From 798e939837b70eb83e0662d071084a1440a09ee9 Mon Sep 17 00:00:00 2001 From: Mike Goldsmith Date: Thu, 1 Aug 2024 06:08:37 +0100 Subject: [PATCH] Add Azure SDK attributes & Logs events (#1028) Co-authored-by: Liudmila Molkova --- .chloggen/add-azure-logs.yaml | 22 +++++ .github/ISSUE_TEMPLATE/bug_report.yaml | 1 + .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 + .github/ISSUE_TEMPLATE/new-conventions.yaml | 1 + docs/attributes-registry/README.md | 1 + docs/attributes-registry/azure.md | 15 +++ docs/azure/README.md | 19 ++++ docs/azure/events.md | 57 +++++++++++ model/logs/azure.yaml | 102 ++++++++++++++++++++ model/registry/azure.yaml | 13 +++ 10 files changed, 232 insertions(+) create mode 100644 .chloggen/add-azure-logs.yaml create mode 100644 docs/attributes-registry/azure.md create mode 100644 docs/azure/README.md create mode 100644 docs/azure/events.md create mode 100644 model/logs/azure.yaml create mode 100644 model/registry/azure.yaml diff --git a/.chloggen/add-azure-logs.yaml b/.chloggen/add-azure-logs.yaml new file mode 100644 index 0000000000..2d14fa50a1 --- /dev/null +++ b/.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: diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 40af0a175b..450551ce21 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index cc7c77ee8b..e30d0a4630 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index 5787556938..8301d9b1bc 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.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 diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 49d5806716..003b21c5b4 100644 --- a/docs/attributes-registry/README.md +++ b/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) diff --git a/docs/attributes-registry/azure.md b/docs/attributes-registry/azure.md new file mode 100644 index 0000000000..95dbf95a15 --- /dev/null +++ b/docs/attributes-registry/azure.md @@ -0,0 +1,15 @@ + + + + + +# 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) | diff --git a/docs/azure/README.md b/docs/azure/README.md new file mode 100644 index 0000000000..3cfbc26ad0 --- /dev/null +++ b/docs/azure/README.md @@ -0,0 +1,19 @@ + + +# 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 diff --git a/docs/azure/events.md b/docs/azure/events.md new file mode 100644 index 0000000000..495a596a67 --- /dev/null +++ b/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 + + + + + + + + +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//resourceGroups//providers/Microsoft.Web/sites//functions/` | `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. + + + + + + + + + +### Body Fields + + +| 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. | {
  "statusCode": "Created",
  "serviceRequestId": "50d5cddb-8ca0-47ad-9b80-6cde2207f97c"
} | `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) | + + +See [Azure Resource Log definition](/model/logs/azure.yaml) for the details. + +[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/model/logs/azure.yaml b/model/logs/azure.yaml new file mode 100644 index 0000000000..da061e5f31 --- /dev/null +++ b/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: {
  "statusCode": "Created",
  "serviceRequestId": "50d5cddb-8ca0-47ad-9b80-6cde2207f97c"
} + # - 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" diff --git a/model/registry/azure.yaml b/model/registry/azure.yaml new file mode 100644 index 0000000000..0ef9dc1dcc --- /dev/null +++ b/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"