diff --git a/.chloggen/1296.yaml b/.chloggen/1296.yaml new file mode 100644 index 0000000000..8a1347f20a --- /dev/null +++ b/.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 ] 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/.chloggen/session_start_end_event.yaml b/.chloggen/session_start_end_event.yaml new file mode 100755 index 0000000000..1dd2bf020d --- /dev/null +++ b/.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: diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 40af0a175b..b09b4102e4 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -16,6 +16,7 @@ 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 @@ -23,6 +24,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/docs/general/session.md b/docs/general/session.md index 3c4d50209f..99ab4d63f5 100644 --- a/docs/general/session.md +++ b/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. +## 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 diff --git a/docs/non-normative/code-generation.md b/docs/non-normative/code-generation.md new file mode 100644 index 0000000000..e8e22d8848 --- /dev/null +++ b/docs/non-normative/code-generation.md @@ -0,0 +1,193 @@ + + +# Generating Semantic Convention libraries + + + +- [Stability and Versioning](#stability-and-versioning) + - [Deprecated Conventions](#deprecated-conventions) +- [Semantic Conventions Artifact Structure](#semantic-conventions-artifact-structure) +- [Generating semantic conventions](#generating-semantic-conventions) + - [Migrating from build-tools](#migrating-from-build-tools) + - [Weaver config](#weaver-config) + - [Jinja templates](#jinja-templates) + + + +The code for OpenTelemetry Semantic Conventions defined in this repository can be auto-generated. + +OpenTelemetry Language SIGs can generate Semantic Conventions code in the form that's idiomatic for +their language and may (or may not) ship it as a stand-alone library. + +This document outlines common patterns and provides non-normative guidance on how to structure semantic conventions artifacts +and generate the code. + +## Stability and Versioning + +Semantic Conventions contain a mix of stability levels. +Language SIGs that ship semantic conventions library may decide to ship a stable artifact with stable part of the Semantic Conventions, a preview artifact with all Semantic Conventions, or other combination that's idiomatic for this language and provides [SemVer 2.0](https://semver.org/) stability guarantees. + +Possible solutions include: + +- Generate all Semantic Conventions for a given version in specific folder while keeping old versions intact. It is used by [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go/tree/main/semconv/) but could be problematic if the artifact size is a concern. +- Follow language-specific conventions to annotate experimental parts. For example, Semantic Conventions in Python puts experimental attributes in `opentelemetry.semconv._incubating` import path which is considered (following Python underscore convention) to be internal and subject to change. +- Ship two different artifacts: one that contains stable Semantic Conventions and another one with all available conventions. For example, [semantic-conventions in Java](https://github.com/open-telemetry/semantic-conventions-java) are shipped in two artifacts: `opentelemetry-semconv` and `opentelemetry-semconv-incubating`. + +> Note: +> Shipping two versions of the same artifact (stable and preview) could be problematic due to diamond-dependency problems. +> For example, if user application depends on the `semconv v1.0.0-preview` and some library brings transitive dependency on `semconv v1.1.0` that does not contain +> experimental conventions, the latter would be resolved leading to compilation or runtime issues in the application. + +Instrumentation libraries should depend on the stable (part of) semantic convention artifact or copy relevant definitions into their own code base. +Experimental semantic conventions are intended for end-user applications. + +### Deprecated Conventions + +It's recommended to generate code for deprecated attributes, metrics, and other conventions. Use appropriate annotations to mark them as deprecated. +Conventions have a `stability` property which provide the stability level at the deprecation time (`experimental` or `stable`) and +the `deprecated` property that describes deprecation reason which can be used to generate documentation. + +- Deprecated conventions that reached stability should not be removed without major version update according to SemVer. +- Conventions that were deprecated while being experimental should still be generated and kept in the preview (part of) semantic conventions artifact. It minimizes runtime issues + and breaking changes in user applications. + +Keep stable convention definitions inside the preview (part of) semantic conversions artifact. It prevents user code from breaking when semantic convention stabilizes. Deprecate stable definitions inside the preview artifact and point users to the stable location in generated documentation. +For example, in Java, the attribute `http.request.method` is defined as deprecated in both stable and preview artifacts (e.g., `io.opentelemetry.semconv.incubating.HttpIncubatingAttributes.HTTP_REQUEST_METHOD`, `io.opentelemetry.semconv.HttpAttributes.HTTP_REQUEST_METHOD`). + +## Semantic Conventions Artifact Structure + +This section contains suggestions on how to structure semantic convention artifact(s). + +- Artifact name: + - `opentelemetry-semconv` - stable conventions + - `opentelemetry-semconv-incubating` - (if applicable) the preview artifact containing all (stable and experimental) conventions +- Namespace: `opentelemetry.semconv` and `opentelemetry.semconv.incubating` +- All supported Schema URLs should be listed to allow different instrumentations in the same application to provide the exact version of conventions they follow. +- Attributes, metrics, and other convention definitions should be grouped by the convention type and the root namespace. See the example below: + +``` +├── SchemaUrls.code +├── attributes +│ ├── ClientAttributes.code +│ ├── HttpAttributes.code +│ └── ... +├── metrics +│ ├── HttpMetrics.code +│ └── ... +└── events + └── ... +``` + +## Generating semantic conventions + +This section describes how to do code-generation with weaver. + +> [!IMPORTANT] +> We're transitioning from [build-tools](https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/README.md#code-generator) +> to [opentelemetry-weaver](https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md) to generate code for semantic conventions. +> All new code-generation should be done using weaver, build-tools may become incompatible with future version of semantic conventions. + +Code-generation is based on YAML definitions in the specific version of semantic conventions. +Usually, it involves several steps where some can be semi-automated: +involves several steps which could be semi-automated: + +1. Manually update the Semantic Conventions version in config +2. Add the new Schema URL to the list of supported versions + - If it's not automated, then it can, at least, be automatically checked. +3. Check out (or download) the new version of Semantic Conventions +4. Run code-generation script (see below for the details) +5. Fix lint violations in the auto-generated code (if any) +6. Send the PR with new code to the corresponding repository + +Here are examples of how steps 2-5 are implemented for [Python](https://github.com/open-telemetry/opentelemetry-python/pull/4091) and [Erlang](https://github.com/open-telemetry/opentelemetry-erlang/pull/733). + +Step 4 (running code generation) depends on language-specific customizations. It's also the only step that's affected by tooling migration. + +Check out [weaver code-generation documentation for more details](https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md) + +### Migrating from build-tools + +Migration from build-tools involves changing Jinja templates and adding a [weaver config file](https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md#configuration-file---weaveryaml). + +#### Weaver config + +Here's a simplified example of this file that generates all attributes. + +```yaml +params: + excluded_namespaces: [ios, aspnetcore, signalr, android, dotnet, jvm, kestrel] + +templates: + - pattern: semantic_attributes.j2 + filter: > + semconv_grouped_attributes({ + "exclude_root_namespace": $excluded_namespaces + }) + | map({ + root_namespace: .root_namespace, + attributes: .attributes, + output: $output + "attributes/" + }) + application_mode: each +``` + +You can configure language-specific parameters in the `params` section of the config or pass them with `-DparamName=value` arguments when +running weaver command from the code generation script (similarly to build-tools). + +Weaver is able to run code-generation for multiple templates (defined in the corresponding section) at once. + +Before executing Jinja, weaver allows to filter or process semantic convention definitions in the `filter` section for each template. +In this example, it uses `semconv_grouped_attributes` filter - a helper method that groups attribute definitions by root namespace and excludes +attributes not relevant to this language. You can write alternative or additional filters and massage semantic conventions data using [JQ](https://jqlang.github.io/jq/manual/). + +In certain cases, calling `semconv_grouped_attributes` with namespace exclusion and stability filters may be enough and post-processing is not necessary. + +The `application_mode: each` configures weaver to run code generation for each semantic convention group and, as a consequence, +generate code for each group in a different file. The application mode `single` is also supported to apply the template to all groups at once. + +See +[weaver code-generation docs](https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md) +for the details on the config, data schema, JQ filters, and more. + +#### Jinja templates + +Jinja templates need to be changed to leverage (better) data structure and helper methods. +The first key difference is that each jinja template can define how to name the corresponding file(s). If you +don't specify the name of the output file via the method `set_file_name`, Weaver will use the relative path +and the name of the template itself to determine the output file. + +E.g. here's an example that uses root namespace in a subfolder provided in the `output` parameter. + +```jinja +{% set file_name = ctx.output + (ctx.root_namespace | snake_case ) ~ "_attributes.py" -%} +{{- template.set_file_name(file_name) -}} +``` + +Notable changes on data structure: + +- `attributes_and_templates` -> `ctx.attributes` +- `enum_attributes` -> `ctx.attributes | select("enum")` +- `metrics` -> `ctx.metrics` +- `root_namespace` -> `ctx.root_namespace` (only available if using `semconv_grouped_attributes` or similar filter)' +- all custom parameters are provided as properties under `ctx` variable. +- `attribute.fqn` -> `attribute.name` +- `attribute.type | instantiated_type` (gets underlying type of enum values) +- `attribute.attr_type.members` -> `attribute.type.members` (gets members of enum type) +- `member.member_id` -> `member.id` (gets id of the enum member) + +Notable changes on helper methods: + +- `attr.fqn | to_const_name` -> `attr.name | screaming_snake_case` +- `attr.fqn | to_camelcase(True)` -> `attr.name | pascal_case` +- `attr.brief | to_doc_brief | indent` -> `attr.brief | comment_with_prefix(" ")` (prefix is used to indent) +- stability/deprecation checks: + - `attribute is stable` if checking one attribute, `attributes | select("stable")` to filter stable attributes + - `attribute is experimental` if checking one attribute, `attributes | select("experimental")` to filter experimental attributes + - `attribute is deprecated` if checking one attribute, `attributes | select("deprecated")` to filter deprecated attributes +- check if attribute is a template: `attribute.type is template_type` +- `print_member_value` - no replacement at this time, use something like `{%- if type == "string" -%}"{{value}}"{%-else-%}{{value}}{%-endif-%}` +- new way to simplify switch-like logic: `key | map_text("map_name")`. Maps can be defined in the weaver config. + It can be very useful to convert semantic convention attribute types to language-specific types. diff --git a/docs/non-normative/libraries.md b/docs/non-normative/libraries.md deleted file mode 100644 index 320627ed3e..0000000000 --- a/docs/non-normative/libraries.md +++ /dev/null @@ -1,123 +0,0 @@ - - -# Semantic convention libraries - - - -- [Stability and Versioning](#stability-and-versioning) - - [Deprecated Conventions](#deprecated-conventions) -- [Semantic Conventions Artifact Structure](#semantic-conventions-artifact-structure) -- [Generating semantic conventions](#generating-semantic-conventions) - - - -The code for OpenTelemetry Semantic Conventions defined in this repository can be auto-generated. - -OpenTelemetry Language SIGs can generate Semantic Conventions code in the form that's idiomatic for -their language and may (or may not) ship it as a stand-alone library. - -This document outlines common patterns and provides non-normative guidance on how to structure semantic conventions artifact -and generate the code. - -## Stability and Versioning - -Semantic Conventions contain a mix of stability levels. -Language SIGs that ship semantic conventions library may decide to ship a stable artifact with stable part of the Semantic Conventions, a preview artifact with all Semantic Conventions, or other combination that's idiomatic for this language and provides [SemVer 2.0](https://semver.org/) stability guarantees. - -Possible solutions include: - -- Generate all Semantic Conventions for a given version in specific folder while keeping old versions intact. It is used by [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go/tree/main/semconv/) but could be problematic if the artifact size is a concern. -- Follow language-specific conventions to annotate experimental parts. For example, Semantic Conventions in Python puts experimental attributes in `opentelemetry.semconv._incubating` import path which is considered (following Python underscore convention) to be internal and subject to change. -- Ship two different artifacts: one that contains stable Semantic Conventions and another one with all available conventions. For example, [semantic-conventions in Java](https://github.com/open-telemetry/semantic-conventions-java) are shipped in two artifacts: `opentelemetry-semconv` and `opentelemetry-semconv-incubating`. - -> Note: -> Shipping two versions of the same artifact (stable and preview) could be problematic due to diamond-dependency problems. -> For example, if user application depends on the `semconv v1.0.0-preview` and some library brings transitive dependency on `semconv v1.1.0` that does not contain -> experimental conventions, the latter would be resolved leading to compilation or runtime issues in the application. - -Instrumentation libraries should depend on the stable (part of) semantic convention artifact or copy relevant definitions into their own code base. -Experimental semantic conventions are intended for end-user applications. - -### Deprecated Conventions - -It's recommended to generate code for deprecated attributes, metrics, and other conventions. Use appropriate annotations to mark them as deprecated. -Conventions have a `stability` property which provide the stability level at the deprecation time (`experimental` or `stable`) and -the `deprecated` property that describes deprecation reason which can be used to generate documentation. - -- Deprecated conventions that reached stability should not be removed without major version update according to SemVer. -- Conventions that were deprecated while being experimental should still be generated and kept in the preview (part of) semantic conventions artifact. It minimizes runtime issues - and breaking changes in user applications. - -Keep stable convention definitions inside the preview (part of) semantic conversions artifact. It prevents user code from breaking when semantic convention stabilizes. Deprecate stable definitions inside the preview artifact and point users to the stable location in generated documentation. -For example, in Java `http.request.method` attribute is defined as the deprecated `io.opentelemetry.semconv.incubating.HttpIncubatingAttributes.HTTP_REQUEST_METHOD` field and also as stable `io.opentelemetry.semconv.HttpAttributes.HTTP_REQUEST_METHOD`. - -## Semantic Conventions Artifact Structure - -This section contains suggestions on structuring semantic convention artifact(s) which should be adjusted to the specific language. - -- Artifact name: - - `opentelemetry-semconv` - stable conventions - - `opentelemetry-semconv-incubating` - (if applicable) the preview artifact containing all conventions -- Namespace: `opentelemetry.semconv` and `opentelemetry.semconv.incubating` -- All supported Schema URLs should be listed to allow different instrumentations in the same application to provide the exact version of conventions they follow. -- Attributes, metrics, and other convention definitions should be grouped by the convention type and the root namespace. See the example below: - -``` -├── SchemaUrls.code -├── attributes -│ ├── ClientAttributes.code -│ ├── HttpAttributes.code -│ └── ... -├── metrics -│ ├── HttpMetrics.code -│ └── ... -└── events - └── ... -``` - -## Generating semantic conventions - -> Note: -> The tooling used for code generation may change to [opentelemetry-weaver](https://github.com/open-telemetry/weaver), -> without any breaking changes in the generated code and with minimal changes to generation process and templates. - -The generation is done using [build-tools code generator](https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/README.md#code-generator). -It's based on YAML definitions of the semantic conventions and uses [Jinja templates](https://palletsprojects.com/p/jinja/). - -For example, this Jinja template can be used to generate Python constant for an attribute name along with the docstring. - -```jinja -{{attribute.fqn | to_const_name}} = "{{attribute.fqn}}" -""" -{{attribute.brief | to_doc_brief}}. -{%- if attribute.note %} -Note: {{attribute.note | to_doc_brief | indent}}. -{%- endif %} -""" -``` - -It generates the following code: - -```python -SERVER_ADDRESS = "server.address" -""" -Server domain name if available without reverse DNS lookup; otherwise, IP address or Unix domain socket name. -Note: When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. -""" -``` - -Language SIGs are expected to create Jinja templates specific to their language. -Code-generation usually involves several steps which could be semi-automated: - -1. Manually update the Semantic Conventions version when necessary -2. Add the new Schema URL to the list of supported versions - - If it's not automated, then it can, at least, be automatically checked. -3. Check out (or download) this version of Semantic Conventions -4. Run code-generation script for each template -5. Fix lint violations in the auto-generated code (if any) -6. Send the PR with new code to the corresponding repository - -Here are examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/397e357dfad3e6ff42c09c74d5945dfdcad24bdd/scripts/semconv/generate.sh). 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"