REST Tracing¶

OpenMed can emit OpenTelemetry traces for the REST service without putting request text, model output text, or PHI-bearing bodies into spans. Tracing is off by default. If no tracing environment variable is set, the service does not create an OTLP exporter and does not push telemetry to a collector.

Enable Tracing¶

Install the service extra:

uv pip install -e ".[hf,service]"

Enable in-process spans without exporting them:

OPENMED_SERVICE_TRACING_ENABLED=true \
uvicorn openmed.service.app:app --host 127.0.0.1 --port 8080

Enable OTLP export over HTTP:

OPENMED_SERVICE_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces \
uvicorn openmed.service.app:app --host 127.0.0.1 --port 8080

Setting OPENMED_SERVICE_OTLP_ENDPOINT is treated as an explicit tracing opt-in. To override that, set OPENMED_SERVICE_TRACING_ENABLED=false.

Optional exporter settings:

OPENMED_SERVICE_OTLP_HEADERS=Authorization=Bearer-token,X-Scope=clinic-a \
OPENMED_SERVICE_OTLP_TIMEOUT_SECONDS=5 \
OPENMED_SERVICE_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces \
uvicorn openmed.service.app:app --host 127.0.0.1 --port 8080

Span Shape¶

Each traced HTTP request creates one openmed.service.request server span. For model-backed routes, OpenMed adds child spans for service stages such as openmed.service.model_request, openmed.service.analyze_pipeline, openmed.service.pii_extract_pipeline, openmed.service.pii_deidentify_pipeline, and request coalescing or batch stages when those features are enabled.

Incoming W3C traceparent headers are honored, so an upstream gateway span can be the parent of the OpenMed request span. The existing X-Request-ID correlation ID is also attached as a span attribute when present or generated by the service middleware.

No-PHI Attribute Contract¶

Span attributes are restricted to route templates, HTTP method/status, request ID, model name, static stage names, input lengths/counts, batch sizes, entity counts, categorical entity labels, and stage durations. The service never stores request text, response text, entity text, mappings, prompts, client identity, headers, query strings, or raw path parameters in span attributes.

Tracing is complementary to the Prometheus /metrics endpoint. Metrics stay pull-only and aggregate; traces are optional and exported only when configured.