Azure / Azure/azure-sdk-for-cpp
WS7: Decide and implement distributed tracing
- Dominant language
- C++
- Stars
- 205
- Forks
- 172
- Avg merge
- 1d 15m
- Merged PRs (30d)
- 33
Description
## Summary
The C++ Event Hubs package contains no distributed tracing code. A search for `Tracing`, `traceparent`, `Diagnostic-Id`, and `OpenTelemetry` across the package sources and headers returns nothing, while the repository already ships a tracing abstraction in `azure-core` and an exporter in `azure-core-tracing-opentelemetry`.
The Azure SDK guidelines bind C++ here, so the implementation item is a GA blocker. Severity tags follow the key in #7252.
## Motivation
The general guidelines state "DO support OpenTelemetry for distributed tracing" [`general-tracing-opentelemetry`], "DO accept a context from calling code to establish a parent span" [`general-tracing-accept-context`], and "DO pass the context to the backend service through the appropriate headers (traceparent and tracestate per W3C Trace-Context standard)" [`general-tracing-pass-context`]. These carry no language carve-out.
The C++ implementation guidelines repeat the requirement in language-specific form: "DO create a new trace span for each API call. New spans must be children of the span that was passed in" [`cpp-tracing-span-per-call`], and "DO abstract the underlying tracing facility, allowing consumers to use the tracing implementation of their choice" [`cpp-tracing-abstraction`]. The C++ design guidelines also list tracing as fundamental [`cpp-design-logical-client`].
The guidance is therefore explicit rather than unstated. That settles the question this issue previously held open.
Repository practice does not match the guidance. Of the C++ client packages, only `azure-security-attestation` creates spans, through `TracingContextFactory::CreateTracingContext` (`sdk/attestation/azure-security-attestation/src/attestation_administration_client.cpp:92,180,254`). `azure-storage-blobs`, `azure-security-keyvault-secrets`, and `azure-identity` create none, and all three have shipped stable releases. `azure-core-amqp` creates none either.
Two readings follow, and the architecture board picks one. Either the earlier packages shipped with an unrecorded exception, and Event Hubs may take the same exception; or the guideline binds and Event Hubs implements tracing. Event Hubs is the weaker candidate for an exception, because trace correlation between a producer and a consumer is the case the guidance exists to serve, and the .NET and Java Event Hubs libraries both implement it.
Logging is a separate matter and is adequate. `Log::Stream` calls are present throughout the package.
## Proposal
- [ ] Implement send, receive, and process spans, and propagate the message-level trace context, using the abstraction the repository already ships (`azure-core` tracing and `azure-core-tracing-opentelemetry`). Follow `cpp-tracing-span-per-call` and `general-tracing-pass-context`. **[GA blocker]**
- [ ] Take the tracing question to the architecture board and record the ruling in this issue. If the board grants the same exception that `azure-storage-blobs`, `azure-security-keyvault-secrets`, and `azure-identity` appear to hold, downgrade the implementation item to **GA quality bar** and record the waiver here. **[GA blocker]**
## Resolution of the earlier open question
This issue previously tagged the implementation item **GA quality bar**, on the reading that the C++ position on tracing was unstated. The guidelines were then read directly. `cpp-tracing-span-per-call` is explicit and normative, so the tag is now **GA blocker**, and a recorded board waiver is the only path that lowers it.
## Validation
- [ ] A produced event carries W3C trace context, and a consumer continues the same trace.
- [ ] Each public client method creates exactly one span, per `general-tracing-new-span-per-method`.
- [ ] The board ruling is recorded in this issue with a link to its source.
Contributor guide
Assessment
This issue has not been assessed yet.