Merge branch 'main' into remove-prefix-everywhere

.chloggen/1296.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: docs
+note: Update semantic conventions code generation documentation to use weaver instead of build-tools.
+issues: [ 1296 ]

.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:

.chloggen/session_start_end_event.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: 'enhancement'
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: 'session'
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add new experimental `session.start` and `session.end` events
+
+# 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: [1091]
+
+# (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

@@ -16,13 +16,15 @@ body:
       multiple: true
       options:
         - area:other
+        - area:docs
         # NOTE: The list below is autogenerated using `make generate-gh-issue-templates`
         # DO NOT manually edit it.
         # Start semconv area list
         - area:android
         - 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

docs/general/session.md

@@ -13,7 +13,7 @@ the Logs, Events, and Spans generated during the Session's lifecycle.
 
 When a session reaches end of life, typically due to user inactivity or session timeout, a new session identifier
 will be assigned. The previous session identifier may be provided by the instrumentation so that telemetry
-backends can link the two sessions.
+backends can link the two sessions (see [Session Start Event](#session-start-event) below).
 
 ## Attributes
 
@@ -35,4 +35,41 @@ backends can link the two sessions.
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
+## Session Events
+
+### Session Start Event
+
+![Experimental](https://img.shields.io/badge/-experimental-blue)
+
+`event.name` MUST be`session.start`
+
+For instrumentation that tracks user behavior during user sessions, a `session.start` event MUST be emitted
+every time a session is created. When a new session is created as a continuation of a prior session,
+the `session.previous_id` SHOULD be included in the event. The values of `session.id` and `session.previous_id`
+MUST be different.
+
+When the `session.start` event contains both `session.id` and `session.previous_id` fields, the event then implies
+that the previous session has ended. If the session ID in `session.previous_id` has not yet ended via explicit
+`session.end` event, then the consumer SHOULD treat this continuation event as semantically equivalent to
+`session.end(session.previous_id)` and `session.start(session.id)`.
+
+| Body field                                                    | Type   | Description                                          | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability                                                        |
+|---------------------------------------------------------------|--------|------------------------------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------|
+| [`session.id`](/docs/attributes-registry/session.md)          | string | The ID of the new session being started.             | `Required`                                                                                            | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| [`session.previous_id`](/docs/attributes-registry/session.md) | string | The previous `session.id` for this user, when known. | `Conditionally Required`                                                                              | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+### Session End Event
+
+![Experimental](https://img.shields.io/badge/-experimental-blue)
+
+`event.name` MUST be `session.end`
+
+For instrumentation that tracks user behavior during user sessions, a `session.end` event SHOULD be emitted
+every time a session ends. When a session ends and continues as a new session, this event SHOULD be
+emitted prior to the `session.start` event.
+
+| Body field                                                    | Type   | Description                            | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability                                                        |
+|---------------------------------------------------------------|--------|----------------------------------------|--------------------------|------------------------------------------------------------------|
+| [`session.id`](/docs/attributes-registry/session.md)          | string | The ID of the new session being ended. | `Required`                                                | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
 [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status