more clean up

lmolkova · lmolkova · commit 0008eadc7cb2 · 2022-01-03T17:02:06.000-08:00
diff --git 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
@@ -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.
 
 <!-- semconv azure.sdk -->
 | 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`
 <!-- endsemconv -->
 
 ## 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)
 <!-- endsemconv -->
 
-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,20 +95,22 @@ Messaging SDKs produce three kinds of spans:
 | `peer.address` | string | Fully qualified messaging service name. | `myEventHubNamespace.servicebus.windows.net` | Yes |
 <!-- endsemconv -->
 
-## 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
 
 <!-- semconv azure.sdk.cosmos -->
 | 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.
 <!-- endsemconv -->
