refactor: the app sends traces through the OpenTelemetry Collector

Merged
HA
21h ago
+5-5

Summary

Part of #389. Its plan turns spans into metrics with the collector's signaltometrics connector, so every span has to pass through the collector first. Today the SDK exports straight to Jaeger (OTLP_TRACES_ENDPOINT = "http://jaeger:4317"), a carry-over from replacing the Jaeger agent settings in #175.

Changes

config.toml points OTLP_TRACES_ENDPOINT at http://otel-collector:4317. The collector's traces pipeline already ran tail_sampling into Jaeger, but nothing used it, so Jaeger now keeps traces with an error, traces over 1 s and a 10 % sample of the rest, 10 to 20 s after they end. The connector itself comes with the first area PR, since the collector refuses a signaltometrics block with no metric defined. The tracing doc also stops saying FastAPI is instrumented in the lifespan, which #388 changed.

Type of Change

  • Bug fix (non-breaking change that fixes an issue)
  • New feature (non-breaking change that adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update
  • Refactoring (no functional changes)
  • CI/CD or tooling changes

Test Plan

  • Backend unit tests pass (cd backend && uv run pytest tests/unit)
  • Frontend unit tests pass (cd frontend && npm run test)
  • Backend E2E tests pass (docker compose exec -T backend sh -c 'uv sync --group test --no-dev --frozen --no-install-project --no-build && pytest tests/e2e')
  • Frontend E2E tests pass (cd frontend && npm run test:e2e)
  • API spec and client regenerated if routes or schemas changed (./deploy.sh openapi, then ./deploy.sh types), never edited by hand
  • Manual testing performed

Validation: the repo's collector config and Jaeger 2.20.0 ran locally, and the OpenTelemetry SDK sent 20 plain spans and 1 error span to the collector. About 26 s later Jaeger had the error trace and 2 of the 20 plain ones. Tests export no traces (config.test.toml leaves the endpoint empty), so CI doesn't cover this path.

Checklist

  • My code follows the project's style guidelines
  • I have run pre-commit run --all-files and all checks pass
  • I have added tests that prove my fix/feature works
  • I have updated documentation if needed
  • My changes don't introduce new warnings

Summary by cubic

Sends traces through the OpenTelemetry Collector instead of exporting them straight to Jaeger, so the collector's signaltometrics connector can turn spans into metrics as planned in #389.

Jaeger now only receives what the collector's existing tail sampling keeps: traces with errors, traces over 1 second, and a 10% random sample, arriving 10 to 20 seconds after they end. The tracing docs also drop the outdated note that FastAPI is instrumented in the lifespan, which #388 already moved into create_app.