admin/mcp-nextcloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: simplify OpenTelemetry tracing configuration

Browse Source 
Simplifies the OpenTelemetry tracing setup by removing the redundant
OTEL_ENABLED flag and using the presence of OTEL_EXPORTER_OTLP_ENDPOINT
to determine if tracing should be enabled. This follows the standard
OpenTelemetry environment variable conventions more closely.

Changes:
- Remove OTEL_ENABLED/tracing_enabled flag in favor of checking if
  OTEL_EXPORTER_OTLP_ENDPOINT is set
- Add OTEL_EXPORTER_VERIFY_SSL configuration option for OTLP endpoints
  with self-signed certificates (defaults to false for development)
- Move HTTPXClientInstrumentor initialization to module level to ensure
  httpx calls are traced across all Nextcloud API requests
- Add tracing spans to vector sync operations (scan_user_documents)
- Fix authorization header logging to only warn about missing headers
  in OAuth mode (BasicAuth mode doesn't use Authorization headers)
- Update observability documentation to reflect simplified configuration
- Refactor Dockerfile to use --no-editable flag for uv sync

Breaking changes:
- OTEL_ENABLED environment variable is removed
- Tracing is now automatically enabled when OTEL_EXPORTER_OTLP_ENDPOINT
  is set

Migration guide:
- Remove OTEL_ENABLED=true from environment configuration
- Tracing will be enabled automatically if OTEL_EXPORTER_OTLP_ENDPOINT
  is configured

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

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Chris Coutinho
2025-11-10 22:48:37 +01:00
co-authored by Claude
parent f44bf3e8f2
commit a6e5f3d8ff
13 changed files with 255 additions and 206 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+2
View File
@@ -5,5 +5,7 @@ __pycache__/
.env.local
.env.*.local
docker-compose.override.yml
# Generated by pytest used to login users
.nextcloud_oauth_*.json
Dockerfile
+1 -1
View File
@@ -9,7 +9,7 @@ WORKDIR /app
COPY . .
RUN uv sync --locked --no-dev
RUN uv sync --locked --no-dev --no-editable
ENV PYTHONUNBUFFERED=1
ENV VIRTUAL_ENV=/app/.venv
charts/nextcloud-mcp-server/templates/deployment.yaml
-2
View File
@@ -218,8 +218,6 @@ spec:
- name: METRICS_PORT
value: {{ .Values.observability.metrics.port | quote }}
{{- if .Values.observability.tracing.enabled }}
- name: OTEL_ENABLED
value: "true"
- name: OTEL_EXPORTER_OTLP_ENDPOINT
value: {{ .Values.observability.tracing.endpoint | quote }}
- name: OTEL_SERVICE_NAME
docker-compose.yml
+6 -2
View File
@@ -98,16 +98,20 @@ services:
#- QDRANT_URL=http://qdrant:6333 # Uncomment for network mode
#- QDRANT_API_KEY=${QDRANT_API_KEY:-my_secret_api_key} # Only for network mode
# Observability
#- OTEL_SERVICE_NAME=nextcloud-mcp-docker-compose
#- OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317
# Collection naming: Auto-generated as {deployment-id}-{model-name}
# - Deployment ID: OTEL_SERVICE_NAME (if set) or hostname (fallback)
# - Model name: OLLAMA_EMBEDDING_MODEL
# - Example: "nextcloud-mcp-server-nomic-embed-text"
# - Changing models creates new collection (requires re-embedding)
# - Set QDRANT_COLLECTION to override auto-generation:
- QDRANT_COLLECTION=nextcloud_content
#- QDRANT_COLLECTION=nextcloud_content
# Ollama configuration (optional - uses SimpleEmbeddingProvider if not set)
# - OLLAMA_BASE_URL=https://ollama.internal.coutinho.io:443
# - OLLAMA_BASE_URL=http://ollama:11434
# - OLLAMA_EMBEDDING_MODEL=nomic-embed-text # Changing this creates new collection
# - OLLAMA_VERIFY_SSL=false
docs/observability.md
+2 -4
View File
@@ -16,8 +16,7 @@ The Nextcloud MCP Server includes comprehensive observability features for produ
export METRICS_ENABLED=true
export METRICS_PORT=9090
# Enable tracing (optional)
export OTEL_ENABLED=true
# Enable tracing (optional - tracing is enabled when OTEL_EXPORTER_OTLP_ENDPOINT is set)
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
# Start the server
@@ -46,8 +45,7 @@ helm install nextcloud-mcp charts/nextcloud-mcp-server \
|----------|---------|-------------|
| `METRICS_ENABLED` | `true` | Enable Prometheus metrics |
| `METRICS_PORT` | `9090` | Port for metrics endpoint |
| `OTEL_ENABLED` | `false` | Enable OpenTelemetry tracing |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | - | OTLP gRPC endpoint (e.g., `http://otel-collector:4317`) |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | - | OTLP gRPC endpoint (e.g., `http://otel-collector:4317`). Tracing is enabled when this is set. |
| `OTEL_SERVICE_NAME` | `nextcloud-mcp-server` | Service name in traces |
| `OTEL_TRACES_SAMPLER` | `always_on` | Trace sampling strategy |
| `OTEL_TRACES_SAMPLER_ARG` | `1.0` | Sampling rate (0.0-1.0) |
nextcloud_mcp_server/app.py
+13 -3
View File
@@ -5,9 +5,12 @@ from contextlib import AsyncExitStack, asynccontextmanager
from dataclasses import dataclass
from typing import TYPE_CHECKING, Optional
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
if TYPE_CHECKING:
from nextcloud_mcp_server.auth.refresh_token_storage import RefreshTokenStorage
import anyio
import click
import httpx
@@ -58,6 +61,7 @@ from nextcloud_mcp_server.server.oauth_tools import register_oauth_tools
from nextcloud_mcp_server.vector import processor_task, scanner_task
logger = logging.getLogger(__name__)
HTTPXClientInstrumentor().instrument()
def initialize_document_processors():
@@ -791,17 +795,20 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
)
# Setup OpenTelemetry tracing (optional)
if settings.tracing_enabled:
if settings.otel_exporter_otlp_endpoint:
setup_tracing(
service_name=settings.otel_service_name,
otlp_endpoint=settings.otel_exporter_otlp_endpoint,
otlp_verify_ssl=settings.otel_exporter_verify_ssl,
sampling_rate=settings.otel_traces_sampler_arg,
)
logger.info(
f"OpenTelemetry tracing enabled (endpoint: {settings.otel_exporter_otlp_endpoint})"
)
else:
logger.info("OpenTelemetry tracing disabled (set OTEL_ENABLED=true to enable)")
logger.info(
"OpenTelemetry tracing disabled (set OTEL_EXPORTER_OTLP_ENDPOINT to enable)"
)
# Determine authentication mode
oauth_enabled = is_oauth_mode()
@@ -1391,6 +1398,9 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
)
logger.info(f"🔑 /mcp request with Authorization: {token_preview}")
else:
# Only warn about missing Authorization in OAuth mode
# In BasicAuth mode, /mcp requests without Authorization are expected
if oauth_enabled:
logger.warning(
f"⚠️ /mcp request WITHOUT Authorization header from {request.client}"
)
@@ -1454,7 +1464,7 @@ def get_app(transport: str = "sse", enabled_apps: list[str] | None = None):
)
# Add observability middleware (metrics + tracing)
if settings.metrics_enabled or settings.tracing_enabled:
if settings.metrics_enabled or settings.otel_exporter_otlp_endpoint:
app.add_middleware(ObservabilityMiddleware)
logger.info("Observability middleware enabled (metrics and/or tracing)")
nextcloud_mcp_server/auth/unified_verifier.py
+8 -4
View File
@@ -231,17 +231,21 @@ class UnifiedTokenVerifier(TokenVerifier):
token,
signing_key.key,
algorithms=["RS256"],
issuer=self.settings.oidc_issuer
issuer=(
self.settings.oidc_issuer
if hasattr(self.settings, "oidc_issuer")
else None,
else None
),
options={
"verify_signature": True,
"verify_exp": True,
"verify_iat": True,
"verify_iss": True
"verify_iss": (
True
if hasattr(self.settings, "oidc_issuer")
and self.settings.oidc_issuer
else False,
else False
),
"verify_aud": False, # We handle audience validation separately
},
)
nextcloud_mcp_server/client/__init__.py
+2
View File
@@ -9,6 +9,7 @@ from httpx import (
BasicAuth,
Request,
Response,
Timeout,
)
from ..controllers.notes_search import NotesSearchController
@@ -66,6 +67,7 @@ class NextcloudClient:
auth=auth,
transport=AsyncDisableCookieTransport(AsyncHTTPTransport()),
event_hooks={"request": [log_request], "response": [log_response]},
timeout=Timeout(timeout=30, connect=5),
)
# Initialize app clients
nextcloud_mcp_server/config.py
+3 -2
View File
@@ -181,8 +181,8 @@ class Settings:
# Observability settings
metrics_enabled: bool = True
metrics_port: int = 9090
tracing_enabled: bool = False
otel_exporter_otlp_endpoint: Optional[str] = None
otel_exporter_verify_ssl: bool = False
otel_service_name: str = "nextcloud-mcp-server"
otel_traces_sampler: str = "always_on"
otel_traces_sampler_arg: float = 1.0
@@ -334,8 +334,9 @@ def get_settings() -> Settings:
# Observability settings
metrics_enabled=os.getenv("METRICS_ENABLED", "true").lower() == "true",
metrics_port=int(os.getenv("METRICS_PORT", "9090")),
tracing_enabled=os.getenv("OTEL_ENABLED", "false").lower() == "true",
otel_exporter_otlp_endpoint=os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT"),
otel_exporter_verify_ssl=os.getenv("OTEL_EXPORTER_VERIFY_SSL", "false").lower()
== "true",
otel_service_name=os.getenv("OTEL_SERVICE_NAME", "nextcloud-mcp-server"),
otel_traces_sampler=os.getenv("OTEL_TRACES_SAMPLER", "always_on"),
otel_traces_sampler_arg=float(os.getenv("OTEL_TRACES_SAMPLER_ARG", "1.0")),
nextcloud_mcp_server/observability/tracing.py
+10 -6
View File
@@ -13,9 +13,9 @@ import logging
from contextlib import contextmanager
from typing import Any
from importlib_metadata import version
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor
from opentelemetry.instrumentation.logging import LoggingInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
@@ -27,10 +27,13 @@ logger = logging.getLogger(__name__)
# Global tracer instance (initialized in setup_tracing)
_tracer: Tracer | None = None
# Auto-instrument httpx for Nextcloud API calls
def setup_tracing(
service_name: str = "nextcloud-mcp-server",
otlp_endpoint: str | None = None,
otlp_verify_ssl: bool = False,
sampling_rate: float = 1.0,
) -> Tracer:
"""
@@ -40,6 +43,8 @@ def setup_tracing(
service_name: Service name for traces (default: "nextcloud-mcp-server")
otlp_endpoint: OTLP gRPC endpoint (e.g., "http://otel-collector:4317")
If None, tracing is initialized but no exporter is configured
otlp_verify_ssl: Enable TLS verification for otlp_endpoint. If True,
`insecure` will eval to False
sampling_rate: Sampling rate (0.0-1.0). Default 1.0 (100% sampling)
Returns:
@@ -51,7 +56,7 @@ def setup_tracing(
resource = Resource.create(
{
"service.name": service_name,
"service.version": "0.27.2", # TODO: Extract from pyproject.toml
"service.version": version(__package__.split(".")[0]),
}
)
@@ -61,7 +66,9 @@ def setup_tracing(
# Configure OTLP exporter if endpoint is provided
if otlp_endpoint:
try:
otlp_exporter = OTLPSpanExporter(endpoint=otlp_endpoint, insecure=True)
otlp_exporter = OTLPSpanExporter(
endpoint=otlp_endpoint, insecure=not otlp_verify_ssl
)
span_processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(span_processor)
logger.info(
@@ -79,9 +86,6 @@ def setup_tracing(
# Set global tracer provider
trace.set_tracer_provider(provider)
# Auto-instrument httpx for Nextcloud API calls
HTTPXClientInstrumentor().instrument()
# Auto-instrument logging to inject trace context
LoggingInstrumentor().instrument(set_logging_format=True)
nextcloud_mcp_server/vector/processor.py
+11
View File
@@ -15,6 +15,7 @@ from qdrant_client.models import FieldCondition, Filter, MatchValue, PointStruct
from nextcloud_mcp_server.client import NextcloudClient
from nextcloud_mcp_server.config import get_settings
from nextcloud_mcp_server.embedding import get_embedding_service
from nextcloud_mcp_server.observability.tracing import trace_operation
from nextcloud_mcp_server.vector.document_chunker import DocumentChunker
from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
from nextcloud_mcp_server.vector.scanner import DocumentTask
@@ -94,6 +95,16 @@ async def process_document(doc_task: DocumentTask, nc_client: NextcloudClient):
f"for {doc_task.user_id} ({doc_task.operation})"
)
with trace_operation(
"vector_sync.process_document",
attributes={
"vector_sync.operation": "process",
"vector_sync.user_id": doc_task.user_id,
"vector_sync.doc_id": doc_task.doc_id,
"vector_sync.doc_type": doc_task.doc_type,
"vector_sync.doc_operation": doc_task.operation,
},
):
qdrant_client = await get_qdrant_client()
settings = get_settings()
nextcloud_mcp_server/vector/scanner.py
+18 -3
View File
@@ -13,6 +13,7 @@ from qdrant_client.models import FieldCondition, Filter, MatchValue
from nextcloud_mcp_server.client import NextcloudClient
from nextcloud_mcp_server.config import get_settings
from nextcloud_mcp_server.observability.tracing import trace_operation
from nextcloud_mcp_server.vector.qdrant_client import get_qdrant_client
logger = logging.getLogger(__name__)
@@ -154,9 +155,20 @@ async def scan_user_documents(
f"[SCAN-{scan_id}] Starting scan for user: {user_id}, initial_sync={initial_sync}"
)
with trace_operation(
"vector_sync.scan_user_documents",
attributes={
"vector_sync.operation": "scan",
"vector_sync.user_id": user_id,
"vector_sync.initial_sync": initial_sync,
"vector_sync.scan_id": scan_id,
},
):
# Calculate prune timestamp for optimized data transfer
# Only notes modified after this will be sent with full data
prune_before = None if initial_sync else await get_last_indexed_timestamp(user_id)
prune_before = (
None if initial_sync else await get_last_indexed_timestamp(user_id)
)
if prune_before:
logger.info(
f"[SCAN-{scan_id}] Using pruneBefore={prune_before} to optimize data transfer"
@@ -164,7 +176,8 @@ async def scan_user_documents(
# Fetch all notes from Nextcloud
notes = [
note async for note in nc_client.notes.get_all_notes(prune_before=prune_before)
note
async for note in nc_client.notes.get_all_notes(prune_before=prune_before)
]
logger.info(f"[SCAN-{scan_id}] Found {len(notes)} notes for {user_id}")
@@ -239,7 +252,9 @@ async def scan_user_documents(
# Check for deleted documents (in Qdrant but not in Nextcloud)
# Use grace period: only delete after 2 consecutive scans confirm absence
settings = get_settings()
grace_period = settings.vector_sync_scan_interval * 1.5 # Allow 1.5 scan intervals
grace_period = (
settings.vector_sync_scan_interval * 1.5
) # Allow 1.5 scan intervals
current_time = time.time()
for doc_id in indexed_docs: