From 8f19d75a01ebd3ba23b64cc0649505061a592f47 Mon Sep 17 00:00:00 2001 From: Alex Van Boxel Date: Mon, 10 Jun 2024 09:44:26 +0200 Subject: [PATCH] Add more clarity on the purpose of summary --- docs/attributes-registry/event.md | 13 +++++++------ docs/general/events.md | 7 ++++--- model/logs/events.yaml | 2 +- model/registry/event.yaml | 11 ++++++++--- 4 files changed, 20 insertions(+), 13 deletions(-) diff --git a/docs/attributes-registry/event.md b/docs/attributes-registry/event.md index cfe8219f45..34be90c2d1 100644 --- a/docs/attributes-registry/event.md +++ b/docs/attributes-registry/event.md @@ -10,11 +10,12 @@ Attributes for Events represented using Log Records. -| Attribute | Type | Description | Examples | Stability | -| ------------------- | ------ | ------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | -| `event.description` | string | Human-readable message representing an event. [1] | `User clicked element with id 42`; `Device app lifecycle changed to PAUSED` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `event.name` | string | Identifies the class / type of event. [2] | `browser.mouse.click`; `device.app.lifecycle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| Attribute | Type | Description | Examples | Stability | +| --------------- | ------ | ------------------------------------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------------- | +| `event.name` | string | Identifies the class / type of event. [1] | `browser.mouse.click`; `device.app.lifecycle` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `event.summary` | string | Human-readable summary representing an event. [2] | `User clicked element with id 42`; `Device app lifecycle changed to PAUSED` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -**[1]:** Events are identified by an `event.name` and a set of attributes and fields in the body that carry specific meaning. However, since these events will be combined with other logs, `event.description` allows a centralized logging system to display a human-readable representation of the event. +**[1]:** 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. -**[2]:** 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. +**[2]:** Events are identified by an `event.name` and a set of attributes and fields in the body that carry specific meaning. However, since these events will be combined with other logs, `event.summary` allows a centralized logging system to display a human-readable representation of the event. +When summaries are generated, they are not expected to include every attribute and field that is part of the event but could contain those that are meaningful for a human operator when visually navigating a centralized log system. Instrumentation libraries that produce events defined within the standard OpenTelemetry are not expected to add an `event.summary` attribute, as these are well-known events. diff --git a/docs/general/events.md b/docs/general/events.md index b1bb2c68a7..b167e6a5ca 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -44,11 +44,12 @@ structure and semantics will also be defined. | 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) | -| [`event.description`](/docs/attributes-registry/event.md) | string | Human-readable message representing an event. [2] | `User clicked element with id 42`; `Device app lifecycle changed to PAUSED` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`event.summary`](/docs/attributes-registry/event.md) | string | Human-readable summary representing an event. [2] | `User clicked element with id 42`; `Device app lifecycle changed to PAUSED` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | **[1]:** 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. -**[2]:** Events are identified by an `event.name` and a set of attributes and fields in the body that carry specific meaning. However, since these events will be combined with other logs, `event.description` allows a centralized logging system to display a human-readable representation of the event. +**[2]:** Events are identified by an `event.name` and a set of attributes and fields in the body that carry specific meaning. However, since these events will be combined with other logs, `event.summary` allows a centralized logging system to display a human-readable representation of the event. +When summaries are generated, they are not expected to include every attribute and field that is part of the event but could contain those that are meaningful for a human operator when visually navigating a centralized log system. Instrumentation libraries that produce events defined within the standard OpenTelemetry are not expected to add an `event.summary` attribute, as these are well-known events. @@ -72,7 +73,7 @@ structure and semantics will also be defined. and the semantic conventions will define the expected structure of the _payload_ (data) for the event. * The _payload_ (data) SHOULD be used to represent the structure of the event. -* The event MAY have an `event.message` attribute that is a human-readable +* The event MAY have an `event.summary` attribute that is a human-readable representation of the event. Recommendations for defining events: diff --git a/model/logs/events.yaml b/model/logs/events.yaml index acc0f8822a..123e672d52 100644 --- a/model/logs/events.yaml +++ b/model/logs/events.yaml @@ -6,5 +6,5 @@ groups: attributes: - ref: event.name requirement_level: required - - ref: event.description + - ref: event.summary requirement_level: recommended diff --git a/model/registry/event.yaml b/model/registry/event.yaml index 6614c2af21..028279873d 100644 --- a/model/registry/event.yaml +++ b/model/registry/event.yaml @@ -16,13 +16,18 @@ groups: separation of semantics for events in separate domains like browser, mobile, and kubernetes. examples: ['browser.mouse.click', 'device.app.lifecycle'] - - id: description + - id: summary type: string stability: experimental brief: > - Human-readable message representing an event. + Human-readable summary representing an event. note: > Events are identified by an `event.name` and a set of attributes and fields in the body that carry specific - meaning. However, since these events will be combined with other logs, `event.description` allows a + meaning. However, since these events will be combined with other logs, `event.summary` allows a centralized logging system to display a human-readable representation of the event. + + When summaries are generated, they are not expected to include every attribute and field that is part of the + event but could contain those that are meaningful for a human operator when visually navigating a centralized + log system. Instrumentation libraries that produce events defined within the standard OpenTelemetry are not + expected to add an `event.summary` attribute, as these are well-known events. examples: ['User clicked element with id 42', 'Device app lifecycle changed to PAUSED']