Distributed Tracing Conventions

Conventions are the contract between Azure SDK and tracing providers such as Azure Monitor, Jaeger and others. They describe and standardize attributes, events and relationships for common span types: HTTP, DB, messaging and others. Observability vendors use conventions to build visualizations and may be very sensitive to them. Custom Azure SDK conventions are described in tracing-conventions.yml and include:

• Custom Azure SDK attributes
• Azure SDK HTTP conventions compatible with OpenTelemetry
• Custom messaging and DB conventions. They don’t follow OpenTelemetry convention and used until OpenTelemetry conventions evolve and stabilize

When writing instrumentation in Azure SDK or Core:

✅ DO use OpenTelemetry conventions whenever possible.

✅ DO update distributed-tracing-conventions.yml when adding new attributed.

✅ DO set OpenTelemetry Schema URL when creating OpenTelemetry tracer.

☑️ YOU SHOULD set Azure Client Library name and version Schema URL when creating OpenTelemetry tracer.

☑️ YOU SHOULD contribute new conventions (or patch existing ones) to OpenTelemetry when there is no suitable one or some scenarios are missing.

✔️ YOU MAY extend list of attributes on top of OpenTelemetry contentions with Azure-specific ones.

⛔️ DO NOT add new custom Azure SDK conventions.