Merge branch 'main' into db-pool-name-attribute

.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

.github/workflows/checks.yml

@@ -108,3 +108,10 @@ jobs:
       run: |
         make generate-gh-issue-templates
         git diff --exit-code '.github/ISSUE_TEMPLATE' || (echo 'Dropdowns in issue templates is out of date, please run "make generate-gh-issue-templates" and commit the changes in this PR. Please note, if you are running it on Mac OS X, please make sure to use GNU version of sed instead of default "sed".' && exit 1)
+
+  policies-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: verify semantic conventions yaml definitions
+      run: make check-policies

Makefile

@@ -228,3 +228,12 @@ chlog-update: $(CHLOGGEN)
 .PHONY: generate-gh-issue-templates
 generate-gh-issue-templates:
 	$(TOOLS_DIR)/scripts/update-issue-template-areas.sh
+
+.PHONY: check-policies
+check-policies:
+	docker run --rm -v $(PWD)/model:/source -v $(PWD)/docs:/spec -v $(PWD)/policies:/policies \
+		otel/weaver:${WEAVER_VERSION} registry check \
+		--registry=/source \
+		--policy=/policies/registry.rego \
+		--policy=/policies/attribute_name_collisions.rego \
+		--policy=/policies/yaml_schema.rego

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/attributes-registry/gcp.md

@@ -6,18 +6,10 @@
 
 # GCP
 
-- [GCP Attributes](#gcp-attributes)
 - [GCP Client Attributes](#gcp-client-attributes)
 - [GCP - Google Cloud Run Attributes](#gcp---google-cloud-run-attributes)
 - [GCP - Google Compute Engine (GCE) Attributes](#gcp---google-compute-engine-gce-attributes)
 
-## GCP Attributes
-
-Attributes for Google Cloud
-
-| Attribute | Type | Description | Examples | Stability |
-| --------- | ---- | ----------- | -------- | --------- |
-
 ## GCP Client Attributes
 
 Attributes for Google Cloud client libraries.

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