Files

T

Chris CoutinhoandClaude 093ac5b5ba feat(helm): Add observability support with ServiceMonitor and Grafana dashboard

Add comprehensive observability configuration to Helm chart:

**Helm Values:**
- Add observability configuration section for metrics, tracing, and logging
- Add serviceMonitor configuration (disabled by default)
- Add prometheusRule configuration (disabled by default)

**Templates:**
- Update deployment to include observability environment variables
- Update deployment to expose metrics port (9090)
- Update service to expose metrics port
- Add ServiceMonitor template for Prometheus Operator
- Add PrometheusRule template with critical and warning alerts

**Dashboards:**
- Add comprehensive Grafana dashboard JSON with 6 panels:
  - Request Rate (by method and endpoint)
  - Error Rate (5xx errors percentage)
  - Request Latency (P50/P95 by endpoint)
  - Top MCP Tools (by invocation volume)
  - Nextcloud API Latency (by app)
  - Vector Sync Queue Size
- Add dashboard README with import instructions

**Alert Rules:**
- Critical: Server down, high error rate (>5%), high latency (>1s), dependency down
- Warning: Token validation errors (>1%), vector sync queue high (>100), Qdrant slow (>500ms)

All features are opt-in via values.yaml configuration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-11-09 09:10:11 +01:00

nextcloud-mcp-server.json

feat(helm): Add observability support with ServiceMonitor and Grafana dashboard

2025-11-09 09:10:11 +01:00

README.md

feat(helm): Add observability support with ServiceMonitor and Grafana dashboard

2025-11-09 09:10:11 +01:00

README.md

Grafana Dashboards

This directory contains example Grafana dashboards for monitoring the Nextcloud MCP Server.

Dashboards

nextcloud-mcp-server.json

Comprehensive dashboard with the following panels:

Request Rate: HTTP requests per second by method and endpoint
Error Rate: Percentage of 5xx errors
Request Latency: P50 and P95 latency by endpoint
Top MCP Tools: Most frequently called tools
Nextcloud API Latency: API call latency by app (notes, calendar, etc.)
Vector Sync Queue: Queue size for background document processing

Importing to Grafana

Manual Import

Open Grafana UI
Navigate to Dashboards → Import
Upload nextcloud-mcp-server.json
Select your Prometheus data source
Click "Import"

Automated Import (Kubernetes)

If using the Grafana Operator or kube-prometheus-stack, you can create a ConfigMap:

kubectl create configmap nextcloud-mcp-dashboards \
  --from-file=nextcloud-mcp-server.json \
  -n monitoring

# Add label for Grafana sidecar to discover
kubectl label configmap nextcloud-mcp-dashboards \
  grafana_dashboard=1 \
  -n monitoring

Or add to your Helm values:

# values.yaml for kube-prometheus-stack
grafana:
  dashboardProviders:
    dashboardproviders.yaml:
      apiVersion: 1
      providers:
        - name: 'nextcloud-mcp'
          orgId: 1
          folder: 'Nextcloud MCP'
          type: file
          disableDeletion: false
          editable: true
          options:
            path: /var/lib/grafana/dashboards/nextcloud-mcp

  dashboardsConfigMaps:
    nextcloud-mcp: nextcloud-mcp-dashboards

Dashboard Variables

The dashboard includes two variables:

Data Source: Select your Prometheus data source
Namespace: Filter metrics by Kubernetes namespace

Customization

You can customize the dashboard by:

Adjusting refresh rate (default: 30s)
Modifying time range (default: last 6 hours)
Adding new panels for specific metrics
Adjusting thresholds in existing panels

Metrics Reference

All metrics are documented in /docs/observability.md. Key metric prefixes:

mcp_http_* - HTTP server metrics
mcp_tool_* - MCP tool invocation metrics
mcp_nextcloud_api_* - Nextcloud API call metrics
mcp_oauth_* - OAuth token validation metrics
mcp_vector_sync_* - Vector database sync metrics
mcp_db_* - Database operation metrics