distributed-tracing-conventions.yml

groups:
  - id: azure.sdk
    brief: 'Azure SDK attribute registry.'
    type: attribute_group
    prefix: az
    attributes:
      - id: namespace
        requirement_level: required
        type: string
        stability: stable
        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']
        note: >
          This SHOULD be set as an instrumentation scope attribute when creating a `Tracer` as long as OpenTelemetry in a given language allows to do so.
      - id: schema_url
        requirement_level:
          conditionally_required: if and only if OpenTelemetry in a given language doesn't provide a standard way to set `schema_url` (.NET) # https://github.com/dotnet/runtime/issues/93795
        stability: stable
        type: string
        brief: 'OpenTelemetry Schema URL including schema version. Only 1.23.0 is supported.'
        examples: ['https://opentelemetry.io/schemas/1.23.0']
      - id: client_request_id
        type: string
        stability: stable
        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: service_request_id
        type: string
        stability: stable
        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']
      - id: appconfiguration.key
        type: string
        stability: stable
        brief: 'Value of the Azure Application Configuration property [key](https://learn.microsoft.com/azure/azure-app-configuration/concept-key-value).'
        examples: ['AppName:Service1:ApiEndpoint']
      - id: cognitivelanguage.deployment.name
        type: string
        stability: stable
        brief: 'Name of the [Azure Questions Answering](https://learn.microsoft.com/azure/ai-services/language-service/question-answering/overview) deployment.'
        examples: ['production']
      - id: cognitivelanguage.project.name
        type: string
        stability: stable
        brief: 'Name of the [Azure Questions Answering](https://learn.microsoft.com/azure/ai-services/language-service/question-answering/overview) project.'
        examples: ['production']
      - id: digitaltwins.twin.id
        type: string
        stability: stable        
        brief: 'The unique identifier of the [digital twin](https://learn.microsoft.com/azure/digital-twins/concepts-twins-graph).'
        examples: ['edf41622']
      - id: digitaltwins.model.id
        type: string
        stability: stable
        brief: 'The digital twin model id.'
        examples: ['dtmi:example:Room23;1']
      - id: digitaltwins.job.id
        type: string
        stability: stable
        brief: 'Digital twin job id.'
        examples: ['test-job']
      - id: digitaltwins.event_route.id
        type: string
        stability: stable
        brief: 'The [event route](https://learn.microsoft.com/azure/digital-twins/concepts-route-events) identifier used by the digital twin.'
        examples: ['6f8741b1']
      - id: digitaltwins.message.id
        type: string
        stability: stable
        brief: 'A unique message identifier (in the scope of the digital twin id) used to de-duplicate telemetry messages.'
        examples: ['a40896c5ab954ab1']
      - id: digitaltwins.query
        type: string
        stability: stable
        brief: 'Digital twin graph query.'
        examples: ['SELECT * FROM DIGITALTWINS WHERE Name = "DSouza"']
      - id: digitaltwins.component.name
        type: string
        stability: stable
        brief: 'The name of the digital twin component.'
        examples: ['thermostat']
      - id: digitaltwins.relationship.name
        type: string
        stability: stable
        brief: 'The name of the relationship between twins.'
        examples: ['contains']
      - id: keyvault.certificate.name
        type: string
        stability: stable
        brief: 'Azure KeyVault certificate name.'
        examples: ['selfSignedCert01']
      - id: keyvault.certificate.version
        type: string
        stability: stable
        brief: 'Azure KeyVault certificate version.'
        examples: ['c3d31d7b36c942ad83ef36fc0785a4fc']
      - id: keyvault.certificate.issuer.name
        type: string
        stability: stable
        brief: 'Azure KeyVault certificate version.'
        examples: ['issuer01']
      - id: keyvault.key.id
        type: string
        stability: stable
        brief: 'Azure KeyVault key id (full URL).'
        examples: ['"https://myvault.vault.azure.net/keys/CreateSoftKeyTest/78deebed173b48e48f55abf87ed4cf71']
      - id: keyvault.key.name
        type: string
        stability: stable
        brief: 'Azure KeyVault key name.'
        examples: ['test-key']
      - id: keyvault.key.version
        type: string
        stability: stable
        brief: 'Azure KeyVault key version.'
        examples: ['3d31e6e5c4c14eaf9be8d42c00225088']
      - id: keyvault.secret.name
        type: string
        stability: stable
        brief: 'Azure KeyVault secret name.'
        examples: ['test-secret']
      - id: keyvault.secret.version
        type: string
        stability: stable
        brief: 'Azure KeyVault secret version.'
        examples: ['4387e9f3d6e14c459867679a90fd0f79']
      - id: remoterendering.conversion.id
        type: string
        stability: stable
        brief: '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.'
        examples: ['contoso-conversion-6fae2bfb754e']
      - id: remoterendering.session.id
        type: string
        stability: stable
        brief: '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.'
        examples: ['contoso-session-8c28813adc28']

  # public API (logical calls)
  - id: azure.sdk.api
    type: span
    span_kind: internal
    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`.
    attributes:
      - ref: az.namespace
      - ref: az.schema_url
      - ref: error.type
        examples: ['java.net.UnknownHostException', 'System.Threading.Tasks.OperationCanceledException', 'azure.core.exceptions.ServiceRequestError']

  # HTTP spans
  - id: azure.sdk.http
    type: span
    span_kind: client
    extends: attributes.http.client
    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 some optional/recommended attributes. It also adds request-id attributes supported by Azure services.
    attributes:
      - ref: server.address
        note: Describes host component of Azure service endpoint.
        sampling_relevant: true
      - ref: server.port
        note: Describes port component of Azure service endpoint.
        sampling_relevant: true
      - ref: url.full
        sampling_relevant: true
      - ref: http.request.method
        note: >
          Azure SDKs support HTTP methods listed in [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#name-methods)
          and the `PATCH`` method defined in [RFC5789](https://www.rfc-editor.org/rfc/rfc5789.html)
        sampling_relevant: true          
      - ref: http.request.resend_count
      - ref: http.response.status_code
      - ref: error.type
      - ref: az.namespace
        sampling_relevant: true
      - ref: az.schema_url
        sampling_relevant: true
      - ref: az.client_request_id
      - ref: az.service_request_id

  # messaging
  - id: azure.sdk.messaging
    type: span
    brief: 'Describes Azure messaging SDKs spans.'
    attributes:
      - ref: messaging.system
        sampling_relevant: true
        examples: ['eventhubs', 'servicebus']
      - ref: messaging.destination.name
        sampling_relevant: true
      - ref: messaging.operation
        sampling_relevant: true
      - ref: messaging.batch.message_count
      - ref: messaging.message.id
      - ref: server.address
      - ref: server.port
      - ref: az.namespace
        sampling_relevant: true
      - ref: az.schema_url
        sampling_relevant: true

  # appconfiguration
  - id: azure.sdk.appconfiguration
    type: span
    brief: 'Describes Azure AppConfiguration SDK spans.'
    extends: azure.sdk.api
    attributes:
      - ref: az.appconfiguration.key

  # cognitivelanguage
  - id: azure.sdk.cognitivelanguage
    type: span
    brief: 'Describes Azure QuestionAnswering SDK spans.'
    extends: azure.sdk.api
    attributes:
      - ref: az.cognitivelanguage.project.name
      - ref: az.cognitivelanguage.deployment.name

  # digitaltwins
  - id: azure.sdk.digitaltwins
    type: span
    brief: 'Describes Azure DigitalTwins SDK spans.'
    extends: azure.sdk.api
    attributes:
      - ref: az.digitaltwins.twin.id
      - ref: az.digitaltwins.component.name
      - ref: az.digitaltwins.relationship.name
      - ref: az.digitaltwins.model.id
      - ref: az.digitaltwins.job.id
      - ref: az.digitaltwins.query
      - ref: az.digitaltwins.event_route.id
      - ref: az.digitaltwins.message.id

  # keyvault certificates
  - id: azure.sdk.keyvault.certificates
    type: span
    brief: 'Describes Azure KeyVault Certificates SDK spans.'
    extends: azure.sdk.api
    attributes:
      - ref: az.keyvault.certificate.name
      - ref: az.keyvault.certificate.version
      - ref: az.keyvault.certificate.issuer.name

  # keyvault keys
  - id: azure.sdk.keyvault.keys
    type: span
    brief: 'Describes Azure KeyVault Keys SDK spans.'
    extends: azure.sdk.api
    attributes:
      - ref: az.keyvault.key.name
      - ref: az.keyvault.key.version
      - ref: az.keyvault.key.id

  # keyvault secrets
  - id: azure.sdk.keyvault.secrets
    type: span
    brief: 'Describes Azure KeyVault Secrets SDK spans.'
    extends: azure.sdk.api
    attributes:
      - ref: az.keyvault.secret.name
      - ref: az.keyvault.secret.version

  # remote rendering
  - id: azure.sdk.remoterendering
    type: span
    brief: 'Describes Azure KeyVault Secrets SDK spans.'
    extends: azure.sdk.api
    attributes:
      - ref: az.remoterendering.conversion.id
      - ref: az.remoterendering.session.id