From d6364ff0b50f51b6191ef09439b78c523fe1d86e Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Tue, 3 Dec 2024 13:47:47 -0800 Subject: [PATCH 1/7] =?UTF-8?q?Deprecate=20=1Bvent.name=20attribute?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/attributes-registry/event.md | 4 +-- docs/azure/events.md | 2 +- docs/exceptions/exceptions-spans.md | 2 +- docs/feature-flags/feature-flags-logs.md | 2 +- docs/general/events.md | 28 +++---------------- docs/general/session.md | 4 +-- docs/mobile/events.md | 4 +-- docs/rpc/rpc-spans.md | 2 +- model/event/common.yaml | 9 ------ .../registry-deprecated.yaml} | 8 ++---- templates/registry/markdown/event_macros.j2 | 2 +- 11 files changed, 16 insertions(+), 51 deletions(-) delete mode 100644 model/event/common.yaml rename model/event/{registry.yaml => deprecated/registry-deprecated.yaml} (51%) diff --git a/docs/attributes-registry/event.md b/docs/attributes-registry/event.md index 4489039554..7b00cb83c5 100644 --- a/docs/attributes-registry/event.md +++ b/docs/attributes-registry/event.md @@ -12,6 +12,4 @@ Attributes for Events represented using Log Records. | Attribute | Type | Description | Examples | Stability | |---|---|---|---|---| -| `event.name` | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1] `event.name`:** 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. +| `event.name` | string | Identifies the class / type of event. | `browser.mouse.click`; `device.app.lifecycle` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by EventName top-level field on the LogRecord | diff --git a/docs/azure/events.md b/docs/azure/events.md index dcf10fc02d..4e8d402088 100644 --- a/docs/azure/events.md +++ b/docs/azure/events.md @@ -16,7 +16,7 @@ Resource Log events. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The event name MUST be `az.resource.log`. +The [EventName](TODO link to new spec model) MUST be `az.resource.log`. 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. diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index afcb5a50c3..99e2f1043f 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -49,7 +49,7 @@ try { **Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) -The event name MUST be `exception`. +The [EventName](TODO link to new spec model) MUST be `exception`. This event describes a single exception. diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 1f601e9e71..64d6ce71bb 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -50,7 +50,7 @@ The table below indicates which attributes should be added to the **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The event name MUST be `feature_flag.evaluation`. +The [EventName](TODO link to new spec model) MUST be `feature_flag.evaluation`. Defines feature flag evaluation as an event. diff --git a/docs/general/events.md b/docs/general/events.md index 15ae55be53..2e2a990a7e 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -32,29 +32,9 @@ field semantics, and stability and requirement levels. Other events may be user- bespoke user semantics. When an Event name exists in the semantic conventions, its _payload_ structure and semantics will also be defined. -## Event definition +## General event semantics - - - - - - - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`event.name`](/docs/attributes-registry/event.md) | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - -**[1] `event.name`:** 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. - - - - - - -### General event semantics - -* An event MUST have an `event.name` attribute that uniquely identifies the event. +* An event MUST have an [Event name property](TODO link to new spec model) that uniquely identifies the event. * It MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) attributes that provide additional context about the event. * It MAY contain a _payload_ (body) that describes the specific details of the @@ -87,7 +67,7 @@ Recommendations on using attributes vs. body fields: * If the field should be comparable across every type of record, it should be an attribute. * If the field is specific to the event itself, then it should be a body field. -* Unless the same `event.name` exists on two events, anything in two event bodies is not comparable to each other. +* Unless two events share the same `EventName` property value, anything in two event bodies is not comparable to each other. ### Event payload (body) @@ -95,7 +75,7 @@ Recommendations on using attributes vs. body fields: requirements don't apply to event payload fields. * The definition for OpenTelemetry defined events supports describing individual _fields_ (Body Fields) - * The _fields_ are unique to the named event (`event.name`) and different events + * The _fields_ are unique to the named event ([EventName](TODO link to new spec model)) and different events may use the same _field_ name to represent different data, due to the unique nature of the event. diff --git a/docs/general/session.md b/docs/general/session.md index 8302097127..b7de42492e 100644 --- a/docs/general/session.md +++ b/docs/general/session.md @@ -40,7 +40,7 @@ backends can link the two sessions (see [Session Start Event](#session-start-eve ![Experimental](https://img.shields.io/badge/-experimental-blue) -`event.name` MUST be`session.start` +[EventName](TODO link to new spec model) 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, @@ -61,7 +61,7 @@ that the previous session has ended. If the session ID in `session.previous_id` ![Experimental](https://img.shields.io/badge/-experimental-blue) -`event.name` MUST be `session.end` +[EventName](TODO link to new spec model) 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 diff --git a/docs/mobile/events.md b/docs/mobile/events.md index df2e4bb7e2..cc6794536d 100644 --- a/docs/mobile/events.md +++ b/docs/mobile/events.md @@ -4,7 +4,7 @@ This document defines semantic conventions for instrumentations that emit events on mobile platforms. All mobile events MUST use a namespace of -`device` in the `event.name` property. +`device` in the EventName LogRecord property. @@ -29,7 +29,7 @@ application lifecycle. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The event name MUST be `device.app.lifecycle`. +The [EventName](TODO link to new spec model) MUST be `device.app.lifecycle`. This event represents an occurrence of a lifecycle transition on Android or iOS platform. diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 20928f293e..d22b130c7d 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -266,7 +266,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The event name MUST be `rpc.message`. +The [EventName](TODO link to new spec model) MUST be `rpc.message`. Describes a message sent or received within the context of an RPC call. diff --git a/model/event/common.yaml b/model/event/common.yaml deleted file mode 100644 index 8e68c5a909..0000000000 --- a/model/event/common.yaml +++ /dev/null @@ -1,9 +0,0 @@ -groups: - - id: event - type: attribute_group - stability: experimental - brief: > - This document defines attributes for Events represented using Log Records. - attributes: - - ref: event.name - requirement_level: required diff --git a/model/event/registry.yaml b/model/event/deprecated/registry-deprecated.yaml similarity index 51% rename from model/event/registry.yaml rename to model/event/deprecated/registry-deprecated.yaml index c8c540e052..37f2da56b3 100644 --- a/model/event/registry.yaml +++ b/model/event/deprecated/registry-deprecated.yaml @@ -1,5 +1,5 @@ groups: - - id: registry.event + - id: registry.event.deprecated type: attribute_group display_name: Event Attributes brief: > @@ -8,11 +8,7 @@ groups: - id: event.name type: string stability: experimental + deprecated: "Replaced by EventName top-level field on the LogRecord" brief: > Identifies the class / type of event. - note: > - 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. examples: ["browser.mouse.click", "device.app.lifecycle"] diff --git a/templates/registry/markdown/event_macros.j2 b/templates/registry/markdown/event_macros.j2 index c6ef8ef6fa..20fcce6550 100644 --- a/templates/registry/markdown/event_macros.j2 +++ b/templates/registry/markdown/event_macros.j2 @@ -3,7 +3,7 @@ {% import 'body_field_table.j2' as body_table %} {% macro header(event) %}**Status:** {{ stability.badge(event.stability, event.deprecated) }} -The event name MUST be `{{ event.name }}`. +The [EventName](TODO link to new spec model) MUST be `{{ event.name }}`. {{ event.brief | trim }} {%if event.note %} From 7e05277f0733097a0a7212f47c317c43b6745dd2 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 11 Dec 2024 20:58:54 -0800 Subject: [PATCH 2/7] reword --- docs/attributes-registry/event.md | 15 ----------- docs/azure/events.md | 2 +- docs/exceptions/exceptions-spans.md | 2 +- docs/feature-flags/feature-flags-logs.md | 2 +- docs/gen-ai/gen-ai-events.md | 17 ++++++++----- docs/general/events.md | 28 ++++++++++----------- docs/general/session.md | 4 +-- docs/mobile/events.md | 2 +- docs/rpc/rpc-spans.md | 2 +- templates/registry/markdown/event_macros.j2 | 2 +- 10 files changed, 32 insertions(+), 44 deletions(-) delete mode 100644 docs/attributes-registry/event.md diff --git a/docs/attributes-registry/event.md b/docs/attributes-registry/event.md deleted file mode 100644 index 7b00cb83c5..0000000000 --- a/docs/attributes-registry/event.md +++ /dev/null @@ -1,15 +0,0 @@ - - - - - -# Event - -## Event Attributes - -Attributes for Events represented using Log Records. - -| Attribute | Type | Description | Examples | Stability | -|---|---|---|---|---| -| `event.name` | string | Identifies the class / type of event. | `browser.mouse.click`; `device.app.lifecycle` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by EventName top-level field on the LogRecord | diff --git a/docs/azure/events.md b/docs/azure/events.md index 4e8d402088..f0e7ebb60c 100644 --- a/docs/azure/events.md +++ b/docs/azure/events.md @@ -16,7 +16,7 @@ Resource Log events. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](TODO link to new spec model) MUST be `az.resource.log`. +The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `az.resource.log`. 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. diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index 99e2f1043f..c0d947b0b4 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -49,7 +49,7 @@ try { **Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) -The [EventName](TODO link to new spec model) MUST be `exception`. +The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `exception`. This event describes a single exception. diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 64d6ce71bb..3d145c14de 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -50,7 +50,7 @@ The table below indicates which attributes should be added to the **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](TODO link to new spec model) MUST be `feature_flag.evaluation`. +The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `feature_flag.evaluation`. Defines feature flag evaluation as an event. diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md index 4c12ee55d5..05df5e4a61 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -23,10 +23,15 @@ linkTitle: Generative AI events -GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/logs/event-api.md). +GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/logs/api.md#emit-an-event). +<<<<<<< HEAD > [!NOTE] > Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md#events) to see the implementation status in corresponding language. +======= +> Note: +> Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language. +>>>>>>> 75746bc9 (reword) Instrumentations MAY capture inputs and outputs if and only if application has enabled the collection of this data. This is for three primary reasons: @@ -57,7 +62,7 @@ Instrumentations MAY offer configuration options allowing to disable events or a **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The event name MUST be `gen_ai.system.message`. +The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `gen_ai.system.message`. This event describes the system instructions passed to the GenAI model. @@ -112,7 +117,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The event name MUST be `gen_ai.user.message`. +The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `gen_ai.user.message`. This event describes the user message passed to the GenAI model. @@ -167,7 +172,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The event name MUST be `gen_ai.assistant.message`. +The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `gen_ai.assistant.message`. This event describes the assistant message passed to GenAI system. @@ -237,7 +242,7 @@ Semantic conventions for individual systems MAY specify a different type for arg **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The event name MUST be `gen_ai.tool.message`. +The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `gen_ai.tool.message`. This event describes the response from a tool or function call passed to the GenAI model. @@ -293,7 +298,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The event name MUST be `gen_ai.choice`. +The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `gen_ai.choice`. This event describes the Gen AI response message. diff --git a/docs/general/events.md b/docs/general/events.md index 2e2a990a7e..22d9467e15 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -5,7 +5,7 @@ aliases: [events-general] # Semantic Conventions for Events -**Status**: [Experimental][DocumentStatus] +**Status**: [Development][DocumentStatus] This document describes the characteristics of standalone Events that are represented in the data model by `LogRecord`s. @@ -15,11 +15,7 @@ Semantically, an Event is a named occurrence at an instant in time. It signals t Examples of Events might include things like uncaught exceptions, button clicks, user logout, network connection severed, etc. -In OpenTelemetry, Events are implemented as a specific type of `LogRecord` that conforms to -the conventions included here, and Events -[have their own API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md). -The API abstracts away knowledge of `LogRecord` so that users only deal with Event -semantics. +In OpenTelemetry, Events are implemented as a specific type of [`LogRecord`](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.39.0/specification/logs/api.md) that conforms to the conventions included here. In addition to a required name, an Event may contain a _payload_ (body) of any type permitted by the [LogRecord body](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body). @@ -34,7 +30,8 @@ structure and semantics will also be defined. ## General event semantics -* An event MUST have an [Event name property](TODO link to new spec model) that uniquely identifies the event. +* An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) + that uniquely identifies the event. * It MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) attributes that provide additional context about the event. * It MAY contain a _payload_ (body) that describes the specific details of the @@ -53,21 +50,22 @@ Recommendations for defining events: collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) attributes. * Events SHOULD be generated / produced / recorded using the - [Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/event-api.md) + [Emit Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/tree/v1.40.0/specification/logs/api.md#emit-an-event) to ensure that the event is created using the configured SDK instance. - * The Event API is not yet available in all OpenTelemetry SDKs. - * TODO: Add deep link to the [compliance matrix of the Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md) - when it exists. -* It's NOT RECOMMENDED to prefix the _payload_ (body) _fields_ with the `event.name` to + * The Emit Event API is not yet available in all OpenTelemetry SDKs. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language. +* It's NOT RECOMMENDED to prefix the _payload_ (body) _fields_ with the `EventName` to avoid redundancy and to keep the event definition clean. * The events SHOULD document their semantic conventions including event name, attributes, and the payload. Recommendations on using attributes vs. body fields: -* If the field should be comparable across every type of record, it should be an attribute. +* If the field should be comparable across events with different `EventName` (or between an event and other telemetry items), + it should be an attribute. * If the field is specific to the event itself, then it should be a body field. -* Unless two events share the same `EventName` property value, anything in two event bodies is not comparable to each other. +* Body fields that belong to events with different event names are not comparable. + For example, body field `id` on event `my_company.order_submitted` is semantically different from + field `id` on an event with name `session.start`. ### Event payload (body) @@ -75,7 +73,7 @@ Recommendations on using attributes vs. body fields: requirements don't apply to event payload fields. * The definition for OpenTelemetry defined events supports describing individual _fields_ (Body Fields) - * The _fields_ are unique to the named event ([EventName](TODO link to new spec model)) and different events + * The _fields_ are unique to the named event ([EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname)) and different events may use the same _field_ name to represent different data, due to the unique nature of the event. diff --git a/docs/general/session.md b/docs/general/session.md index b7de42492e..18c0c447cf 100644 --- a/docs/general/session.md +++ b/docs/general/session.md @@ -40,7 +40,7 @@ backends can link the two sessions (see [Session Start Event](#session-start-eve ![Experimental](https://img.shields.io/badge/-experimental-blue) -[EventName](TODO link to new spec model) MUST be`session.start` +[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) 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, @@ -61,7 +61,7 @@ that the previous session has ended. If the session ID in `session.previous_id` ![Experimental](https://img.shields.io/badge/-experimental-blue) -[EventName](TODO link to new spec model) MUST be `session.end` +[EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) 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 diff --git a/docs/mobile/events.md b/docs/mobile/events.md index cc6794536d..6970f638d0 100644 --- a/docs/mobile/events.md +++ b/docs/mobile/events.md @@ -29,7 +29,7 @@ application lifecycle. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](TODO link to new spec model) MUST be `device.app.lifecycle`. +The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `device.app.lifecycle`. This event represents an occurrence of a lifecycle transition on Android or iOS platform. diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index d22b130c7d..0bb6715e9f 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -266,7 +266,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](TODO link to new spec model) MUST be `rpc.message`. +The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `rpc.message`. Describes a message sent or received within the context of an RPC call. diff --git a/templates/registry/markdown/event_macros.j2 b/templates/registry/markdown/event_macros.j2 index 20fcce6550..8f78275659 100644 --- a/templates/registry/markdown/event_macros.j2 +++ b/templates/registry/markdown/event_macros.j2 @@ -3,7 +3,7 @@ {% import 'body_field_table.j2' as body_table %} {% macro header(event) %}**Status:** {{ stability.badge(event.stability, event.deprecated) }} -The [EventName](TODO link to new spec model) MUST be `{{ event.name }}`. +The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `{{ event.name }}`. {{ event.brief | trim }} {%if event.note %} From fad18219f8a66f8768c9a42a555d9430a2737faf Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 11 Dec 2024 21:11:13 -0800 Subject: [PATCH 3/7] add note on event naming --- docs/general/events.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/general/events.md b/docs/general/events.md index 22d9467e15..10f10cc058 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -31,8 +31,8 @@ structure and semantics will also be defined. ## General event semantics * An event MUST have an [Event name property](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) - that uniquely identifies the event. -* It MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) + that uniquely identifies the event. Event names are subject to the same rules as [attribute names](/docs/general/attribute-naming.md). +* Event MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) attributes that provide additional context about the event. * It MAY contain a _payload_ (body) that describes the specific details of the named event. From e96607ebd3c6aeb17789bb9f7da56768736bb99a Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 12 Dec 2024 08:43:20 -0800 Subject: [PATCH 4/7] changelog and some fixes --- .chloggen/1646.yaml | 4 ++++ docs/attributes-registry/event.md | 15 +++++++++++++++ docs/azure/events.md | 2 +- docs/exceptions/exceptions-spans.md | 2 +- docs/feature-flags/feature-flags-logs.md | 2 +- docs/mobile/events.md | 2 +- docs/rpc/rpc-spans.md | 2 +- templates/registry/markdown/event_macros.j2 | 2 +- 8 files changed, 25 insertions(+), 6 deletions(-) create mode 100644 .chloggen/1646.yaml create mode 100644 docs/attributes-registry/event.md diff --git a/.chloggen/1646.yaml b/.chloggen/1646.yaml new file mode 100644 index 0000000000..778acd9c9a --- /dev/null +++ b/.chloggen/1646.yaml @@ -0,0 +1,4 @@ +change_type: breaking +component: event +note: Deprecate `event.name` attribute in favor of the top level event name property on the log record +issues: [1646] diff --git a/docs/attributes-registry/event.md b/docs/attributes-registry/event.md new file mode 100644 index 0000000000..7b00cb83c5 --- /dev/null +++ b/docs/attributes-registry/event.md @@ -0,0 +1,15 @@ + + + + + +# Event + +## Event Attributes + +Attributes for Events represented using Log Records. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `event.name` | string | Identifies the class / type of event. | `browser.mouse.click`; `device.app.lifecycle` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)
Replaced by EventName top-level field on the LogRecord | diff --git a/docs/azure/events.md b/docs/azure/events.md index f0e7ebb60c..dcf10fc02d 100644 --- a/docs/azure/events.md +++ b/docs/azure/events.md @@ -16,7 +16,7 @@ Resource Log events. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `az.resource.log`. +The event name MUST be `az.resource.log`. 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. diff --git a/docs/exceptions/exceptions-spans.md b/docs/exceptions/exceptions-spans.md index c0d947b0b4..afcb5a50c3 100644 --- a/docs/exceptions/exceptions-spans.md +++ b/docs/exceptions/exceptions-spans.md @@ -49,7 +49,7 @@ try { **Status:** ![Stable](https://img.shields.io/badge/-stable-lightgreen) -The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `exception`. +The event name MUST be `exception`. This event describes a single exception. diff --git a/docs/feature-flags/feature-flags-logs.md b/docs/feature-flags/feature-flags-logs.md index 3d145c14de..1f601e9e71 100644 --- a/docs/feature-flags/feature-flags-logs.md +++ b/docs/feature-flags/feature-flags-logs.md @@ -50,7 +50,7 @@ The table below indicates which attributes should be added to the **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `feature_flag.evaluation`. +The event name MUST be `feature_flag.evaluation`. Defines feature flag evaluation as an event. diff --git a/docs/mobile/events.md b/docs/mobile/events.md index 6970f638d0..e81a7da8b2 100644 --- a/docs/mobile/events.md +++ b/docs/mobile/events.md @@ -29,7 +29,7 @@ application lifecycle. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `device.app.lifecycle`. +The event name MUST be `device.app.lifecycle`. This event represents an occurrence of a lifecycle transition on Android or iOS platform. diff --git a/docs/rpc/rpc-spans.md b/docs/rpc/rpc-spans.md index 0bb6715e9f..20928f293e 100644 --- a/docs/rpc/rpc-spans.md +++ b/docs/rpc/rpc-spans.md @@ -266,7 +266,7 @@ different processes could be listening on TCP port 12345 and UDP port 12345. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `rpc.message`. +The event name MUST be `rpc.message`. Describes a message sent or received within the context of an RPC call. diff --git a/templates/registry/markdown/event_macros.j2 b/templates/registry/markdown/event_macros.j2 index 8f78275659..c6ef8ef6fa 100644 --- a/templates/registry/markdown/event_macros.j2 +++ b/templates/registry/markdown/event_macros.j2 @@ -3,7 +3,7 @@ {% import 'body_field_table.j2' as body_table %} {% macro header(event) %}**Status:** {{ stability.badge(event.stability, event.deprecated) }} -The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `{{ event.name }}`. +The event name MUST be `{{ event.name }}`. {{ event.brief | trim }} {%if event.note %} From 04c3005f1b5c9fe0cd5edf39e4a401929a96ae57 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 12 Dec 2024 08:49:45 -0800 Subject: [PATCH 5/7] regenerate areas --- .github/ISSUE_TEMPLATE/bug_report.yaml | 1 - .github/ISSUE_TEMPLATE/change_proposal.yaml | 1 - .github/ISSUE_TEMPLATE/new-conventions.yaml | 1 - 3 files changed, 3 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index d65a7ffc55..43a6c3c748 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.github/ISSUE_TEMPLATE/bug_report.yaml @@ -42,7 +42,6 @@ body: - area:dns - area:dotnet - area:error - - area:event - area:exception - area:faas - area:feature-flag diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index 920ab75c84..bb0d28736a 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.github/ISSUE_TEMPLATE/change_proposal.yaml @@ -34,7 +34,6 @@ body: - area:dns - area:dotnet - area:error - - area:event - area:exception - area:faas - area:feature-flag diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml index e63b412b75..eb43279195 100644 --- a/.github/ISSUE_TEMPLATE/new-conventions.yaml +++ b/.github/ISSUE_TEMPLATE/new-conventions.yaml @@ -43,7 +43,6 @@ body: - area:dns - area:dotnet - area:error - - area:event - area:exception - area:faas - area:feature-flag From 4fba709fd6708d2e12cd44ce6a81cb2be725ad9d Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 12 Dec 2024 18:30:52 -0800 Subject: [PATCH 6/7] up --- docs/gen-ai/gen-ai-events.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md index 05df5e4a61..cc77890c73 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -62,7 +62,7 @@ Instrumentations MAY offer configuration options allowing to disable events or a **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `gen_ai.system.message`. +The event name MUST be `gen_ai.system.message`. This event describes the system instructions passed to the GenAI model. @@ -117,7 +117,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `gen_ai.user.message`. +The event name MUST be `gen_ai.user.message`. This event describes the user message passed to the GenAI model. @@ -172,7 +172,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `gen_ai.assistant.message`. +The event name MUST be `gen_ai.assistant.message`. This event describes the assistant message passed to GenAI system. @@ -242,7 +242,7 @@ Semantic conventions for individual systems MAY specify a different type for arg **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `gen_ai.tool.message`. +The event name MUST be `gen_ai.tool.message`. This event describes the response from a tool or function call passed to the GenAI model. @@ -298,7 +298,7 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. **Status:** ![Experimental](https://img.shields.io/badge/-experimental-blue) -The [EventName](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/data-model.md#field-eventname) MUST be `gen_ai.choice`. +The event name MUST be `gen_ai.choice`. This event describes the Gen AI response message. From 11409ede063dde03b603b51a299bc2c02c2fe1be Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Fri, 13 Dec 2024 10:16:43 -0800 Subject: [PATCH 7/7] fix broken link --- docs/general/events.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/general/events.md b/docs/general/events.md index 10f10cc058..c63aa5904a 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -50,7 +50,7 @@ Recommendations for defining events: collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute) attributes. * Events SHOULD be generated / produced / recorded using the - [Emit Event API](https://github.com/open-telemetry/opentelemetry-specification/blob/tree/v1.40.0/specification/logs/api.md#emit-an-event) + [Emit Event API](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.40.0/specification/logs/api.md#emit-an-event) to ensure that the event is created using the configured SDK instance. * The Emit Event API is not yet available in all OpenTelemetry SDKs. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language. * It's NOT RECOMMENDED to prefix the _payload_ (body) _fields_ with the `EventName` to