Skip to content

Commit 5b0790a

Browse files
Liudmila Molkovajsquire
Liudmila Molkova
and
jsquire
authored
Tracing conventions: move .NET-only attributes from azure-sdk to this repo (Azure#51366)
* Tracing conventions: move .NET-only attributes from azure-sdk to this repo --------- Co-authored-by: Jesse Squire <[email protected]>
1 parent d5ebc59 commit 5b0790a

File tree

2 files changed

+70
-6
lines changed

2 files changed

+70
-6
lines changed

‎sdk/core/Azure.Core/samples/Diagnostics.md‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -174,14 +174,15 @@ Azure client libraries produce the following kinds of activities:
174174
- *client method calls*: for example, `BlobClient.DownloadTo` or `SecretClient.StartDeleteSecret`.
175175
- *messaging events*: Event Hubs and Service Bus message creation is traced and correlated with its sending, receiving, and processing.
176176

177-
Prior to November 2023, OpenTelemetry support was experimental for all Azure client libraries (see [Enabling experimental tracing features](#enabling-experimental-tracing-features) for the details).
178-
Most of Azure client libraries released in or after November 2023 have OpenTelemetry support enabled by default. Tracing support in messaging libraries (`Azure.Messaging.ServiceBus` and `Azure.Messaging.EventHubs`) remains experimental.
177+
Prior to November 2023, OpenTelemetry support was experimental for all Azure client libraries (see [Enabling experimental tracing features](#enabling-experimental-tracing-features) for the details).
178+
Most of Azure client libraries released in or after November 2023 have OpenTelemetry support enabled by default. Tracing support in messaging libraries (`Azure.Messaging.ServiceBus` and `Azure.Messaging.EventHubs`) remains experimental.
179179

180-
More detailed distributed tracing convention can be found at [Azure SDK semantic conventions](https://github.com/Azure/azure-sdk/blob/main/docs/tracing/distributed-tracing-conventions.md).
180+
More detailed distributed tracing convention can be found at [Azure SDK semantic conventions](https://github.com/Azure/azure-sdk/blob/main/docs/observability/opentelemetry-conventions.md). Additional attributes emitted by
181+
Azure client libraries in .NET are documented [here](https://github.com/Azure/azure-sdk-for-net/blob/95b7ac20eebea0c13eab4a9bed0ee3ae1908d2bd/sdk/core/Azure.Core/samples/OpenTelemetrySemanticConventions.md).
181182

182183
### OpenTelemetry configuration
183184

184-
OpenTelemetry relies on `ActivitySource` to collect distributed traces.
185+
OpenTelemetry relies on `ActivitySource` to collect distributed traces.
185186
Follow the [OpenTelemetry configuration guide](https://opentelemetry.io/docs/instrumentation/net/getting-started/#instrumentation) to configure collection and exporting pipeline.
186187

187188
Your observability vendor may enable Azure SDK activities by default. For example, stable Azure SDK instrumentations are enabled by [Azure Monitor OpenTelemetry Distro](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/monitor/Azure.Monitor.OpenTelemetry.AspNetCore/README.md#enable-azure-sdk-instrumentation).
@@ -212,7 +213,7 @@ Azure SDK traces all HTTP calls using `Azure.Core.Http` source. If you enable it
212213

213214
Unlike generic HTTP activities, Azure SDK HTTP activities include Azure-specific attributes such as request identifiers usually passed to and from Azure services in `x-ms-client-request-id`, `x-ms-request-id` or similar request and response headers. This data may be important when correlating client and server telemetry or creating support tickets.
214215

215-
To avoid double-collection you may either
216+
To avoid double-collection you may either:
216217
- enrich generic HTTP client activities with Azure request identifiers and disable Azure SDK HTTP activities.
217218
- filter out duplicated generic HTTP client activities.
218219

@@ -283,7 +284,7 @@ To see an example of distributed tracing in action, take a look at our [sample a
283284

284285
### Enabling experimental tracing features
285286

286-
Certain tracing features remain experimental and still need to be enabled explicitly. Check out [Azure SDK semantic conventions](https://github.com/Azure/azure-sdk/blob/main/docs/tracing/distributed-tracing-conventions.md) to see which conventions are considered experimental.
287+
Certain tracing features remain experimental and still need to be enabled explicitly. Check out [Azure SDK semantic conventions](https://github.com/Azure/azure-sdk/blob/main/docs/observability/opentelemetry-conventions.md) to see which conventions are considered experimental.
287288

288289
The shape of experimental Activities may change in the future without notice. This includes:
289290
- the kinds of operations that are tracked

‎sdk/core/Azure.Core/samples/OpenTelemetrySemanticConventions.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# OpenTelemetry Semantic Conventions
2+
3+
Azure client libraries follow OpenTelemetry semantic conventions on distributed traces.
4+
In addition to general conventions described in the [azure-sdk repo](https://github.com/Azure/azure-sdk/blob/main/docs/observability/opentelemetry-conventions.md), some of the .NET libraries emit
5+
additional attributes on public API spans. Such attributes are described below.
6+
7+
## Azure Application Configuration attributes
8+
9+
| Attribute | Type | Description | Examples | Requirement Level |
10+
|---|---|---|---|---|
11+
| `az.appconfiguration.key` | string | Value of the Azure Application Configuration property [key](https://learn.microsoft.com/azure/azure-app-configuration/concept-key-value). | `AppName:Service1:ApiEndpoint` | Recommended |
12+
13+
## Azure Cognitive Language Question Answering SDK attributes
14+
15+
| Attribute | Type | Description | Examples | Requirement Level |
16+
|---|---|---|---|---|
17+
| `az.cognitivelanguage.deployment.name` | string | Name of the [Azure Questions Answering](https://learn.microsoft.com/azure/ai-services/language-service/question-answering/overview) deployment. | `production` | Recommended |
18+
| `az.cognitivelanguage.project.name` | string | Name of the [Azure Questions Answering](https://learn.microsoft.com/azure/ai-services/language-service/question-answering/overview) project. | `production` | Recommended |
19+
20+
## Azure Digital Twins attributes
21+
22+
| Attribute | Type | Description | Examples | Requirement Level |
23+
|---|---|---|---|---|
24+
| `az.digitaltwins.component.name` | string | The name of the digital twin component. | `thermostat` | Recommended |
25+
| `az.digitaltwins.event_route.id` | string | The [event route](https://learn.microsoft.com/azure/digital-twins/concepts-route-events) identifier used by the digital twin. | `6f8741b1` | Recommended |
26+
| `az.digitaltwins.job.id` | string | Digital twin job ID. | `test-job` | Recommended |
27+
| `az.digitaltwins.message.id` | string | A unique message identifier (in the scope of the digital twin ID) used to de-duplicate telemetry messages. | `a40896c5ab954ab1` | Recommended |
28+
| `az.digitaltwins.model.id` | string | The digital twin model ID. | `dtmi:example:Room23;1` | Recommended |
29+
| `az.digitaltwins.query` | string | Digital twin graph query. | `SELECT * FROM DIGITALTWINS WHERE Name = "DSouza"` | Recommended |
30+
| `az.digitaltwins.relationship.name` | string | The name of the relationship between twins. | `contains` | Recommended |
31+
| `az.digitaltwins.twin.id` | string | The unique identifier of a [digital twin](https://learn.microsoft.com/azure/digital-twins/concepts-twins-graph). | `edf41622` | Recommended |
32+
33+
## Azure Key Vault attributes
34+
35+
### Azure Key Vault Certificates attributes
36+
37+
| Attribute | Type | Description | Examples | Requirement Level |
38+
|---|---|---|---|---|
39+
| `az.keyvault.certificate.issuer.name` | string | The Azure Key Vault certificate issuer name. | `issuer01` | Recommended |
40+
| `az.keyvault.certificate.name` | string | The Azure Key Vault certificate name. | `selfSignedCert01` | Recommended |
41+
| `az.keyvault.certificate.version` | string | The Azure Key Vault certificate version. | `c3d31d7b36c942ad83ef36fc0785a4fc` | Recommended |
42+
43+
### Azure Key Vault Keys attributes
44+
45+
| Attribute | Type | Description | Examples | Requirement Level |
46+
|---|---|---|---|---|
47+
| `az.keyvault.key.id` | string | The Azure Key Vault key ID (full URL). | `"https://myvault.vault.azure.net/keys/CreateSoftKeyTest/78deebed173b48e48f55abf87ed4cf71"` | Recommended |
48+
| `az.keyvault.key.name` | string | The Azure Key Vault key name. | `test-key` | Recommended |
49+
| `az.keyvault.key.version` | string | The Azure Key Vault key version. | `3d31e6e5c4c14eaf9be8d42c00225088` | Recommended |
50+
51+
### Azure Key Vault Secrets attributes
52+
53+
| Attribute | Type | Description | Examples | Requirement Level |
54+
|---|---|---|---|---|
55+
| `az.keyvault.secret.name` | string | The Azure Key Vault secret name. | `test-secret` | Recommended |
56+
| `az.keyvault.secret.version` | string | The Azure Key Vault secret version. | `4387e9f3d6e14c459867679a90fd0f79` | Recommended |
57+
58+
### Azure Mixed Reality Remote Rendering attributes
59+
60+
| Attribute | Type | Description | Examples | Requirement Level |
61+
|---|---|---|---|---|
62+
| `az.remoterendering.conversion.id` | string | A conversion ID uniquely identifying the conversion for the given [Azure Remote Rendering](https://learn.microsoft.com/windows/mixed-reality/develop/mixed-reality-cloud-services#azure-remote-rendering) account. | `contoso-conversion-6fae2bfb754e` | Recommended |
63+
| `az.remoterendering.session.id` | string | A session ID uniquely identifying the conversion for the given [Azure Remote Rendering](https://learn.microsoft.com/windows/mixed-reality/develop/mixed-reality-cloud-services#azure-remote-rendering) account. | `contoso-session-8c28813adc28` | Recommended |

0 commit comments

Comments
 (0)