From 8195103d6bef90b19d5f6b938bdf18bdd3ae10b6 Mon Sep 17 00:00:00 2001 From: Santosh Cheler Date: Wed, 9 Nov 2022 11:01:28 -0800 Subject: [PATCH] Clarification on what an Event is, and what the event.domain and event.name attributes represent (#2848) * Remove language around uniqueness of event names within a domain This came up in https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/14474 where it was highlighted that just `name` is not sufficient to provide for uniqueness of a Kubernetes Event. The attribute `event.domain` is only meant to be a logical separation across different event systems, so it allows for similar looking names in different domains but with a completely different purpose. However, within each domain we don't have to have any uniqueness constraints on the `name` and leave it to whatever is idiomatic to the particular event system the domain represents. --- CHANGELOG.md | 2 ++ semantic_conventions/logs/events.yaml | 7 ++-- .../logs/semantic_conventions/events.md | 35 +++++++++++++++---- 3 files changed, 33 insertions(+), 11 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a826a02d2a..8ae1720630 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -53,6 +53,8 @@ release. - Add `Context` as argument to `LogRecordProcessor#onEmit`. ([#2927](https://github.com/open-telemetry/opentelemetry-specification/pull/2927)) +- Clarification on what an Event is, and what the event.domain and event.name attributes represent + ([#2848](https://github.com/open-telemetry/opentelemetry-specification/pull/2848)) ### Resource diff --git a/semantic_conventions/logs/events.yaml b/semantic_conventions/logs/events.yaml index 246cfb551a..da8ac3ccf8 100644 --- a/semantic_conventions/logs/events.yaml +++ b/semantic_conventions/logs/events.yaml @@ -12,7 +12,7 @@ groups: examples: ['click', 'exception'] - id: domain brief: > - The domain identifies the context in which an event happened. An event name is unique only within a domain. + The domain identifies the business context for the events. type: allow_custom_values: true members: @@ -27,6 +27,5 @@ groups: brief: 'Events from Kubernetes' requirement_level: required note: | - An `event.name` is supposed to be unique only in the context of an - `event.domain`, so this allows for two events in different domains to - have same `event.name`, yet be unrelated events. + Events across different domains may have same `event.name`, yet be + unrelated events. diff --git a/specification/logs/semantic_conventions/events.md b/specification/logs/semantic_conventions/events.md index 16c132923a..ee61cf49f0 100644 --- a/specification/logs/semantic_conventions/events.md +++ b/specification/logs/semantic_conventions/events.md @@ -3,19 +3,40 @@ **Status**: [Experimental](../../document-status.md) This document describes the attributes of standalone Events that are represented -by `LogRecord`s. All standalone Events have a name and a domain. The Event domain -is a namespace for event names and is used as a mechanism to avoid conflicts of +in the data model by `LogRecord`s. Events are recorded as LogRecords that are shaped +in a special way: + +- They have a LogRecord attribute `event.name` (and possibly other LogRecord attributes). +- They have an InstrumentationScope with a non-empty `Name` and with an + InstrumentationScope attribute `event.domain` (and possibly other InstrumentationScope 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. +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 +requires multiple fields to identify the structure of the events. In such cases, +OpenTelemetry recommends using a combination of one or more fields as the name +such that the name identifies the event structurally. It is also recommended that +the event names have low-cardinality, so care must be taken to not use fields +that identify the instance of the Event and not the class of Events. + | Attribute | Type | Description | Examples | Requirement Level | |---|---|---|---|---| | `event.name` | string | The name identifies the event. | `click`; `exception` | Required | -| `event.domain` | string | The domain identifies the context in which an event happened. An event name is unique only within a domain. [1] | `browser` | Required | +| `event.domain` | string | The domain identifies the business context for the events. [1] | `browser` | Required | -**[1]:** An `event.name` is supposed to be unique only in the context of an -`event.domain`, so this allows for two events in different domains to -have same `event.name`, yet be unrelated events. +**[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. @@ -24,4 +45,4 @@ have same `event.name`, yet be unrelated events. | `browser` | Events from browser apps | | `device` | Events from mobile apps | | `k8s` | Events from Kubernetes | - \ No newline at end of file +