Azure / Azure/azure-sdk-for-cpp

Add distributed tracing instrumentation to the Event Hubs SDK

Open
#7,336 0 comments 0 reactions 1 assignee Claimed by @j7nw4r View on GitHub
Dominant language
C++
Stars
205
Forks
172
Avg merge
1d 15m
Merged PRs (30d)
33

Description

**Is your feature request related to a problem? Please describe.**

The Event Hubs SDK currently emits diagnostic logs, but its ProducerClientOptions and ConsumerClientOptions do not expose the Azure Core tracing configuration and its public operations do not create distributed tracing spans. Applications therefore cannot observe Event Hubs send and receive calls through the existing azure-core-tracing-opentelemetry adapter or correlate Event Hubs activity with the rest of an OpenTelemetry trace.

The stress tests use OpenTelemetry directly, but the published Event Hubs package correctly has no direct runtime dependency on opentelemetry-cpp.

**Describe the solution you would like**

Add provider-neutral distributed tracing to azure-messaging-eventhubs using the tracing abstractions already provided by azure-core.

Initial operation-level instrumentation should:

- Expose Azure Core telemetry/tracing configuration through ProducerClientOptions and ConsumerClientOptions, following the established client-options pattern.
- Create one producer span around each logical ProducerClient::Send call. The span should cover all internal retries rather than creating a separate top-level span for every attempt.
- Create one client/receive span around each PartitionClient::ReceiveEvents call.
- Record final failures and cancellation correctly without reporting transient retry failures as the final operation result.
- Add applicable messaging attributes, including az.namespace, messaging.system, destination, operation, batch message count, and server address.
- Use the package name and version as the instrumentation scope.
- Remain a no-op when no tracing provider is configured.
- Avoid creating process spans because this SDK does not invoke application event handlers.
- Add unit tests using a test tracing provider, without requiring an OpenTelemetry implementation.

OpenTelemetry compatibility should continue to come from azure-core-tracing-opentelemetry. The Event Hubs runtime package should not acquire a direct dependency on opentelemetry-cpp.

**Cross-message propagation and batch links**

End-to-end producer-to-consumer correlation also requires capabilities not currently present in the Azure Core tracing abstraction:

- Generic text-map or AMQP message context injection and extraction.
- Span links so a batch send or receive operation can reference multiple message creation contexts.
- A documented, cross-language-compatible convention for carrying W3C trace context in Event Hubs application properties.

These capabilities should be designed in Azure Core, or tracked as a prerequisite/follow-up, instead of bypassing Azure Core with Event Hubs-specific OpenTelemetry calls. Receive spans should link only to messages delivered to the caller, not messages that remain prefetched internally.

**Describe alternatives you have considered**

- Depending on opentelemetry-cpp directly from Event Hubs. This would couple a service library to one telemetry implementation and duplicate the adapter already provided by Azure Core.
- Instrumenting only azure-core-amqp. Low-level AMQP instrumentation cannot reliably identify Event Hubs logical operations, destination semantics, batch boundaries, or the user-visible retry scope.
- Keeping tracing only in the stress tests. This helps test diagnostics but provides no SDK instrumentation to customers.

**Additional context**

The current OpenTelemetry messaging semantic conventions define eventhubs as a messaging.system value and recommend producer/client spans plus links for batched messaging. The conventions are still evolving, while the current C++ OpenTelemetry adapter advertises schema version 1.17.0, so the exact attribute set and schema version should be agreed during API/design review.

This work changes the public client-options surface and may require an extension to the Azure Core tracing abstraction, so it should receive API and architecture review before implementation.

**Information Checklist**

- [x] Description Added
- [x] Expected solution specified

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.