Skip to content

docs(dev): verify tracing guide against code and remove migrated status (#206) - #219

Merged
antiv merged 3 commits into
antiv:mainfrom
Fire162:docs/tracing-clean
Oct 11, 2026
Merged

antiv merged 3 commits into
antiv:mainfrom
Fire162:docs/tracing-clean

Conversation

@Fire162

@Fire162 Fire162 commented Oct 11, 2026

Copy link
Copy Markdown
Contributor

Part of #206.

Changes

  • Re-checked docs/dev/tracing.md against shared/utils/tracing/**.
  • Documented TracerProvider behavior: attaches DatabaseSpanExporter directly to ADK's TracerProvider when present, or initializes an SDK TracerProvider with the service name.
  • Clarified batching and table name (trace_spans) for DB export.
  • Removed status: migrated from frontmatter.
  • Verified that python3 scripts/gen_docs.py --check passes cleanly.

@antiv

antiv commented Oct 11, 2026

Copy link
Copy Markdown
Owner

This branch is based on a 72-commit-old main, and it brings back statements that #157 (0d8fcda) removed from this guide because the code doesn't do them:

  1. There is no default OTLP endpoint. tracer.py only adds the OTLP exporter when OTEL_EXPORTER_OTLP_ENDPOINT is set; otherwise spans only go to the database.
  2. Only OTLP over HTTP is supported (opentelemetry.exporter.otlp.proto.http). gRPC isn't, and nothing reads OTEL_EXPORTER_OTLP_PROTOCOL.
  3. Trace context is only injected by the auth proxy (_inject_trace_headers in server/proxy_routes.py); nothing extracts it from inbound requests.
  4. When ADK already has an SDK TracerProvider, MATE only adds the DB exporter to it and returns, so MATE's OTLP exporter and OTEL_SERVICE_NAME don't apply in that case. Worth saying.
  5. "Zero runtime overhead" is too strong: tool wrapping is skipped, but trace_context still goes through a no-op tracer.

Please rebase on current main (the PR conflicts in docs/dev/tracing.md) and start from the guide there.

Per the note on #206: please address the open reviews on #209, #213 and #217 before opening more PRs.

@Fire162

Fire162 commented Oct 11, 2026

Copy link
Copy Markdown
Contributor Author

Updated docs/dev/tracing.md to address all review points:

  1. OTLP Endpoint: Clarified that there is no default OTLP endpoint; without OTEL_EXPORTER_OTLP_ENDPOINT explicitly configured, spans only go to the database.
  2. Protocol: Documented that only OTLP over HTTP is supported (opentelemetry.exporter.otlp.proto.http), gRPC is not supported, and OTEL_EXPORTER_OTLP_PROTOCOL is not read.
  3. Trace Context: Clarified that trace context is injected into outbound requests to ADK by the auth server proxy (_inject_trace_headers in server/proxy_routes.py), and inbound external requests do not have context extracted. Added server/proxy_routes.py to covers:.
  4. Existing TracerProvider: Documented that when ADK has already initialized an SDK TracerProvider, MATE only attaches the DB exporter and returns, so MATE's OTLP exporter and OTEL_SERVICE_NAME do not apply in that scenario.
  5. Overhead phrasing: Clarified that while tool wrapping is skipped when tracing is disabled, calls via trace_context still execute through a no-op tracer.

Rechecked with python scripts/gen_docs.py --check.

@antiv
antiv merged commit f4c3dab into antiv:main Oct 11, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants