git.stella-ops.org/docs/doctor/articles/observability/observability-otel.md

checkId, plugin, severity, tags

checkId	plugin	severity	tags
check.observability.otel	stellaops.doctor.observability	warn	observability opentelemetry tracing metrics

OpenTelemetry Configuration

What It Checks

Reads OpenTelemetry:*, Telemetry:*, and OTEL_* settings for endpoint, service name, tracing enablement, metrics enablement, and sampling ratio. When possible, it probes the collector host directly.

The check reports info when no OTLP endpoint is configured and warns when the service name is missing, tracing or metrics are disabled, sampling is too low, or the collector is unreachable.

Why It Matters

OpenTelemetry is the main path for exporting traces and metrics to external systems. Broken collector settings silently remove cross-service visibility.

Common Causes

• OTEL_EXPORTER_OTLP_ENDPOINT was omitted from compose or environment settings
• 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:4317
      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 -fsS http://otel-collector:4318/

Bare Metal / systemd

Keep the collector endpoint in the service unit or configuration file and verify firewalls allow traffic on the OTLP port.

Kubernetes / Helm

Use cluster-local collector service names and inject OTEL_SERVICE_NAME per workload.

Verification

stella doctor --check check.observability.otel

Related Checks

• check.observability.tracing - validates trace-specific tuning once OTLP export is wired
• check.observability.metrics - metrics export often shares the same collector