---
checkId: check.observability.otel
plugin: stellaops.doctor.observability
severity: warn
tags: [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
```yaml
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"
```

```bash
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
```bash
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