Chris Coutinho
4ea5ed72d4
Implement comprehensive observability for vector database synchronization
with Grafana dashboard and Prometheus metrics.
## Part 1: Grafana Dashboard
Created all-in-one operations dashboard with 7 rows and 34 panels:
### Dashboard Structure:
- **Overview Row**: Request rate, error rate, P95 latency, active requests
- **HTTP Metrics (RED)**: Request/error rates by endpoint, latency percentiles
- **MCP Tools**: Call volume, error rates, execution duration by tool
- **Nextcloud API**: API calls/latency by app, retry patterns
- **OAuth & Authentication**: Token validations, exchanges, cache hit rate
- **Dependencies & Health**: Status for Nextcloud/Qdrant/Keycloak/Unstructured
- **Vector Sync**: Processing throughput, queue depth, Qdrant operations
### Helm Chart Integration:
- Added dashboard-configmap.yaml template for automatic provisioning
- Configured Grafana sidecar auto-discovery (label: grafana_dashboard="1")
- Added dashboards configuration section in values.yaml (opt-in)
- Updated Chart.yaml with dashboard annotations
- Enhanced NOTES.txt with dashboard deployment instructions
- Comprehensive documentation in dashboards/README.md
Dashboard supports dynamic filtering via variables:
- datasource: Prometheus data source selection
- namespace: Filter by Kubernetes namespace
- pod: Multi-select pod filtering
- interval: Query interval (1m/5m/10m/30m/1h)
## Part 2: Vector Sync Metric Instrumentation
Implemented metric recording throughout vector sync pipeline:
### metrics.py:
Added convenience functions:
- record_vector_sync_scan() - Track documents per scan
- record_vector_sync_processing() - Track processing duration/status
- record_qdrant_operation() - Track database operations
- update_vector_sync_queue_size() - Track queue depth
### scanner.py:
- Record number of documents found in each scan
- Enables monitoring of scan throughput
### processor.py:
- Record processing duration for each document
- Track success/failure status with timing
- Record Qdrant upsert/delete operations
- Handle all code paths (success, deletion, error)
### semantic.py:
- Wrap Qdrant query_points with try/except
- Record search operation success/failure
## Metrics Exposed:
- mcp_vector_sync_documents_scanned_total
- mcp_vector_sync_documents_processed_total{status}
- mcp_vector_sync_processing_duration_seconds (histogram)
- mcp_vector_sync_queue_size (gauge)
- mcp_qdrant_operations_total{operation,status}
This enables monitoring of:
- Scan and processing throughput
- Processing latency (P50/P95/P99)
- Error rates for processing and Qdrant operations
- Queue depth trends
- Complete observability of vector sync pipeline
## Testing:
Verified locally that metrics are recorded correctly:
- 36 documents scanned
- 3 documents processed (avg 7.5s each)
- 3 successful Qdrant upsert operations
- Search operations tracked
## Deployment:
Enable dashboard provisioning in Helm values:
```yaml
dashboards:
enabled: true
grafanaFolder: "Nextcloud MCP"
```
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude <noreply@anthropic.com>
37 lines
984 B
YAML
37 lines
984 B
YAML
apiVersion: v2
|
|
name: nextcloud-mcp-server
|
|
description: A Helm chart for Nextcloud MCP Server - enables AI assistants to interact with Nextcloud
|
|
type: application
|
|
version: 0.32.1
|
|
appVersion: "0.32.1"
|
|
keywords:
|
|
- nextcloud
|
|
- mcp
|
|
- model-context-protocol
|
|
- llm
|
|
- ai
|
|
- claude
|
|
- webdav
|
|
- caldav
|
|
- carddav
|
|
maintainers:
|
|
- name: Chris Coutinho
|
|
email: chris@coutinho.io
|
|
home: https://github.com/cbcoutinho/nextcloud-mcp-server
|
|
sources:
|
|
- https://github.com/cbcoutinho/nextcloud-mcp-server
|
|
icon: https://raw.githubusercontent.com/nextcloud/server/master/core/img/logo/logo.svg
|
|
annotations:
|
|
# Grafana dashboard support
|
|
grafana_dashboard: "true"
|
|
grafana_dashboard_folder: "Nextcloud MCP"
|
|
dependencies:
|
|
- name: qdrant
|
|
version: "1.15.5"
|
|
repository: https://qdrant.github.io/qdrant-helm
|
|
condition: qdrant.networkMode.deploySubchart
|
|
- name: ollama
|
|
version: "1.34.0"
|
|
repository: https://otwld.github.io/ollama-helm
|
|
condition: ollama.enabled
|