Merging events domain and name (open-telemetry#473)

Co-authored-by: jason plumb <[email protected]> Co-authored-by: Tigran Najaryan <[email protected]> Co-authored-by: jack-berg <[email protected]> Co-authored-by: Joao Grassi <[email protected]> Co-authored-by: Alexander Wert <[email protected]>
dynatrace-oss-contrib · Nov 24, 2023 · 12dfe6a · 12dfe6a
1 parent 9d9990c
commit 12dfe6a
Show file tree

Hide file tree

Showing 5 changed files with 26 additions and 55 deletions.
diff --git 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
@@ -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.
 <!-- semconv 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.
 <!-- endsemconv -->
 
 [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
@@ -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.
 
 <!-- toc -->
 
@@ -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
 
 <!-- semconv ios.lifecycle.events -->
-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
 
 <!-- semconv android.lifecycle.events -->
-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
@@ -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
@@ -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