Skip to content

docs: Observability example uses OTel environment variable names that no longer exist #352

Description

@AryanKansagara

Summary

The example observability stack in examples/observability/otel-jaeger-prometheus/ instructs users to configure Tangle with TANGLE_OTEL_EXPORTER_ENDPOINT and TANGLE_OTEL_EXPORTER_PROTOCOL. These variables are no longer read by the application. Following the README as written results in no traces or metrics being exported, with no error or warning.

Background

The example and its README were added in #101. Shortly after, #125 ("Refactor OTel exporters to be signal-specific") replaced the generic TANGLE_OTEL_EXPORTER_* variables with separate trace and metric variables:

  • TANGLE_OTEL_TRACE_EXPORTER_ENDPOINT
  • TANGLE_OTEL_TRACE_EXPORTER_PROTOCOL
  • TANGLE_OTEL_METRIC_EXPORTER_ENDPOINT
  • TANGLE_OTEL_METRIC_EXPORTER_PROTOCOL

The code and tests were updated in that PR, but the example README and the header comment in docker-compose.yml were not.

Affected files

  • examples/observability/otel-jaeger-prometheus/README.md (variable table, shell example, .env example, and the closing sentence about disabling export)
  • examples/observability/otel-jaeger-prometheus/docker-compose.yml (header comment, lines 6 and 7)

Steps to reproduce

  1. Start the example stack: cd examples/observability/otel-jaeger-prometheus && docker compose up -d
  2. Export the variables exactly as the README says and start the API server.
  3. Open Jaeger at http://localhost:16686. No tangle-* service appears and no traces are recorded.

A faster check without Docker:

TANGLE_OTEL_EXPORTER_ENDPOINT=http://localhost:4317 python -c \
  "from cloud_pipelines_backend.instrumentation.opentelemetry._internal import configuration as c; print(c.resolve())"

This prints None, which the app treats as "telemetry not configured". Running the same command with TANGLE_OTEL_TRACE_EXPORTER_ENDPOINT instead returns a populated OtelConfig.

The old names also do not appear anywhere in the code base:

grep -rn "TANGLE_OTEL_EXPORTER" --include='*.py' .

returns nothing.

Additional inaccuracy in the same README

The TANGLE_ENV row states the default is development. The code defaults it to unknown (configuration.py, resolve()), so the default service name is tangle-unknown, not tangle-development.

Expected outcome

The README and docker-compose comment should list the four current variable names, show both the trace and metric endpoints in the examples, state that export is disabled only when neither endpoint is set, and document the correct TANGLE_ENV default.

I have a PR ready for this and will link it here.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions