From b019d456bb76ba7e44f598257fc56a9eb1548ba4 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Mon, 3 Jan 2022 16:59:01 -0800 Subject: [PATCH] more clean up --- .vscode/settings.json | 12 ++++- .../trace/instrumentation/azure-sdk.yml | 28 ++++------- .../instrumentation/azure-sdk.md | 47 +++++++++++-------- 3 files changed, 46 insertions(+), 41 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 1a9c1838421..c7804707f54 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -4,10 +4,18 @@ "markdownlint.config": { "MD004": false, "MD013": false, - "MD024": {"allow_different_nesting": true}, - "MD029": {"style": "ordered"}, + "MD024": { + "allow_different_nesting": true + }, + "MD029": { + "style": "ordered" + }, "MD033": false, "MD040": false, + "MD028": false, + "MD025": { + "front_matter_title": "" + } }, "yaml.schemas": { "https://raw.githubusercontent.com/open-telemetry/build-tools/v0.8.0/semantic-conventions/semconv.schema.json": [ diff --git a/semantic_conventions/trace/instrumentation/azure-sdk.yml b/semantic_conventions/trace/instrumentation/azure-sdk.yml index 8646bc83b46..f75ede0745b 100644 --- a/semantic_conventions/trace/instrumentation/azure-sdk.yml +++ b/semantic_conventions/trace/instrumentation/azure-sdk.yml @@ -10,6 +10,7 @@ groups: - 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.' examples: ['Microsoft.Storage', 'Microsoft.KeyVault', 'Microsoft.ServiceBus'] @@ -39,29 +40,18 @@ groups: 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'] - - id: http.method - type: string + - ref: http.method required: always sampling_relevant: true - brief: 'HTTP request method.' - examples: ["GET", "POST", "HEAD"] - - id: http.url - type: string + - ref: http.url required: always sampling_relevant: true - brief: Full HTTP request URL in the form `scheme://host[:port]/path?query[#fragment]` - examples: ['https://www.foo.bar/search?q=OpenTelemetry#SemConv'] - - id: http.status_code - type: int - required: - conditional: If and only if one was received/sent. - brief: '[HTTP response status code](https://tools.ietf.org/html/rfc7231#section-6).' - examples: [200] - - id: http.user_agent - type: string + - 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.' - examples: ['CERN-LineMode/2.15 libwww/2.17b3'] # messaging - id: azure.sdk.messaging @@ -112,10 +102,8 @@ groups: required: always brief: 'Cosmos DB URI' examples: ['https://my-cosmos.documents.azure.com:443/'] - - id: db.statement - type: string + - ref: db.statement required: always - brief: 'Database statement' examples: ['createContainerIfNotExists.myContainer'] - id: db.instance type: string diff --git a/specification/trace/semantic_conventions/instrumentation/azure-sdk.md b/specification/trace/semantic_conventions/instrumentation/azure-sdk.md index d5016823f39..c6c84328fa4 100644 --- a/specification/trace/semantic_conventions/instrumentation/azure-sdk.md +++ b/specification/trace/semantic_conventions/instrumentation/azure-sdk.md @@ -2,7 +2,7 @@ **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. +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. - [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) @@ -13,26 +13,30 @@ Azure SDK produces spans for public API calls and nested HTTP client spans. Non- ## 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 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 SDKs plan to fully adopt OpenTelemetry semantic conventions once they reach `Stable` status. +Azure SDK plans to fully adopt OpenTelemetry semantic conventions once conventions 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). +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 | + +Following attributes MUST be provided **at span creation time** (when provided at all), so they can be considered for sampling decisions: + +* `az.namespace` ## Public API calls -Azure SDKs create a span for public API call (that involve communication with Azure services). +Azure SDKs create a span for public API call (that involves 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. +- 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. @@ -45,18 +49,21 @@ Azure SDKs implement a valid subset of [OpenTelemetry HTTP conventions v1.6.x](h |---|---|---|---|---| | `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 | +| [`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:password@www.example.com/`. 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.url` +* [`http.method`](../http.md) +* [`http.url`](../http.md) +* [`http.user_agent`](../http.md) -SDKs support [W3C Trace context](https://w3c.github.io/trace-context/) propagation and Azure Services legacy correlation protocols. +Instrumentation support [W3C Trace context](https://w3c.github.io/trace-context/) propagation and Azure Services legacy correlation protocols. Propagator configuration is not supported. ## Messaging SDKs @@ -88,12 +95,12 @@ Messaging SDKs produce three kinds of spans: | `peer.address` | string | Fully qualified messaging service name. | `myEventHubNamespace.servicebus.windows.net` | Yes | -## CosmosDb +## 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. +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. -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. +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 @@ -101,7 +108,9 @@ Spans have `CLIENT` kind and the name matches `db.statement` value. When CosmosD | 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 | +| [`db.statement`](../database.md) | string | The database statement being executed. [1] | `createContainerIfNotExists.myContainer` | Yes | + +**[1]:** The value may be sanitized to exclude sensitive information. \ No newline at end of file