diff --git a/semantic_conventions/trace/instrumentation/azure-sdk.yml b/semantic_conventions/trace/instrumentation/azure-sdk.yml index f75ede0745b..f32e22f5d70 100644 --- a/semantic_conventions/trace/instrumentation/azure-sdk.yml +++ b/semantic_conventions/trace/instrumentation/azure-sdk.yml @@ -4,31 +4,30 @@ groups: # common - - id: azure.sdk - brief: 'Describes Azure SDK spans.' + - id: azure + brief: 'Describes Azure spans.' attributes: - id: az.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 request is made against.' + 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.sdk - brief: 'Describes Azure SDK API calls spans.' - note: 'Represents public surface API calls that wrap an Azure service call.' + extends: azure + brief: 'Describes Azure SDK API calls that wrap an Azure service call(s).' # http - id: azure.sdk.http - extends: azure.sdk + extends: azure span_kind: client - brief: 'Describes HTTP client spans created per HTTP request (try).' + 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 all optional attributes, providing only `http.url` to describe destination. It adds request-id attributes supported by Azure services. + 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 @@ -56,7 +55,7 @@ groups: # messaging - id: azure.sdk.messaging brief: 'Describes Azure messaging SDKs spans.' - extends: azure.sdk + extends: azure note: Implements OpenTracing MessageBus conventions https://opentracing.io/specification/conventions/ attributes: - id: message_bus.destination @@ -72,7 +71,7 @@ groups: - id: azure.sdk.messaging.producer span_kind: producer extends: azure.sdk.messaging - brief: 'Describes producer span created per event.' + brief: 'Describes producer span created per message.' - id: azure.sdk.messaging.send span_kind: client @@ -93,9 +92,9 @@ groups: span_kind: client brief: 'Describes Azure CosmosDB spans.' note: > - Events with additional debug info are added for long running operations. + 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.sdk + extends: azure attributes: - id: db.url type: string diff --git a/specification/trace/semantic_conventions/instrumentation/azure-sdk.md b/specification/trace/semantic_conventions/instrumentation/azure-sdk.md index c6c84328fa4..94ecdae6471 100644 --- a/specification/trace/semantic_conventions/instrumentation/azure-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/azure-sdk.md @@ -15,16 +15,16 @@ Azure SDK produces spans for public API calls and nested HTTP client spans. Non- 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 conventions reach `Stable` status. +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. - + | 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 request is made against. | `Microsoft.Storage`; `Microsoft.KeyVault`; `Microsoft.ServiceBus` | Yes | +| `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: @@ -42,7 +42,7 @@ Azure SDKs create a span for public API call (that involves communication with A ## HTTP Client -Azure SDKs implement a valid subset of [OpenTelemetry HTTP conventions v1.6.x](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/semantic_conventions/http.md) and create a span per HTTP call (try). +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 (try). | Attribute | Type | Description | Examples | Required | @@ -63,28 +63,28 @@ Following attributes MUST be provided **at span creation time** (when provided a * [`http.user_agent`](../http.md) -Instrumentation support [W3C Trace context](https://w3c.github.io/trace-context/) propagation and Azure Services legacy correlation protocols. Propagator configuration is not supported. +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 originates from [OpenTracing semantic conventions](https://opentracing.io/specification/conventions/) +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 `.message` pattern (e.g. `EventHubs.message`) + - Producer spans name follows `.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 `.send` pattern (e.g. `EventHubs.send`) + - Send spans name follows `.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. + - 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 @@ -98,7 +98,7 @@ Messaging SDKs produce three kinds of spans: ## 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 trace conventions 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. +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.