Events API Interface
Status: Experimental
Overview
Wikipedia’s definition of log file:
In computing, a log file is a file that records either events that occur in an operating system or other software runs.
From OpenTelemetry’s perspective LogRecords and Events are both represented using the same data model.
However, OpenTelemetry does recognize a subtle semantic difference between
LogRecords and Events: Events are LogRecords which have a name
and domain
.
Within a particular domain
, the name
uniquely defines a particular class or
type of event. Events with the same domain
/ name
follow the same schema
which assists in analysis in observability platforms. Events are described in
more detail in the semantic conventions.
While the logging space has a diverse legacy with many existing logging libraries in different languages, there is not ubiquitous alignment with OpenTelemetry events. In some logging libraries, producing records shaped as OpenTelemetry events is clunky or error-prone.
The Event API offers convenience methods for emitting LogRecords that conform to the semantic conventions for Events. Unlike the Logs Bridge API, application developers and instrumentation authors are encouraged to call this API directly.
EventLogger
The EventLogger
is the entrypoint of the Event API, and is responsible for
emitting Events
as LogRecord
s.
EventLogger Operations
The EventLogger
MUST provide functions to:
Create EventLogger
New EventLogger
instances are created though a constructor or factory method
on EventLogger
.
Parameters:
logger
- the delegate Logger used to emitEvents
asLogRecord
s.event_domain
- the domain of emitted events, used to set theevent.domain
attribute.
Emit Event
Emit a LogRecord
representing an Event
to the delegate Logger
.
This function MAY be named logEvent
.
Parameters:
event_name
- the Event name. This argument MUST be recorded as aLogRecord
attribute with the keyevent.name
. Care MUST be taken by the implementation to not override or delete this attribute while the Event is emitted to preserve its identity.logRecord
- the LogRecord representing the Event.
Implementation Requirements:
The implementation MUST emit the logRecord
to
the logger
specified when creating the EventLogger
after making the following changes:
- The
event_domain
specified when creating the EventLogger MUST be set as theevent.domain
attribute on thelogRecord
. - The
event_name
MUST be set as theevent.name
attribute on thelogRecord
.