Add Azure SDK attributes & Logs events (#1028)

Co-authored-by: Liudmila Molkova <[email protected]>

.chloggen/add-azure-logs.yaml

@@ -0,0 +1,22 @@
+# Use this changelog template to create an entry for release notes.
+#
+# If your change doesn't affect end users you should instead start
+# your pull request title with [chore] or use the "Skip Changelog" label.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: new_component
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: azure
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add Azure SDK attributes & Logs event semantic conventions
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+# The values here must be integers.
+issues: [1027]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext:

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -23,6 +23,7 @@ body:
         - area:artifact
         - area:aspnetcore
         - area:aws
+        - area:azure
         - area:browser
         - area:cicd
         - area:client

.github/ISSUE_TEMPLATE/change_proposal.yaml

@@ -16,6 +16,7 @@ body:
         - area:artifact
         - area:aspnetcore
         - area:aws
+        - area:azure
         - area:browser
         - area:cicd
         - area:client

.github/ISSUE_TEMPLATE/new-conventions.yaml

@@ -25,6 +25,7 @@ body:
         - area:artifact
         - area:aspnetcore
         - area:aws
+        - area:azure
         - area:browser
         - area:cicd
         - area:client

docs/attributes-registry/README.md

@@ -35,6 +35,7 @@ Currently, the following namespaces exist:
 - [Artifact](artifact.md)
 - [Aspnetcore](aspnetcore.md)
 - [AWS](aws.md)
+- [Azure](azure.md)
 - [Browser](browser.md)
 - [CICD](cicd.md)
 - [Client](client.md)

docs/attributes-registry/azure.md

@@ -0,0 +1,15 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Azure
+
+## Azure Sdk Attributes
+
+This document defines generic attributes for Azure SDK.
+
+| Attribute               | Type   | Description                                                                                                       | Examples                               | Stability                                                        |
+| ----------------------- | ------ | ----------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------- |
+| `az.service_request_id` | string | The unique identifier of the service request. It's generated by the Azure service and returned with the response. | `00000000-0000-0000-0000-000000000000` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

docs/azure/README.md

@@ -0,0 +1,19 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Azure
+path_base_for_github_subdir:
+  from: tmp/semconv/docs/azure/_index.md
+  to: azure/README.md
+--->
+
+# Semantic Convention for Azure Resource Logs
+
+**Status**: [Experimental][DocumentStatus]
+
+This document describes Azure Resource Logs, see [Azure Resource Log Top-level Schema][AzureResourceSchema].
+
+Semantic conventions are defined for the following signals:
+
+* [Events](events.md)
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status
+[AzureResourceSchema]: https://learn.microsoft.com/azure/azure-monitor/essentials/resource-logs-schema#top-level-common-schema

docs/azure/events.md

@@ -0,0 +1,57 @@
+# Semantic Conventions for Azure Resource Log events
+
+**Status**: [Experimental][DocumentStatus]
+
+This document defines semantic conventions for instrumentations that emit Azure
+Resource Log events.
+
+## Azure Resource Log
+
+### Attributes
+
+<!-- semconv az.resource.log -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+The event name MUST be `az.resource.log`.
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`az.service_request_id`](/docs/attributes-registry/azure.md) | string | The unique identifier of the service request. It's generated by the Azure service and returned with the response. | `00000000-0000-0000-0000-000000000000` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`cloud.resource_id`](/docs/attributes-registry/cloud.md) | string | The [Fully Qualified Azure Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) the log is emitted for. | `arn:aws:lambda:REGION:ACCOUNT_ID:function:my-function`; `//run.googleapis.com/projects/PROJECT_ID/locations/LOCATION_ID/services/SERVICE_ID`; `/subscriptions/<SUBSCIPTION_GUID>/resourceGroups/<RG>/providers/Microsoft.Web/sites/<FUNCAPP>/functions/<FUNC>` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`event.name`](/docs/attributes-registry/event.md) | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+**[1]:** Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). Notably, event names are namespaced to avoid collisions and provide a clean separation of semantics for events in separate domains like browser, mobile, and kubernetes.
+
+
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+### Body Fields
+
+<!-- manually added table until body fields can be autogenerated -->
+| Body Field | Type | Description  | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| `category` | string | The Azure category of the log entry. | `AuditEvent`, `GatewayLogs`, `ApplicationGatewayAccessLog` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `correlation.id` | string | The correlation ID of the log entry. | `607964b6-41a5-4e24-a5db-db7aab3b9b34` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `duration` | int | The duration of the operations in milliseconds. | `1000` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `identity` | string | A JSON blob that describes the identity of the user or application that performed the operation. | `someone` | `Opt-In` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `operation.name` | string | The name of the operation. | `SecretGet`, `Microsoft.ApiManagement/GatewayLogs`, `ApplicationGatewayAccess` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `operation.version` | string | The version of the operation. | `1.0` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `properties` | keyvaluelist | The properties provided in the Azure Resource Log. | <code>{<br/>&nbsp;&nbsp;"statusCode": "Created",<br/>&nbsp;&nbsp;"serviceRequestId": "50d5cddb-8ca0-47ad-9b80-6cde2207f97c"<br/>}</code> | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `result.type` | string | The status associated with the logged event. | `Started`, `In Progress`, `Succeeded`, `Failed`, `Active`, `Resolved` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `result.signature` | string | The substatus of associated with the logged event. | `OK` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `result.description` | string | The description of the result. | `The operation was successful`, `The operation failed` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `tenant.id` | string | The tenant ID of the Active Directory tenant that this event is tied to. | `607964b6-41a5-4e24-a5db-db7aab3b9b34` | `Conditionally Required`: if the event is tied to an Active Directory tenant. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+<!-- end of manually added table -->
+
+See [Azure Resource Log definition](/model/logs/azure.yaml) for the details.
+
+[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status

model/logs/azure.yaml

@@ -0,0 +1,102 @@
+groups:
+  - id: az.resource.log
+    stability: experimental
+    type: event
+    name: az.resource.log
+    brief: >
+      Describes Azure Resource Log event, see
+      [Azure Resource Log Top-level Schema](https://learn.microsoft.com/azure/azure-monitor/essentials/resource-logs-schema#top-level-common-schema)
+      for more details.
+    attributes:
+      - ref: az.service_request_id
+      - ref: cloud.resource_id
+        brief: The [Fully Qualified Azure Resource ID](https://docs.microsoft.com/rest/api/resources/resources/get-by-id) the log is emitted for.
+        note: ""
+      - ref: event.name
+      # Future Note: When the build tools support this definition please uncomment and validate the details
+      # included here and what has been added to the manual markdown table
+      # body:
+      #   fields:
+      #     - id: category
+      #       type: string
+      #       stability: experimental
+      #       brief: "The Azure category of the log entry."
+      #       examples:
+      #         - AuditEvent
+      #         - GatewayLogs
+      #         - ApplicationGatewayAccessLog
+      #     - id: correlation.id
+      #       type: string
+      #       stability: experimental
+      #       brief: "The correlation ID of the log entry."
+      #       examples:
+      #         - 607964b6-41a5-4e24-a5db-db7aab3b9b34
+      #     - id: duration
+      #       type: int
+      #       stability: experimental
+      #       brief: "The duration of the operations in milliseconds."
+      #       examples:
+      #         - 1000
+      #     - id: identity
+      #       type: string
+      #       stability: experimental
+      #       brief: >
+      #         "A JSON blob that describes the identity of the user or application that performed the operation."
+      #       note: >
+      #         Typically, this field includes the authorization and claims or JWT token from Active Directory.
+      #         > Warning:
+      #         > this field contains sensitive (PII) information."
+      #       requirement_level: opt-in
+      #       examples:
+      #         - "someone"
+      #     - id: operation.name
+      #       type: string
+      #       stability: experimental
+      #       brief: "The name of the operation."
+      #       examples:
+      #         - SecretGet
+      #         - Microsoft.ApiManagement/GatewayLogs
+      #         - ApplicationGatewayAccess
+      #     - id: operation.version
+      #       type: string
+      #       stability: experimental
+      #       brief: "The version of the operation."
+      #       examples:
+      #         - "1.0"
+      #     - id: properties
+      #       type: KeyValueList # note: this is not a supported type in the current build tools
+      #       stability: experimental
+      #       brief: "The properties provided in the Azure Resource Log."
+      #       examples: <code>{<br/>&nbsp;&nbsp;"statusCode": "Created",<br/>&nbsp;&nbsp;"serviceRequestId": "50d5cddb-8ca0-47ad-9b80-6cde2207f97c"<br/>}</code>
+      #     - id: result.type
+      #       type: string
+      #       stability: experimental
+      #       brief: "The status associated with the logged event."
+      #       examples:
+      #         - "Started"
+      #         - "In Progress"
+      #         - "Succeeded"
+      #         - "Failed"
+      #         - "Active"
+      #         - "Resolved"
+      #     - id: result.signature
+      #       type: string
+      #       stability: experimental
+      #       brief: "The substatus of associated with the logged event. "
+      #       examples:
+      #         - "OK"
+      #     - id: result.description
+      #       type: string
+      #       stability: experimental
+      #       brief: "The description of the result."
+      #       examples:
+      #         - "The operation was successful"
+      #         - "The operation failed"
+      #     - id: tenant.id
+      #       type: string
+      #       stability: experimental
+      #       brief: "The tenant ID of the Active Directory tenant that this event is tied to."
+      #       requirement_level:
+      #         conditionally_required: "if the event is tied to an Active Directory tenant."
+      #       examples:
+      #         - "00000000-0000-0000-0000-000000000000"

model/registry/azure.yaml

@@ -0,0 +1,13 @@
+groups:
+  - id: registry.azure.sdk
+    prefix: az
+    type: attribute_group
+    brief: >
+      This document defines generic attributes for Azure SDK.
+    attributes:
+      - id: service_request_id
+        type: string
+        stability: experimental
+        brief: "The unique identifier of the service request. It's generated by the Azure service and returned with the response."
+        examples:
+          - "00000000-0000-0000-0000-000000000000"