From 28a1f0f73695b74dc6dad5d218beee65a0bffc3f Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 21 Dec 2021 13:24:26 -0800 Subject: [PATCH] add md file, changelog and minor fixes --- CHANGELOG.md | 2 + .../trace/instrumentation/azure-sdk.yml | 36 +++--- .../instrumentation/azure-sdk.md | 107 ++++++++++++++++++ 3 files changed, 127 insertions(+), 18 deletions(-) create mode 100644 specification/trace/semantic_conventions/instrumentation/azure-sdk.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 1f8230c7184..d72d3884976 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -49,6 +49,8 @@ release. ([#2191](https://github.com/open-telemetry/opentelemetry-specification/pull/2191)) - Add `device.manufacturer` to describe mobile device manufacturers. ([2100](https://github.com/open-telemetry/opentelemetry-specification/pull/2100)) +- Add Azure SDK trace semantic conventions + ([#2233](https://github.com/open-telemetry/opentelemetry-specification/pull/2233)) ### Compatibility diff --git a/semantic_conventions/trace/instrumentation/azure-sdk.yml b/semantic_conventions/trace/instrumentation/azure-sdk.yml index 7d793bd9d61..8646bc83b46 100644 --- a/semantic_conventions/trace/instrumentation/azure-sdk.yml +++ b/semantic_conventions/trace/instrumentation/azure-sdk.yml @@ -1,10 +1,10 @@ # 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 +# This document describes Azure SDK trace semantic conventions. For more details refer to https://azure.github.io/azure.sdk/distributed_tracing_conventions.html groups: # common - - id: azure-sdk + - id: azure.sdk brief: 'Describes Azure SDK spans.' attributes: - id: az.namespace @@ -14,19 +14,19 @@ groups: examples: ['Microsoft.Storage', 'Microsoft.KeyVault', 'Microsoft.ServiceBus'] # public API - - id: azure-sdk.api + - id: azure.sdk.api span_kind: internal - extends: azure-sdk + extends: azure.sdk brief: 'Describes Azure SDK API calls spans.' note: 'Represents public surface API calls that wrap an Azure service call.' # http - - id: azure-sdk.http - extends: azure-sdk + - id: azure.sdk.http + extends: azure.sdk span_kind: client brief: 'Describes HTTP client spans created per HTTP request (try).' note: > - Follows [OpenTelemetry HTTP conventions v1.6.x](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.6.x/specification/trace/semantic_conventions/http.md) + 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. attributes: - id: request_id @@ -64,9 +64,9 @@ groups: examples: ['CERN-LineMode/2.15 libwww/2.17b3'] # messaging - - id: azure-sdk.messaging + - id: azure.sdk.messaging brief: 'Describes Azure messaging SDKs spans.' - extends: azure-sdk + extends: azure.sdk note: Implements OpenTracing MessageBus conventions https://opentracing.io/specification/conventions/ attributes: - id: message_bus.destination @@ -79,33 +79,33 @@ groups: brief: 'Fully qualified messaging service name.' required: always examples: ['myEventHubNamespace.servicebus.windows.net'] - - id: azure-sdk.messaging.producer + - id: azure.sdk.messaging.producer span_kind: producer - extends: azure-sdk.messaging + extends: azure.sdk.messaging brief: 'Describes producer span created per event.' - - id: azure-sdk.messaging.send + - id: azure.sdk.messaging.send span_kind: client - extends: azure-sdk.messaging + extends: azure.sdk.messaging brief: 'Describes send (transport call) span.' note: 'Contains links to all messages contexts being sent.' - - id: azure-sdk.messaging.process + - id: azure.sdk.messaging.process span_kind: consumer - extends: azure-sdk.messaging + extends: azure.sdk.messaging brief: 'Describes consumption span.' note: > - Contains links to all messages contexts being consumed. Each link has attribute `enqueuedTime` (with `long` type) + 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 + - id: azure.sdk.cosmos span_kind: client brief: 'Describes Azure CosmosDB spans.' note: > Events with additional debug info are added for long running operations. Implements https://github.com/open-telemetry/opentelemetry-specification/blob/v0.5.0/specification/trace/semantic_conventions/database.md - extends: azure-sdk + extends: azure.sdk 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 new file mode 100644 index 00000000000..d5016823f39 --- /dev/null +++ b/specification/trace/semantic_conventions/instrumentation/azure-sdk.md @@ -0,0 +1,107 @@ +# Semantic conventions for Azure SDK + +**Status**: [Experimental](../../../document-status.md) + +This document describes tracing semantic conventions adopted by Azure ClientLibraries (SDK). Instrumentations live in Azure SDK repos and are shipped along with Azure SDK artifacts. Instrumentations cover all modern (track 2) SDKs. + +- [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 from time to time. + +Azure SDKs plan 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 (in some cases SDK 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 | + + +## Public API calls + +Azure SDKs create a span for public API call (that involve communication with Azure services). + +- Spans representing public APIs have names following `ClientType.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 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). + + +| 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` | string | HTTP request method. | `GET`; `POST`; `HEAD` | Yes | +| `http.url` | string | Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]` | `https://www.foo.bar/search?q=OpenTelemetry#SemConv` | Yes | +| `http.status_code` | int | [HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6). | `200` | If and only if one was received/sent. | +| `http.user_agent` | 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 | + +Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: + +* `http.method` +* `http.url` + + +SDKs support [W3C Trace context](https://w3c.github.io/trace-context/) propagation and Azure Services legacy correlation protocols. + +## 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/) + +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`) + +- `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`) + +- `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 + + +| 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 | + + +## 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 0.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 + + +| Attribute | Type | Description | Examples | Required | +|---|---|---|---|---| +| `db.url` | string | Cosmos DB URI | `https://my-cosmos.documents.azure.com:443/` | Yes | +| `db.statement` | string | Database statement | `createContainerIfNotExists.myContainer` | Yes | +| `db.instance` | string | Database name | `mydb` | Yes | +| `db.type` | string | Database type | `Cosmos` | Yes | + \ No newline at end of file