Logs API
Status: Stable, except where otherwise specified
Note: this document defines a log backend API. The API is not intended to be called by application developers directly. It 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 consist of these main components:
- LoggerProvider is the entry point of the API. It provides access to
Logger
s. - Logger is responsible for emitting logs as LogRecords.
graph TD A[LoggerProvider] -->|Get| B(Logger) B -->|Emit| C(LogRecord)
LoggerProvider
Logger
s 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, thename
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 Logger
s describes instances where all
parameters are equal. The term distinct applied to Logger
s describes
instances where at least one parameter has a different value.
Logger
The Logger
is responsible for emitting LogRecord
s. There are two types of
logging operations:
- Log Bridge operations to be used when receiving data from other logging libraries.
- Log Instrumentation operations to be used when writing instrumentation for OpenTelemetry.
The Logger contains methods for both types of operations. The Logger
MUST
provide a function to:
The Logger
SHOULD provide functions to:
Log Bridge operations
Log Bridge operations are not intended to be used for writing instrumentation, and SHOULD include documentation that discourages this use.
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). If unspecified the implementation SHOULD set it equal to the current time.
- 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)
Enabled
Status: Development
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)
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.
Log Instrumentation operations
Emit an Event
Status: Development
The effect of calling this API is to emit a LogRecord
to the processing pipeline
formatted as an event.
Parameters:
- The
Name
of the Event. - Timestamp (optional)
- Observed Timestamp (optional). If unspecified the implementation SHOULD set it equal to the current time.
- The Context associated with the
Event
. 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
Attributes
conform to the standard definition of an attribute.
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
Feedback
Was this page helpful?
Thank you. Your feedback is appreciated!
Please let us know how we can improve this page. Your feedback is appreciated!