diff --git a/CHANGELOG.md b/CHANGELOG.md index fe2a62e63b..bfe047e7bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,8 @@ release. - Rename metrics `jvm.memory.usage` to `jvm.memory.used` and `jvm.memory.usage_after_last_gc` to `jvm.memory.used_after_last_gc` ([#536](https://github.com/open-telemetry/semantic-conventions/pull/536)) +- BREAKING: Change `event.name` definition to include `namespace` and remove `event.domain` from log event attributes. + ([#473](https://github.com/open-telemetry/semantic-conventions/pull/473)) ### Features diff --git a/docs/general/events.md b/docs/general/events.md index 3ca2c7cd89..8fcd24cf8a 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -17,20 +17,10 @@ The following semantic conventions for events are defined: ## General event attributes -Events are recorded as LogRecords that are shaped -in a special way: Event LogRecords have the attributes `event.domain` -and `event.name` (and possibly other LogRecord attributes). - -The `event.domain` attribute is used to logically separate events from different -systems. For example, to record Events from browser apps, mobile apps and -Kubernetes, we could use `browser`, `device` and `k8s` as the domain for their -Events. This provides a clean separation of semantics for events in each of the -domains. - -Within a particular domain, the `event.name` attribute identifies the event. -Events with same domain and name are structurally similar to one another. For -example, some domains could have well-defined schema for their events based on -event names. +Events are recorded as LogRecords that are shaped in a special way: Event +LogRecords have the attribute `event.name` that uniquely identifies the event. +Events with same `event.name` are structurally similar to one another. Events +may also have other LogRecord attributes. When recording events from an existing system as OpenTelemetry Events, it is possible that the existing system does not have the equivalent of a name or @@ -43,18 +33,9 @@ that identify the class of Events but not the instance of the Event. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| -| `event.domain` | string | The domain identifies the business context for the events. [1] | `browser` | Required | -| `event.name` | string | The name identifies the event. | `click`; `exception` | Required | - -**[1]:** Events across different domains may have same `event.name`, yet be unrelated events. - -`event.domain` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used. +| `event.name` | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | Required | -| Value | Description | -|---|---| -| `browser` | Events from browser apps | -| `device` | Events from mobile apps | -| `k8s` | Events from Kubernetes | +**[1]:** Event names are subject to the same rules as [attribute names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/common/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. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/document-status.md diff --git a/docs/mobile/events.md b/docs/mobile/events.md index df020e2c04..70a5d6fdc3 100644 --- a/docs/mobile/events.md +++ b/docs/mobile/events.md @@ -2,8 +2,9 @@ **Status**: [Experimental][DocumentStatus] -This document defines semantic conventions for instrumentations that emit events on mobile platforms. -All mobile events MUST set `event.domain` as `device`. +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. @@ -15,13 +16,15 @@ All mobile events MUST set `event.domain` as `device`. ## Lifecycle instrumentation -This section defines how to apply semantic conventions when instrumenting application lifecycle. -This event is meant to be used in conjunction with `os.name` [resource semantic convention](/docs/resource/os.md) to identify the mobile operating system (e.g. Android, iOS). +This section defines how to apply semantic conventions when instrumenting +application lifecycle. This event is meant to be used in conjunction with +`os.name` [resource semantic convention](/docs/resource/os.md) to identify the +mobile operating system (e.g. Android, iOS). ### iOS -The event name MUST be `app.lifecycle`. +The event name MUST be `device.app.lifecycle`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| @@ -43,7 +46,7 @@ The event name MUST be `app.lifecycle`. ### Android -The event name MUST be `app.lifecycle`. +The event name MUST be `device.app.lifecycle`. | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| diff --git a/model/logs/events.yaml b/model/logs/events.yaml index aed530cb1c..3942d432fd 100644 --- a/model/logs/events.yaml +++ b/model/logs/events.yaml @@ -9,24 +9,10 @@ groups: type: string requirement_level: required brief: > - The name identifies the event. - examples: ['click', 'exception'] - - id: domain - brief: > - The domain identifies the business context for the events. - type: - allow_custom_values: true - members: - - id: browser - value: 'browser' - brief: 'Events from browser apps' - - id: device - value: 'device' - brief: 'Events from mobile apps' - - id: k8s - value: 'k8s' - brief: 'Events from Kubernetes' - requirement_level: required + Identifies the class / type of event. note: > - Events across different domains may have same `event.name`, yet be - unrelated events. + Event names are subject to the same rules as [attribute names](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.26.0/specification/common/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/model/logs/mobile-events.yaml b/model/logs/mobile-events.yaml index 797851cb48..d6f49e70c5 100644 --- a/model/logs/mobile-events.yaml +++ b/model/logs/mobile-events.yaml @@ -2,9 +2,9 @@ groups: - id: ios.lifecycle.events type: event prefix: ios - name: app.lifecycle + name: device.app.lifecycle brief: > - This event represents an occurrence of a lifecycle transition on the iOS platform. `event.domain` MUST be `device`. + This event represents an occurrence of a lifecycle transition on the iOS platform. attributes: - id: state requirement_level: "required" @@ -41,10 +41,9 @@ groups: - id: android.lifecycle.events type: event prefix: android - name: app.lifecycle + name: device.app.lifecycle brief: > This event represents an occurrence of a lifecycle transition on the Android platform. - `event.domain` MUST be `device`. attributes: - id: state requirement_level: required