Distributed tracing: new docs are added

docs/tracing/distributed-tracing-conventions.md

@@ -0,0 +1,30 @@
+---
+title: "Distributed Tracing Conventions"
+permalink: distributed_tracing_conventions.html
+keywords: opentelemetry conventions
+folder: general
+sidebar: general_sidebar
+---
+
+Conventions are the contract between Azure SDK and tracing providers such as Azure Monitor, Jaeger and others.  They describe and standardize attributes, events and relationships for common span types: HTTP, DB, messaging and others.  Observability vendors use conventions to build visualizations and may be very sensitive to them.  Custom Azure SDK conventions are described in [tracing-conventions.yml](./distributed-tracing-conventions.yml) and include:
+
+- Custom Azure SDK attributes
+- Azure SDK HTTP conventions compatible with OpenTelemetry
+- Custom messaging and DB conventions. They don't follow OpenTelemetry convention and used until OpenTelemetry conventions evolve and stabilize
+
+When writing instrumentation in Azure SDK or Core:
+
+{% include requirement/MUST id="general-tracing-convention-use-otel" %} use [OpenTelemetry conventions](https://opentelemetry.io/docs/specs/otel/trace/semantic_conventions/) whenever possible.
+
+{% include requirement/MUST id="general-tracing-convention-describe-attributes" %} update [distributed-tracing-conventions.yml](./distributed-tracing-conventions.yml) when adding new attributed.
+
+{% include requirement/MUST id="general-tracing-convention-set-schema-version" %} set OpenTelemetry [Schema URL](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/schemas/README.md?plain=1) when [creating OpenTelemetry tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#get-a-tracer).
+
+{% include requirement/SHOULD id="general-tracing-convention-set-library" %} set Azure Client Library name and version [Schema URL](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#get-a-tracer) when [creating OpenTelemetry tracer](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/api.md#get-a-tracer).
+
+
+{% include requirement/SHOULD id="general-tracing-convention-new-otel" %} contribute new conventions (or patch existing ones) to OpenTelemetry when there is no suitable one or some scenarios are missing.
+
+{% include requirement/MAY id="general-tracing-convention-add-attributes" %} extend list of attributes on top of OpenTelemetry contentions with Azure-specific ones.
+
+{% include requirement/MUSTNOT id="general-tracing-convention-new-custom" %} add new custom Azure SDK conventions.

docs/tracing/distributed-tracing-conventions.yml

@@ -0,0 +1,143 @@
+# This document describes Azure SDK semantic conventions for tracing in [OpenTelemetry format](https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/syntax.md).
+# DO NOT add new conventions - use [OpenTelemetry conventions](https://github.com/open-telemetry/opentelemetry-specification/tree/main/semantic_conventions), but it's ok to extend existing ones.
+# Version: 0.1.0
+
+groups:
+  # common
+  - id: azure-sdk
+    brief: 'Describes Azure SDK spans.'
+    type: attribute_group
+    attributes:
+      - id: az.namespace
+        requirement_level: required
+        type: string
+        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']
+      - id: az.schema_url
+        requirement_level:
+          conditionally_required: if and only if OpenTelemetry in given language does not provide standard way to set schema_url (i.e. .NET) # https://opentelemetry.io/docs/reference/specification/schemas/#schema-url
+        type: string
+        brief: 'OpenTelemetry Schema URL including schema version. Only 1.17.0 is supported.'
+        examples: ['https://opentelemetry.io/schemas/1.17.0']
+
+  # public API
+  - id: azure-sdk.api
+    type: span
+    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.
+
+      Span name SHOULD match `<short-class-name.method>` pattern. Class and method name SHOULD match API user called close enough for users
+      to understand which method span matches to.
+      For example, `BlobClient.Download` could be used for different overloads of download method, it can also coexist with `BlobClient.DownloadToFile` or
+      `BlobClient.DownloadAsync`.  
+
+  # network calls
+  - id: azure-sdk.network
+    type: attribute_group
+    extends: azure-sdk
+    brief: 'Describes Azure SDK client spans.'
+    note: 'Represents calls that include network attributes'
+    attributes:
+      - ref: net.peer.name
+        requirement_level: required
+        sampling_relevant: true
+        type: string
+        brief: 'Fully qualified Azure service endpoint (host name component).'
+        examples: 'http://my-account.servicebus.windows.net/'
+      - ref: net.peer.port
+        requirement_level: 
+          conditionally_required: if not 80 or 443.
+        sampling_relevant: true
+        brief: Port of Azure service endpoint.'
+        type: int        
+        examples: [8080]
+    constraints:
+      - include: network #https://github.com/open-telemetry/opentelemetry-specification/blob/main/semantic_conventions/trace/general.yaml
+
+  # http
+  - id: azure-sdk.http
+    type: span
+    span_kind: client
+    extends: azure-sdk.network
+    brief: 'Describes HTTP client spans created per HTTP request (try).'
+    note: >
+      This conventions follows [OpenTelemetry HTTP](https://github.com/open-telemetry/opentelemetry-specification/blob/main/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.
+
+      Span name MUST NOT include dynamic parts and SHOULD follow `HTTP <method>` pattern. E.g. `HTTP GET`.
+    attributes:
+      - ref: http.method
+        requirement_level: required    
+        sampling_relevant: true  
+      - ref: http.url
+        requirement_level: required      
+        sampling_relevant: true
+      - ref: http.status_code
+        requirement_level: required      
+      - ref: http.user_agent
+        type: string
+        brief: 'Value of the HTTP User-Agent or x-ms-user-agent header'
+      - id: az.client_request_id
+        type: string
+        requirement_level:
+          conditionally_required: only if present
+        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: az.service_request_id
+        type: string
+        requirement_level:
+          conditionally_required: if and only if one was received
+        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']
+    constraints:
+      - include: http.client #https://github.com/open-telemetry/opentelemetry-specification/blob/main/semantic_conventions/trace/http.yaml
+
+  # messaging
+  - id: azure-sdk.messaging
+    type: span
+    brief: 'Describes Azure messaging SDKs spans.'
+    extends: azure-sdk.network
+    attributes:
+      - ref: messaging.system
+        requirement_level: required      
+        sampling_relevant: true
+        examples: ['eventhubs', 'servicebus']
+      - ref: messaging.destination.name
+        requirement_level: required
+        sampling_relevant: true
+        brief: 'Name of the messaging entity within namespace: e.g EventHubs name, ServiceBus queue or topic name. Must not include partition or subscription'
+        examples: ['myqueue', 'myhub']
+      - ref: messaging.operation
+      - ref: messaging.batch.message_count
+    constraints:
+      - include: messaging #https://github.com/open-telemetry/opentelemetry-specification/blob/main/semantic_conventions/trace/messaging.yaml
+
+  - id: azure-sdk.messaging.producer
+    span_kind: producer
+    extends: azure-sdk
+    brief: 'Describes producer span created per message.'
+    note: Span name SHOULD match `<queue/topic_name> message`. E.g. `orders message`. 
+
+  - id: azure-sdk.messaging.send
+    span_kind: client
+    extends: azure-sdk.messaging
+    brief: 'Describes Azure messaging SDKs producer client spans.'
+    note: >
+      Contains links to all messages contexts being sent.
+      Span name SHOULD match `<queue/topic_name> publish`. E.g. `orders publish`. 
+      
+
+  - 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 attribute `enqueuedTime` (with `long` type)
+      attribute with unix epoch time with milliseconds precision representing when message was enqueued.
+      Span name SHOULD match `<queue/topic_name> process`. E.g. `orders process`. 
+
+  # db
+  # is being moved here: https://github.com/open-telemetry/opentelemetry-specification/pull/3097