Add Azure SDK semantic conventions #2233
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,117 @@ | ||
| # Version: 0.0.0 | ||
| # Status: Experimental | ||
| # This document describes Azure SDK trace semantic conventions. For more details refer to https://azure.github.io/azure.sdk/distributed_tracing_conventions.html | ||
|
|
||
| groups: | ||
|
There was a problem hiding this comment. All of these define an There was a problem hiding this comment. I'm not aware of any requirement for id and prefix to match. Did I miss something? There was a problem hiding this comment. That is correct. Currently you have |
||
| # common | ||
| - id: azure | ||
| brief: 'Describes Azure spans.' | ||
| prefix: az | ||
| attributes: | ||
| - id: namespace | ||
| required: always | ||
| type: string | ||
| sampling_relevant: true | ||
| brief: '[Namespace](https://docs.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers) of Azure service that the request is made against.' | ||
| examples: ['Microsoft.Storage', 'Microsoft.KeyVault', 'Microsoft.ServiceBus'] | ||
|
|
||
| # public API | ||
| - id: azure.sdk.api | ||
| span_kind: internal | ||
| extends: azure | ||
| brief: 'Describes Azure SDK API calls that wrap an Azure service call(s).' | ||
|
|
||
| # http | ||
| - id: azure.sdk.http | ||
|
There was a problem hiding this comment. Just confirming if you meant to remove There was a problem hiding this comment. this specific section describes the client side of things (e.g. populates I assume if we add common attributes between server and client and declare them in There was a problem hiding this comment. For HTTP, we chose the same names for client and server, since the overlapping attributes (like http.url) do have the same meaning. We use the span kind to distinguish. |
||
| extends: azure | ||
| span_kind: client | ||
| brief: 'Describes HTTP client spans created per HTTP request.' | ||
| note: > | ||
| Follows [OpenTelemetry HTTP conventions v1.8.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/semantic_conventions/http.md) | ||
| but omits optional attributes, providing only `http.url` to describe destination. It adds request-id attributes supported by Azure services. | ||
| attributes: | ||
| - id: request_id | ||
| type: string | ||
| required: always | ||
| brief: 'Value of the "x-ms-client-request-id" header (or other "*-request-id" header, depending on the service) sent by the client.' | ||
| examples: ['eb178587-c05a-418c-a695-ae9466c5303c'] | ||
| - id: service_request_id | ||
| type: string | ||
| required: always | ||
| brief: 'Value of the "x-ms-request-id" header (or other "*-request-id" header, depending on the service) sent by the server in response.' | ||
| examples: ['3f828ae5-ecb9-40ab-88d9-db0420af30c6'] | ||
| - ref: http.method | ||
| required: always | ||
| sampling_relevant: true | ||
| - ref: http.url | ||
| required: always | ||
| sampling_relevant: true | ||
| - ref: http.status_code | ||
| required: always | ||
| - ref: http.user_agent | ||
| required: always | ||
| sampling_relevant: true | ||
| brief: 'Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) or X-MS-UserAgent header sent by the client.' | ||
|
|
||
| # messaging | ||
| - id: azure.sdk.messaging | ||
| brief: 'Describes Azure messaging SDKs spans.' | ||
| extends: azure | ||
| note: Implements OpenTracing MessageBus conventions https://opentracing.io/specification/conventions/ | ||
| attributes: | ||
| - id: message_bus.destination | ||
| type: string | ||
| required: always | ||
| brief: 'Name of the messaging entity within namespace: e.g EventHubs name, ServiceBus queue or topic name.' | ||
| examples: ['myqueue', 'myhub'] | ||
| - id: peer.address | ||
| type: string | ||
| brief: 'Fully qualified messaging service name.' | ||
| required: always | ||
| examples: ['myEventHubNamespace.servicebus.windows.net'] | ||
|
Comment on lines
+67
to
+71
There was a problem hiding this comment. How about referencing There was a problem hiding this comment. once we'll switch to There was a problem hiding this comment. Ah so that's not a new suggestion that just borrows from OpenTracing semconvs but it's documenting an existing instrumentation that's already in use? |
||
| - id: azure.sdk.messaging.producer | ||
| span_kind: producer | ||
| extends: azure.sdk.messaging | ||
| brief: 'Describes producer span created per message.' | ||
|
|
||
| - id: azure.sdk.messaging.send | ||
| span_kind: client | ||
| extends: azure.sdk.messaging | ||
| brief: 'Describes send (transport call) span.' | ||
| note: 'Contains links to all messages contexts being sent.' | ||
|
|
||
| - id: azure.sdk.messaging.process | ||
| span_kind: consumer | ||
| extends: azure.sdk.messaging | ||
| brief: 'Describes consumption span.' | ||
| note: > | ||
| Contains links to all messages contexts being consumed. Each link has `enqueued_time` (with `long` type) | ||
| attribute with unix epoch time with milliseconds precision representing when message was enqueued. | ||
|
|
||
| # CosmosDB | ||
| - id: azure.sdk.cosmos | ||
| span_kind: client | ||
| brief: 'Describes Azure CosmosDB spans.' | ||
| note: > | ||
| Events with additional debug info are added for long running or failed operations. | ||
| Implements https://github.com/open-telemetry/opentelemetry-specification/blob/v0.5.0/specification/trace/semantic_conventions/database.md | ||
| extends: azure | ||
| attributes: | ||
| - id: db.url | ||
| type: string | ||
| required: always | ||
| brief: 'Cosmos DB URI' | ||
| examples: ['https://my-cosmos.documents.azure.com:443/'] | ||
| - ref: db.statement | ||
| required: always | ||
| examples: ['createContainerIfNotExists.myContainer'] | ||
| - id: db.instance | ||
| type: string | ||
| required: always | ||
| brief: 'Database name' | ||
| examples: ['mydb'] | ||
| - id: db.type | ||
| type: string | ||
| required: always | ||
| brief: 'Database type' | ||
| examples: ['Cosmos'] | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,116 @@ | ||
| # Semantic conventions for Azure SDK | ||
lmolkova marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| **Status**: [Experimental](../../../document-status.md) | ||
|
|
||
| This document describes tracing semantic conventions adopted by Azure SDK. Instrumentations live in Azure SDK repos and are shipped along with Azure SDK artifacts. Instrumentations cover all modern (track 2) Azure client libraries. | ||
lmolkova marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| - [Java](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/core/azure-core-tracing-opentelemetry) | ||
| - [JavaScript](https://github.com/Azure/azure-sdk-for-js/tree/main/sdk/core/core-tracing) | ||
| - [Python](https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/core/azure-core-tracing-opentelemetry) | ||
| - [.NET](https://github.com/Azure/azure-sdk-for-net/blob/5ce907df6490e68c2e632d97048a6b6ee95c01f0/sdk/core/Azure.Core/samples/Diagnostics.md#activitysource-support) | ||
|
|
||
| Azure SDK produces spans for public API calls and nested HTTP client spans. Non-HTTP transport-level calls (AMQP, CosmosDB TCP-based protocol) are not traced. | ||
|
|
||
| ## Versioning | ||
|
|
||
| Azure SDK semantic conventions pin specific versions of OpenTelemetry semantic conventions (where applicable) and are not updated regularly to the latest OpenTelemetry semantic conventions version. However OpenTelemetry-compatible changes should be expected. | ||
|
|
||
| Azure SDK plans to fully adopt OpenTelemetry semantic conventions once they reach `Stable` status. | ||
|
|
||
| ## Common Attributes | ||
|
|
||
| All Azure SDKs spans have `az.namespace` attribute to uniquely identify *Azure SDK* request is made *from*, usually the value matches the destination Azure service, but in some cases client library can support multiple services. | ||
|
|
||
| <!-- semconv azure --> | ||
| | Attribute | Type | Description | Examples | Required | | ||
| |---|---|---|---|---| | ||
| | `az.namespace` | string | [Namespace](https://docs.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers) of Azure service that the request is made against. | `Microsoft.Storage`; `Microsoft.KeyVault`; `Microsoft.ServiceBus` | Yes | | ||
|
|
||
| Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: | ||
|
|
||
| * `az.namespace` | ||
| <!-- endsemconv --> | ||
|
|
||
| ## Public API calls | ||
|
|
||
| Azure SDKs create a span for public API call (that involves communication with Azure services). | ||
|
|
||
| - Spans representing public APIs have names following `client.method` pattern, which is language-specific. | ||
| - For HTTP-based SDKs, public API spans have `INTERNAL` kind. | ||
|
|
||
| [Messaging](#messaging-sdks) and [CosmosDb](#cosmosdb) sections below describe non-HTTP semantics. | ||
|
|
||
| ## HTTP Client | ||
|
|
||
| Azure SDK implements a valid subset of [OpenTelemetry HTTP conventions v1.8.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/semantic_conventions/http.md) and create a span per HTTP call (attempt). | ||
|
|
||
| <!-- semconv azure.sdk.http --> | ||
| | Attribute | Type | Description | Examples | Required | | ||
| |---|---|---|---|---| | ||
| | `request_id` | string | Value of the "x-ms-client-request-id" header (or other "*-request-id" header, depending on the service) sent by the client. | `eb178587-c05a-418c-a695-ae9466c5303c` | Yes | | ||
| | `service_request_id` | string | Value of the "x-ms-request-id" header (or other "*-request-id" header, depending on the service) sent by the server in response. | `3f828ae5-ecb9-40ab-88d9-db0420af30c6` | Yes | | ||
| | [`http.method`](../http.md) | string | HTTP request method. | `GET`; `POST`; `HEAD` | Yes | | ||
| | [`http.status_code`](../http.md) | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | Yes | | ||
| | [`http.url`](../http.md) | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]`. Usually the fragment is not transmitted over HTTP, but if it is known, it should be included nevertheless. [1] | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Yes | | ||
| | [`http.user_agent`](../http.md) | string | Value of the [HTTP User-Agent](https://tools.ietf.org/html/rfc7231#section-5.5.3) or X-MS-UserAgent header sent by the client. | `CERN-LineMode/2.15 libwww/2.17b3` | Yes | | ||
|
|
||
| **[1]:** `http.url` MUST NOT contain credentials passed via URL in form of `https://username:[email protected]/`. In such case the attribute's value should be `https://www.example.com/`. | ||
|
|
||
| Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: | ||
|
|
||
| * [`http.method`](../http.md) | ||
| * [`http.url`](../http.md) | ||
| * [`http.user_agent`](../http.md) | ||
| <!-- endsemconv --> | ||
|
|
||
| Instrumentation supports [W3C Trace context](https://w3c.github.io/trace-context/) propagation and Azure legacy correlation protocols. Propagator configuration is not supported. | ||
|
|
||
| ## Messaging SDKs | ||
|
|
||
| Messaging span semantics apply to Azure Event Hubs and Service Bus SDKs. | ||
|
|
||
| Attribute names predate OpenTelemetry and originate from [OpenTracing semantic conventions](https://opentracing.io/specification/conventions/) | ||
|
|
||
| Messaging SDKs produce three kinds of spans: | ||
|
|
||
| - `PRODUCER` - describes message creation and associates unique context with the message to trace them when they are sent in batches. | ||
| - Producer spans name follows `<client>.message` pattern (e.g. `EventHubs.message`) | ||
|
|
||
| - `CLIENT` - describes message (or batch) publishing. | ||
| - It has links pointing to each message being sent. | ||
| - Links don't have attributes. | ||
| - Send spans name follows `<client>.send` pattern (e.g. `EventHubs.send`) | ||
|
|
||
| - `CONSUMER` - describes message (or batch) processing. | ||
| - It is created when user leverages handler APIs that wrap message or batch processing. | ||
| - Processing span has links to each message being processed (when context is present). | ||
| - Each link has `enqueued_time` attribute with `long` value with unix epoch time (with milliseconds precision) representing when message was enqueued on the broker. | ||
|
|
||
| ### Messaging attributes | ||
|
|
||
| <!-- semconv azure.sdk.messaging --> | ||
| | Attribute | Type | Description | Examples | Required | | ||
| |---|---|---|---|---| | ||
| | `message_bus.destination` | string | Name of the messaging entity within namespace: e.g EventHubs name, ServiceBus queue or topic name. | `myqueue`; `myhub` | Yes | | ||
| | `peer.address` | string | Fully qualified messaging service name. | `myEventHubNamespace.servicebus.windows.net` | Yes | | ||
| <!-- endsemconv --> | ||
|
|
||
| ## CosmosDB | ||
|
|
||
| CosmosDB SDK in [Direct mode](https://docs.microsoft.com/azure/cosmos-db/sql/sql-sdk-connection-modes#available-connectivity-modes) uses TCP-based protocol and traces public API calls only. | ||
| CosmosDB semantic conventions are pinned to OpenTelemetry [Semantic Conventions v0.5.0](https://github.com/open-telemetry/opentelemetry-specification/blob/v0.5.0/specification/trace/semantic_conventions/database.md) version. | ||
|
|
||
| Spans have `CLIENT` kind and the name matches `db.statement` value. When CosmosDB detects an error or long operation (with configurable threshold), it adds a span event with extended `CosmosDiagnostics` information. | ||
|
|
||
| ### CosmosDB attributes | ||
|
|
||
| <!-- semconv azure.sdk.cosmos --> | ||
| | Attribute | Type | Description | Examples | Required | | ||
| |---|---|---|---|---| | ||
| | `db.url` | string | Cosmos DB URI | `https://my-cosmos.documents.azure.com:443/` | Yes | | ||
| | `db.instance` | string | Database name | `mydb` | Yes | | ||
| | `db.type` | string | Database type | `Cosmos` | Yes | | ||
| | [`db.statement`](../database.md) | string | The database statement being executed. [1] | `createContainerIfNotExists.myContainer` | Yes | | ||
|
|
||
| **[1]:** The value may be sanitized to exclude sensitive information. | ||
| <!-- endsemconv --> | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Are those metadata fields used by internal tooling or intended to be used by the MD and code generator in https://github.com/open-telemetry/build-tools?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
those are only intended for MD generator at this point, they might also be used by Java code generator in the future. The main intent is formal documentation though.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think it would make sense to agree on the format and content first and have that specified in the
syntax.mdfor the tool (but it looks good to me in general).