-
Notifications
You must be signed in to change notification settings - Fork 163
/
events.md
115 lines (89 loc) · 6.11 KB
/
events.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
<!--- Hugo front matter used to generate the website version of this page:
linkTitle: Events
aliases: [events-general]
--->
# Semantic Conventions for Events
**Status**: [Experimental][DocumentStatus]
This document describes the characteristics of standalone Events that are represented
in the data model by `LogRecord`s.
Semantically, an Event is a named occurrence at an instant in time. It signals that
"this thing happened at this time" and provides additional specifics about the occurrence.
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 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).
In its implementation, the Event _payload_ (body) will constitute the `Body` of the `LogRecord`.
Like all other OpenTelemetry signals, an Event has optional attribute metadata that helps describe
the event context.
Over time, some Events will be specified by OpenTelemetry and will have documented payload structure,
field semantics, and stability and requirement levels. Other events may be user-defined and carry
bespoke user semantics. When an Event name exists in the semantic conventions, its _payload_
structure and semantics will also be defined.
## Event definition
<!-- 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` |  |
**[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.
<!-- 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.35.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.
* The event name uniquely identifies event structure / type of the _payload_ (body)
and the set of attributes.
* The _payload_ (body) MAY contain any type supported by the OpenTelemetry data
model for the log [body](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/logs/data-model.md#field-body)
and the semantic conventions will define the expected structure of the _payload_
(body) for the event.
* The _payload_ (body) SHOULD be used to represent the structure of the event.
Recommendations for defining events:
* Use the _payload_ (body) to represent the details of the event instead of a
collection of [standard](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.35.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)
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
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 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.
### Event payload (body)
* Common attribute naming conventions and [registry](../attributes-registry/README.md)
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
may use the same _field_ name to represent different data, due to the unique
nature of the event.
## External event compatibility
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 use fields
that identify the class of Events but not the instance of the Event.
[DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status