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 LogRecords.

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 emit Events as LogRecords.
  • event_domain - the domain of emitted events, used to set the event.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 a LogRecord attribute with the key event.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 the event.domain attribute on the logRecord.
  • The event_name MUST be set as the event.name attribute on the logRecord.