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 e786696f29..cf4bf51164 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -27,10 +27,10 @@ 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). > 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. +> 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. Instrumentations MAY capture inputs and outputs if and only if application has enabled the collection of this data. This is for three primary reasons: 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 %}