Skip to content

Latest commit

 

History

History
167 lines (118 loc) · 6.78 KB

event-api.md

File metadata and controls

167 lines (118 loc) · 6.78 KB
Raw

Events API

Status: Development

Table of Contents

The Event API consists of these main components:

  • EventLoggerProvider is the entry point of the API. It provides access to EventLoggers.
  • EventLogger is the component responsible for emitting events.

Event Data model

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. An Event is a specialized type of LogRecord, not a separate concept.

Events are OpenTelemetry's standardized semantic formatting for LogRecords. Beyond the structure provided by the LogRecord data model, it is helpful for logs to have a common format within that structure. When OpenTelemetry instrumentation emits logs, those logs SHOULD be formatted as Events. All semantic conventions defined for logs MUST be formatted as Events.

The Event format is as follows. All Events have a name attribute, and all Events with the same name MUST conform to the same schema for both their Attributes and their Body.

Event API use cases

The Events API was designed to allow shared libraries to emit high quality logs without needing to depend on a third party logger. Unlike the Logs Bridge API, instrumentation authors and application developers are encouraged to call this API directly. It is appropriate to use the Event API when these properties fit your requirements:

  • Logging from a shared library that must run in many applications.
  • A semantic convention needs to be defined. We do not define semantic conventions for LogRecords that are not Events.
  • Analysis by an observability platform is the intended use case. For example: statistics, indexing, machine learning, session replay.
  • Normalizing logging and having a consistent schema across a large application is helpful.

If any of these properties fit your requirements, we recommend using the Event API. Events are described in more detail in the semantic conventions.

Please note that the OpenTelemetry Log SDK currently lacks a number of advanced features present in popular logging libraries. For example: pattern logging, file rotation, network appenders, etc. These features cannot be used with the OpenTelemetry Event SDK at this time.

If a logging library is capable of creating logs which correctly map to the Event data model, logging in this manner is also an acceptable way to create Events.

EventLoggerProvider

EventLoggers can be accessed with a EventLoggerProvider.

Normally, the EventLoggerProvider is expected to be accessed from a central place. Thus, the API SHOULD provide a way to set/register and access a global default EventLoggerProvider.

EventLoggerProvider operations

The EventLoggerProvider MUST provide the following functions:

  • Get an EventLogger

Get an EventLogger

This API MUST accept the following parameters:

  • name: This name uniquely identifies the instrumentation scope, such as the instrumentation library (e.g. io.opentelemetry.contrib.mongodb), package, module or class name. If an application or library has built-in OpenTelemetry instrumentation, both Instrumented library and Instrumentation library may refer to the same library. In that scenario, the name denotes a module name or component name within that library or application.

  • version (optional): Specifies the version of the instrumentation scope if the scope has a version (e.g. a library version). Example value: 1.0.0.

  • schema_url (optional): Specifies the Schema URL that should be recorded in the emitted telemetry.

  • attributes (optional): Specifies the instrumentation scope attributes to associate with emitted telemetry. This API MUST be structured to accept a variable number of attributes, including none.

EventLoggers are identified by name, version, and schema_url fields. When more than one EventLogger of the same name, version, and schema_url is created, it is unspecified whether or under which conditions the same or different EventLogger instances are returned. It is a user error to create EventLoggers with different attributes but the same identity.

The effect of associating a Schema URL with a EventLogger MUST be that the telemetry emitted using the EventLogger will be associated with the Schema URL, provided that the emitted data format is capable of representing such association.

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:

Emit Event

The effect of calling this API is to emit an Event to the processing pipeline.

Parameters:

  • The Name of the Event, as described in event.name semantic conventions.
  • The (AnyValue) (optional) Body of the Event.
  • The Timestamp (optional) of the Event.
  • The Context (optional) associated with the Event.
  • The SeverityNumber (optional) of the Event.
  • The Attributes (optional) of the Event. Event Attributes provide additional details about the Event which are not part of the well-defined event Body.

Optional and required parameters

The operations defined include various parameters, some of which are marked optional. Parameters not marked optional are required.

For each optional parameter, the API MUST be structured to accept it, but MUST NOT obligate a user to provide it.

For each required parameter, the API MUST be structured to obligate a user to provide it.

References