open-telemetry
/
semantic-conventions
mirror of https://github.com/open-telemetry/semantic-conventions.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Deprecate `event.name` attribute in favor of EventName on the log record (#1646)

This commit is contained in:
Liudmila Molkova 2024-12-16 20:21:17 -08:00 committed by GitHub
parent 01be4a4240
commit a596f197d5
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
11 changed files with 31 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.chloggen/1646.yaml Normal file
View File

@ -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]

1
.github/ISSUE_TEMPLATE/bug_report.yaml vendored
View File

@ -42,7 +42,6 @@ body:
- area:dns
- area:dotnet
- area:error
- area:event
- area:exception
- area:faas
- area:feature-flag

1
.github/ISSUE_TEMPLATE/change_proposal.yaml vendored
View File

@ -34,7 +34,6 @@ body:
- area:dns
- area:dotnet
- area:error
- area:event
- area:exception
- area:faas
- area:feature-flag

1
.github/ISSUE_TEMPLATE/new-conventions.yaml vendored
View File

@ -43,7 +43,6 @@ body:
- area:dns
- area:dotnet
- area:error
- area:event
- area:exception
- area:faas
- area:feature-flag

4
docs/attributes-registry/event.md
View File

@ -12,6 +12,4 @@ Attributes for Events represented using Log Records.
| Attribute | Type | Description | Examples | Stability |
|---|---|---|---|---|
| <a id="event-name" href="#event-name">`event.name`</a> | 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.
| <a id="event-name" href="#event-name">`event.name`</a> | string | Identifies the class / type of event. | `browser.mouse.click`; `device.app.lifecycle` | ![Deprecated](https://img.shields.io/badge/-deprecated-red)<br>Replaced by EventName top-level field on the LogRecord |

7
docs/gen-ai/gen-ai-events.md
View File

@ -23,10 +23,15 @@ linkTitle: Generative AI events
<!-- tocstop -->
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:

52
docs/general/events.md
View File

@ -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).
@ -32,30 +28,11 @@ 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
<!-- semconv event -->
<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
<!-- see templates/registry/markdown/snippet.md.j2 -->
<!-- prettier-ignore-start -->
<!-- markdownlint-capture -->
<!-- markdownlint-disable -->
| 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.
<!-- markdownlint-restore -->
<!-- prettier-ignore-end -->
<!-- END AUTOGENERATED TEXT -->
<!-- endsemconv -->
### General event semantics
* An event MUST have an `event.name` attribute that uniquely identifies the event.
* It MAY have [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.39.0/specification/common#attribute)
* 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. 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.
@ -73,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/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 the same `event.name` exists on two events, 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)
@ -95,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 (`event.name`) 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.

4
docs/general/session.md
View File

@ -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](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)
`event.name` 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

2
docs/mobile/events.md
View File

@ -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.
<!-- toc -->

9
model/event/common.yaml
View File

@ -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

8
model/event/registry.yaml → model/event/deprecated/registry-deprecated.yaml
View File

@ -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"]