Azure / Azure/azure-sdk-for-cpp

WS7: Decide and implement distributed tracing

Open
#7,259 0 comments 0 reactions 1 assignee Claimed by @j7nw4r View on GitHub
Event Hubs
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.