checkId: check.observability.otel plugin: stellaops.doctor.observability severity: warn tags: [observability, opentelemetry, tracing, metrics, reachability]

OpenTelemetry Configuration

What It Checks

Resolves the OTLP collector endpoint from the integration manifest keys (OpenTelemetry:Otlp:Endpoint, OTEL_EXPORTER_OTLP_ENDPOINT, or legacy OpenTelemetry:Endpoint) and probes the OTLP HTTP trace receiver path /v1/traces through the injectable IObservabilityReachabilityProbe seam. The default local probe uses IHttpClientFactory; deployments can replace it for gRPC-specific receiver checks.

The check reports skip when no collector is configured or no reachability probe is available. It reports warn when the receiver is unreachable or configuration is incomplete, and pass only when the receiver answers and tracing/metrics settings are sane. Retry attempts are included in evidence for transient probe failures.

Why It Matters

OpenTelemetry is the main path for exporting traces and metrics to local observability backends. A configured URL that does not accept traces removes cross-service visibility while still looking healthy in static config.

Common Causes

OTEL_EXPORTER_OTLP_ENDPOINT was omitted from compose or environment settings
The collector exposes OTLP gRPC on port 4317 but the deployment did not register a gRPC-aware reachability probe
OTEL_SERVICE_NAME was never set
Collector networking differs between local and deployed environments

How to Fix

Docker Compose

services:
  doctor-web:
    environment:
      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
      OTEL_SERVICE_NAME: doctor-web
      OpenTelemetry__Tracing__Enabled: "true"
      OpenTelemetry__Metrics__Enabled: "true"

docker compose -f devops/compose/docker-compose.stella-ops.yml exec doctor-web \
  curl -i -X POST -H "Content-Type: application/x-protobuf" --data-binary "" \
  http://otel-collector:4318/v1/traces

Bare Metal / systemd

Keep the collector endpoint in the service unit or configuration file and verify firewalls allow traffic on the OTLP port. If the collector is gRPC-only, register a local IObservabilityReachabilityProbe implementation that verifies the gRPC receiver.

Kubernetes / Helm

Use cluster-local collector service names and inject OTEL_SERVICE_NAME per workload. For HTTP OTLP, expose the collector service on the HTTP receiver port and path.

Verification

stella doctor run --check check.observability.otel

check.observability.tracing - validates trace-specific tuning once OTLP export is wired
check.observability.metrics - metrics export often shares the same collector
check.observability.logs.shipping - log pipelines should degrade honestly when no backend is configured