-
Notifications
You must be signed in to change notification settings - Fork 57
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #176 from neoseurae12/updated/distributed_tracing
Update the docs: 'Distributed tracing'
- Loading branch information
Showing
3 changed files
with
186 additions
and
6 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |