Logs API

Status: Stable, except where otherwise specified

Table of Contents

LoggerProvider
- LoggerProvider operations
  - Get a Logger
Logger
- Emit a LogRecord
- Enabled
Optional and required parameters
Concurrency requirements
References

The Logs API is provided for logging library authors to build log appenders, which use this API to bridge between existing logging libraries and the OpenTelemetry log data model.

The Logs API can also be directly called by instrumentation libraries as well as instrumented libraries or applications.

The Logs API consist of these main components:

LoggerProvider is the entry point of the API. It provides access to Loggers.
Logger is responsible for emitting logs as LogRecords.

graph TD
    A[LoggerProvider] -->|Get| B(Logger)
    B -->|Emit| C(LogRecord)

Loading

LoggerProvider

Loggers can be accessed with a LoggerProvider.

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

LoggerProvider operations

The LoggerProvider MUST provide the following functions:

Get a Logger

Get a Logger

This API MUST accept the following instrumentation scope parameters:

name: Specifies the name of 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. For log sources which define a logger name (e.g. Java Logger Name) the Logger Name should be recorded as the instrumentation scope name.
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.

The term identical applied to Loggers describes instances where all parameters are equal. The term distinct applied to Loggers describes instances where at least one parameter has a different value.

Logger

The Logger is responsible for emitting LogRecords.

The Logger MUST provide a function to:

Emit a LogRecord

The Logger SHOULD provide functions to:

Report if Logger is Enabled

Emit a LogRecord

The effect of calling this API is to emit a LogRecord to the processing pipeline.

The API MUST accept the following parameters:

Timestamp (optional)
Observed Timestamp (optional)
The Context associated with the LogRecord. When implicit Context is supported, then this parameter SHOULD be optional and if unspecified then MUST use current Context. When only explicit Context is supported, this parameter SHOULD be required.
Severity Number (optional)
Severity Text (optional)
Body (optional)
Attributes (optional)
Event Name (optional)

Status: Development

The API SHOULD provide functionality for users to convert Standard Attributes so they can be used, or directly accept them, in the log signal. This allows the reuse of Standard Attributes across signals.

Enabled

To help users avoid performing computationally expensive operations when generating a LogRecord, a Logger SHOULD provide this Enabled API.

The API SHOULD accept the following parameters:

The Context to be associated with the LogRecord. When implicit Context is supported, then this parameter SHOULD be optional and if unspecified then MUST use current Context. When only explicit Context is supported, accepting this parameter is REQUIRED.
Severity Number (optional)
Event Name (optional)

This API MUST return a language idiomatic boolean type. A returned value of true means the Logger is enabled for the provided arguments, and a returned value of false means the Logger is disabled for the provided arguments.

The returned value is not always static, it can change over time. The API SHOULD be documented that instrumentation authors needs to call this API each time they emit a LogRecord to ensure they have the most up-to-date response.

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.

Concurrency requirements

For languages which support concurrent execution the Logs APIs provide specific guarantees and safeties.

LoggerProvider - all methods are safe to be called concurrently.

Logger - all methods are safe to be called concurrently.

References

OTEP0150 Logging Library SDK Prototype Specification

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!