From 45f6847479520a607d1f484925110af9810f90af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 25 Sep 2024 10:19:17 +0200 Subject: [PATCH 01/20] Use Logs API to emit Events --- spec-compliance-matrix.md | 20 --- specification/README.md | 4 +- specification/glossary.md | 4 +- specification/logs/README.md | 34 ++-- specification/logs/{bridge-api.md => api.md} | 39 +++-- specification/logs/event-api.md | 162 ------------------ specification/logs/event-sdk.md | 110 ------------ specification/logs/noop.md | 10 +- specification/logs/sdk.md | 10 +- .../logs/supplementary-guidelines.md | 16 +- specification/versioning-and-stability.md | 6 +- 11 files changed, 63 insertions(+), 352 deletions(-) rename specification/logs/{bridge-api.md => api.md} (87%) delete mode 100644 specification/logs/event-api.md delete mode 100644 specification/logs/event-sdk.md diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 790875d9e32..54e9fe80ee8 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -203,26 +203,6 @@ Disclaimer: this list of features is still a work in progress, please refer to t | Can plug custom LogRecordExporter | | | + | | + | | | + | | + | | | | Trace Context Injection | | | + | | + | | | + | | + | + | | -## Events - -Features for the [Events API](specification/logs/event-api.md) and the [Events SDK](specification/logs/event-sdk.md). -Disclaimer: Events are currently in Development status - work in progress. - -| Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -|----------------------------------------------------------------------------|----------|----|------|----|--------|------|--------|-----|------|-----|------|-------| -| [EventLoggerProvider](specification/logs/event-api.md#eventloggerprovider) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -| Get EventLogger | | | | | | | | | | | | | -| Get EventLogger accepts version | X | | | | | | | | | | | | -| Get EventLogger accepts schema_url | X | | | | | | | | | | | | -| Get EventLogger accepts attributes | X | | | | | | | | | | | | -| [EventLogger](specification/logs/event-api.md#eventlogger) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -| Emit event accepts name | | | | | | | | | | | | | -| Emit event accepts AnyValue body | X | | | | | | | | | | | | -| Emit event accepts severity | X | | | | | | | | | | | | -| Emit event accepts timestamp | X | | | | | | | | | | | | -| Emit event accepts attributes | X | | | | | | | | | | | | -| Emit event accepts context | X | | | | | | | | | | | | - ## Resource | Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | diff --git a/specification/README.md b/specification/README.md index d1136d70243..39100606db2 100644 --- a/specification/README.md +++ b/specification/README.md @@ -28,9 +28,7 @@ path_base_for_github_subdir: - [Baggage](baggage/api.md) - [Tracing](trace/api.md) - [Metrics](metrics/api.md) - - [Logs](logs/README.md) - - [Bridge API](logs/bridge-api.md) - - [Event API](logs/event-api.md) + - [Logs](logs/api.md) - SDK Specification - [Tracing](trace/sdk.md) - [Metrics](metrics/sdk.md) diff --git a/specification/glossary.md b/specification/glossary.md index 55504f499f5..e2366ee3c49 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -192,7 +192,7 @@ concept the attributes of the scope cannot change at runtime. This refers to the `name` and (optional) `version` arguments specified when creating a new `Tracer` or `Meter` (see -[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider))/[Obtaining a Logger](logs/bridge-api.md#loggerprovider). +[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider))/[Obtaining a Logger](logs/api.md#loggerprovider). The name/version pair identifies the [Instrumentation Scope](#instrumentation-scope), for example the [Instrumentation Library](#instrumentation-library) or another unit of @@ -250,7 +250,7 @@ recommended to call it out specifically. ### Log Appender / Bridge A log appender or bridge is a component which bridges logs from an existing log -API into OpenTelemetry using the [Log Bridge API](./logs/bridge-api.md). The +API into OpenTelemetry using the [Logs (Bridge) API](./logs/api.md). The terms "log bridge" and "log appender" are used interchangeably, reflecting that these components bridge data into OpenTelemetry, but are often called appenders in the logging domain. diff --git a/specification/logs/README.md b/specification/logs/README.md index 61de647230d..f52a7b5de82 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -140,16 +140,18 @@ Given the above state of the logging space we took the following approach: OpenTelemetry log data model. OpenTelemetry Collector can read such logs and translate them to OpenTelemetry log data model. -- OpenTelemetry defines a Logs Bridge API - for [emitting LogRecords](./bridge-api.md#emit-a-logrecord). Application developers are - NOT encouraged to call this API directly. It is provided for library authors - to build [log appender](../glossary.md#log-appender--bridge), which use - the API to bridge between existing logging libraries and the OpenTelemetry log - data model. Existing logging libraries generally provide a much richer set of - features than what is defined in OpenTelemetry. It is NOT a goal of - OpenTelemetry to ship a feature-rich logging library. - -- OpenTelemetry defines an [SDK](./sdk.md) implementation of the [Bridge API](./bridge-api.md), +- OpenTelemetry defines a Logs API for [emitting LogRecords](./api.md#emit-a-logrecord). + It is provided for library authors to build [log appender](../glossary.md#log-appender--bridge), + which use the API to bridge between existing logging libraries and the + OpenTelemetry log data model. + The [API](./api.md) is also provided for instrumentation libraries to emit log + records following semantic conventions (also known as OpenTelemetry Events). + Existing logging libraries generally provide a much richer set of features + than what is defined in OpenTelemetry. It is NOT a goal of OpenTelemetry to + ship a feature-rich logging library. However, nothing prevents application + developers to use it directly. + +- OpenTelemetry defines an [SDK](./sdk.md) implementation of the [API](./api.md), which enables configuration of [processing](./sdk.md#logrecordprocessor) and [exporting](./sdk.md#logrecordexporter) LogRecords. @@ -230,10 +232,9 @@ processor. ### Infrastructure Logs These are logs generated by various infrastructure components, such as -Kubernetes events (if you are wondering why events are discussed in the context -of logs see [Event API Data model](./event-api.md#event-data-model)). Like system logs, the -infrastructure logs lack a trace context and can be enriched by the resource -context - information about the node, pod, container, etc. +Kubernetes events. Like system logs, the infrastructure logs lack a trace +context and can be enriched by the resource context - information about +the node, pod, container, etc. OpenTelemetry Collector or other agents can be used to query logs from most common infrastructure controllers. @@ -359,7 +360,7 @@ as parsers, log tailing and rotation. It also enables the possibility to send logs directly to the logging backend without using a log collection agent. To facilitate both approaches described above OpenTelemetry provides -a [Bridge API](./bridge-api.md) and [SDK](./sdk.md), which can be used together with existing +a [API](./api.md) and [SDK](./sdk.md), which can be used together with existing logging libraries to automatically inject the trace context in the emitted logs, and provide an easy way to send the logs via OTLP. Instead of modifying each logging statement, [log appenders](../glossary.md#log-appender--bridge) @@ -444,10 +445,9 @@ standard output. ## Specifications -* [Logs Bridge API](./bridge-api.md) +* [Logs API](./api.md) * [Logs SDK](./sdk.md) * [Logs Data Model](./data-model.md) -* [Event API](./event-api.md) * [Trace Context in non-OTLP Log Formats](../compatibility/logging_trace_context.md) ## References diff --git a/specification/logs/bridge-api.md b/specification/logs/api.md similarity index 87% rename from specification/logs/bridge-api.md rename to specification/logs/api.md index 0d1e80d7cd7..411e411d56b 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/api.md @@ -1,4 +1,4 @@ -# Logs Bridge API +# Logs API **Status**: [Stable](../document-status.md), except where otherwise specified @@ -9,6 +9,7 @@ +- [Overview](#overview) - [LoggerProvider](#loggerprovider) * [LoggerProvider operations](#loggerprovider-operations) + [Get a Logger](#get-a-logger) @@ -25,14 +26,27 @@ -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](./supplementary-guidelines.md#how-to-create-a-log4j-log-appender), +## Overview + +This document defines a log *backend* API. + +The API serves following use cases. + +It is provided for instrumentation libraries to emit events (log records following +OpenTelemetry Semantic Conventions). + +It is provided for logging library authors to build +[log appenders/bridges](./supplementary-guidelines.md#how-to-create-a-log4j-log-appender), which use this API to bridge between existing logging libraries and the -OpenTelemetry log data model. +OpenTelemetry log data model. -The Logs Bridge API consist of these main components: +It is provided for application developers to emit structured log recors +(e.g. custom events). + +Languges MAY provide a seperate Logs Bridge API if they need different +ergonimics for consumers that are building log appenders/bridges. + +The Logs API consist of these main components: * [LoggerProvider](#loggerprovider) is the entry point of the API. It provides access to `Logger`s. * [Logger](#logger) is responsible for emitting logs as @@ -167,22 +181,13 @@ provide it. ## Concurrency requirements -For languages which support concurrent execution the Logs Bridge APIs provide +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. -## Artifact Naming - -The Logs Bridge API is not intended to be called by application developers -directly, and SHOULD include documentation that discourages direct use. However, -in the event OpenTelemetry were to add a user facing API, the Logs Bridge API would -be a natural starting point. Therefore, Log Bridge API artifact, package, and class -names MUST NOT include the terms "bridge", "appender", or any other qualifier -that would prevent evolution into a user facing API. - ## References - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md deleted file mode 100644 index ea5c58116fe..00000000000 --- a/specification/logs/event-api.md +++ /dev/null @@ -1,162 +0,0 @@ -# Events API - -**Status**: [Development](../document-status.md) - -
-Table of Contents - - - - - -- [Event Data model](#event-data-model) -- [Event API use cases](#event-api-use-cases) -- [EventLoggerProvider](#eventloggerprovider) - * [EventLoggerProvider operations](#eventloggerprovider-operations) - + [Get an EventLogger](#get-an-eventlogger) -- [EventLogger](#eventlogger) - * [EventLogger Operations](#eventlogger-operations) - + [Emit Event](#emit-event) -- [Optional and required parameters](#optional-and-required-parameters) -- [References](#references) - - - -
- -The Event API consists of these main components: - -* [EventLoggerProvider](#eventloggerprovider) is the entry point of the API. It - provides access to `EventLogger`s. -* [EventLogger](#eventlogger) is the component responsible for emitting events. - -## Event Data model - -Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/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](./data-model.md). 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 -[`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md), -and all Events with the same `event.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](./bridge-api.md), 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](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). - -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 - -`EventLogger`s 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`: Specifies the name of the [instrumentation scope](../glossary.md#instrumentation-scope), - such as the [instrumentation library](../glossary.md#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](../glossary.md#instrumented-library) and - [Instrumentation library](../glossary.md#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. - -The term *identical* applied to `EventLogger`s describes instances where all -parameters are equal. The term *distinct* applied to `EventLogger`s describes -instances where at least one parameter has a different value. - -## 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: - -#### 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](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). -* The (`AnyValue`) (optional) `Body` of the Event. -* The `Timestamp` (optional) of the Event. -* The [Context](../context/README.md) (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 - -- [OTEP0202 Introducing Events and Logs API](https://github.com/open-telemetry/oteps/blob/main/text/0202-events-and-logs-api.md) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md deleted file mode 100644 index 1a9bc0ee829..00000000000 --- a/specification/logs/event-sdk.md +++ /dev/null @@ -1,110 +0,0 @@ -# Events SDK - -**Status**: [Development](../document-status.md) - -
-Table of Contents - - - - - -- [Overview](#overview) -- [EventLoggerProvider](#eventloggerprovider) - * [EventLoggerProvider Creation](#eventloggerprovider-creation) - * [EventLogger Creation](#eventlogger-creation) - * [Configuration](#configuration) - * [ForceFlush](#forceflush) -- [EventLogger](#eventlogger) - * [Emit Event](#emit-event) - - - -
- -Users of OpenTelemetry need a way for instrumentation interactions with the -OpenTelemetry API to actually produce telemetry. The OpenTelemetry SDK -(henceforth referred to as the SDK) is an implementation of the OpenTelemetry -API that provides users with this functionally. - -All implementations of the OpenTelemetry API MUST provide an SDK. - -## Overview - -From OpenTelemetry's perspective LogRecords and Events are both represented -using the same [data model](./event-api.md#event-data-model). Therefore, the default -implementation of an Event SDK MUST generate events using the [Logs Data Model](./data-model.md). - -The SDK MUST use the [Logs SDK](./sdk.md) to generate, process and export `LogRecord`s. - -## EventLoggerProvider - -The `EventLoggerProvider` MUST be implemented as a proxy to an instance of [`LoggerProvider`](./sdk.md#loggerprovider). - -All `LogRecord`s produced by any `EventLogger` from the `EventLoggerProvider` SHOULD be associated with the `Resource` from the provided `LoggerProvider`. - -### EventLoggerProvider Creation - -The SDK SHOULD allow the creation of multiple independent `EventLoggerProvider`s. - -### EventLogger Creation - -It SHOULD only be possible to create `EventLogger` instances through an `EventLoggerProvider` -(see [Events API](event-api.md)). - -The `EventLoggerProvider` MUST implement the [Get an EventLogger API](event-api.md#get-an-eventlogger). - -In the case where an invalid `name` (null or empty string) is specified, a -working `EventLogger` MUST be returned as a fallback rather than returning null or -throwing an exception. Its `name` SHOULD keep the original invalid value, and a -message reporting that the specified value is invalid SHOULD be logged. - -### Configuration - -The `EventLoggerProvider` MUST accept an instance of `LoggerProvider`. Any configuration -related to processing MUST be done by configuring the `LoggerProvider` directly. - -### ForceFlush - -This method provides a way for the provider to notify the delegate `LoggerProvider` -to force all registered [LogRecordProcessors](sdk.md#logrecordprocessor) to immediately export all -`LogRecords` that have not yet been exported. - -## EventLogger - -The `EventLogger` MUST be implemented as a proxy to an instance of [`Logger`](./sdk.md#logger). - -### Emit Event - -Emit a `LogRecord` representing an `Event`. - -**Implementation Requirements:** - -The implementation MUST use the parameters -to [emit a logRecord](./bridge-api.md#emit-a-logrecord) as follows: - -* The `Name` MUST be used to set - the `event.name` [Attribute](./data-model.md#field-attributes). If - the `Attributes` provided by the user contain an `event.name` attribute the - value provided in the `Name` takes precedence. -* If provided by the user, the `Body` MUST be used to set - the [Body](./data-model.md#field-body). If not provided, `Body` MUST not be - set. -* If provided by the user, the `Timestamp` MUST be used to set - the [Timestamp](./data-model.md#field-timestamp). If not provided, `Timestamp` - MUST be set to the current time when [emit](#emit-event) was called. -* The [Observed Timestamp](./data-model.md#field-observedtimestamp) MUST not be - set. (NOTE: [emit a logRecord](./bridge-api.md#emit-a-logrecord) will - set `ObservedTimestamp` to the current time when unset.) -* If provided by the user, the `Context` MUST be used to set - the [Context](./bridge-api.md#emit-a-logrecord). If not provided, `Context` - MUST be set to the current Context. -* If provided by the user, the `SeverityNumber` MUST be used to set - the [Severity Number](./data-model.md#field-severitynumber) when emitting the - logRecord. If not provided, `SeverityNumber` MUST be set - to `SEVERITY_NUMBER_INFO=9`. -* The [Severity Text](./data-model.md#field-severitytext) MUST not be set. -* If provided by the user, the `Attributes` MUST be used to set - the [Attributes](./data-model.md#field-attributes). The user - provided `Attributes` MUST not take over the `event.name` - attribute previously discussed. diff --git a/specification/logs/noop.md b/specification/logs/noop.md index d1f4cf6f1a3..6a1d8502106 100644 --- a/specification/logs/noop.md +++ b/specification/logs/noop.md @@ -2,7 +2,7 @@ linkTitle: No-Op ---> -# Logs Bridge API No-Op Implementation +# Logs API No-Op Implementation **Status**: [Stable](../document-status.md) @@ -23,12 +23,12 @@ linkTitle: No-Op Users of OpenTelemetry need a way to disable the API from actually performing any operations. The No-Op OpenTelemetry API implementation (henceforth referred to as the No-Op) provides users with this -functionally. It implements the [OpenTelemetry Logs Bridge API](./bridge-api.md) +functionally. It implements the [OpenTelemetry Logs API](./api.md) so that no telemetry is produced and computation resources are minimized. All language implementations of OpenTelemetry MUST provide a No-Op. -The [Logs Bridge API](./bridge-api.md) defines components with various operations. +The [Logs API](./api.md) defines components with various operations. All No-Op components MUST NOT hold configuration or operational state. All No-op operations MUST accept all defined parameters, MUST NOT validate any arguments received, and MUST NOT return any non-empty error or log any message. @@ -42,7 +42,7 @@ provide the same `LoggerProvider` instances to all creation requests. ### Logger Creation -New `Logger` instances are always created with a [LoggerProvider](./bridge-api.md#loggerprovider). +New `Logger` instances are always created with a [LoggerProvider](./api.md#loggerprovider). Therefore, `LoggerProvider` MUST allow for the creation of `Logger`s. All `Logger`s created MUST be an instance of the [No-Op Logger](#logger). @@ -54,4 +54,4 @@ return the same `Logger` instances to all creation requests. ### Emit LogRecord The No-Op `Logger` MUST allow -for [emitting LogRecords](./bridge-api.md#emit-a-logrecord). +for [emitting LogRecords](./api.md#emit-a-logrecord). diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 5d29e2b6984..7fcc1d34b40 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -59,9 +59,9 @@ The SDK SHOULD allow the creation of multiple independent `LoggerProviders`s. ### Logger Creation It SHOULD only be possible to create `Logger` instances through a `LoggerProvider` -(see [Bridge API](bridge-api.md)). +(see [API](api.md)). -The `LoggerProvider` MUST implement the [Get a Logger API](bridge-api.md#get-a-logger). +The `LoggerProvider` MUST implement the [Get a Logger API](api.md#get-a-logger). The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which @@ -186,7 +186,7 @@ It consists of the following parameters: to [No-op Logger](./noop.md#logger). The value of `disabled` MUST be used to resolve whether a `Logger` - is [Enabled](./bridge-api.md#enabled). If `disabled` is `true`, `Enabled` + is [Enabled](./api.md#enabled). If `disabled` is `true`, `Enabled` returns `false`. If `disabled` is `false`, `Enabled` returns `true`. It is not necessary for implementations to ensure that changes to `disabled` are immediately visible to callers of `Enabled`. I.e. atomic, volatile, @@ -207,7 +207,7 @@ associated with the `LogRecord`. The [trace context fields](./data-model.md#trace-context-fields) MUST be populated from the resolved `Context` (either the explicitly passed `Context` or the -current `Context`) when [emitted](./bridge-api.md#emit-a-logrecord). +current `Context`) when [emitted](./api.md#emit-a-logrecord). Counts for attributes due to collection limits MUST be available for exporters to report as described in @@ -311,7 +311,7 @@ components in the SDK: #### OnEmit -`OnEmit` is called when a `LogRecord` is [emitted](bridge-api.md#emit-a-logrecord). This +`OnEmit` is called when a `LogRecord` is [emitted](api.md#emit-a-logrecord). This method is called synchronously on the thread that emitted the `LogRecord`, therefore it SHOULD NOT block or throw exceptions. diff --git a/specification/logs/supplementary-guidelines.md b/specification/logs/supplementary-guidelines.md index 026951938b6..8108c767722 100644 --- a/specification/logs/supplementary-guidelines.md +++ b/specification/logs/supplementary-guidelines.md @@ -1,7 +1,7 @@ # Supplementary Guidelines Note: this document is NOT a spec, it is provided to support the Logs -[API](./bridge-api.md) and [SDK](./sdk.md) specifications, it does NOT add any +[API](./api.md) and [SDK](./sdk.md) specifications, it does NOT add any extra requirements to the existing specifications.
@@ -34,8 +34,8 @@ and is [one of the supported](README.md#direct-to-collector) log collection approaches. The log appender implementation will typically acquire a -[Logger](./bridge-api.md#logger), then -call [Emit LogRecord](./bridge-api.md#emit-a-logrecord) for `LogRecord`s +[Logger](./api.md#logger), then +call [Emit LogRecord](./api.md#emit-a-logrecord) for `LogRecord`s received from the application. [Implicit Context Injection](#implicit-context-injection) @@ -62,7 +62,7 @@ popular logging library. If the logging library has a concept that is similar to OpenTelemetry's definition of the [Instrumentation Scope's](../glossary.md#instrumentation-scope) name, then the appender's implementation should use that value as the -name parameter when [obtaining the Logger](./bridge-api.md#get-a-logger). +name parameter when [obtaining the Logger](./api.md#get-a-logger). This is for example applicable to: @@ -72,7 +72,7 @@ This is for example applicable to: Appenders should avoid setting any attributes of the Instrumentation Scope. Doing so may result in different appenders setting different attributes on the same Instrumentation Scope, obtained with the same identity of the -[Logger](./bridge-api.md#get-a-logger), which, according to the specification, +[Logger](./api.md#get-a-logger), which, according to the specification, is an error. ### Context @@ -81,13 +81,13 @@ is an error. When Context is implicitly available (e.g. in Java) the Appender can rely on automatic context propagation by NOT explicitly setting `Context` when -calling [emit a LogRecord](./bridge-api.md#emit-a-logrecord). +calling [emit a LogRecord](./api.md#emit-a-logrecord). Some log libraries have mechanisms specifically tailored for injecting contextual information into logs, such as MDC in Log4j. When available, it may be preferable to use these mechanisms to set the Context. A log appender can then fetch the Context and explicitly set it when -calling [emit a LogRecord](./bridge-api.md#emit-a-logrecord). This allows the correct Context +calling [emit a LogRecord](./api.md#emit-a-logrecord). This allows the correct Context to be included even when log records are emitted asynchronously, which can otherwise lead the Context to be incorrect. @@ -100,7 +100,7 @@ In order for `TraceContext` to be recorded in `LogRecord`s in languages where the Context must be provided explicitly (e.g. Go), the end user must capture the Context and explicitly pass it to the logging subsystem. The log appender must take this Context and explicitly set it when -calling [emit a LogRecord](./bridge-api.md#emit-a-logrecord). +calling [emit a LogRecord](./api.md#emit-a-logrecord). Support for OpenTelemetry for logging libraries in these languages typically can be implemented in the form of logger wrappers that can capture the context once, diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index d81831b157a..00942544e4c 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -234,9 +234,9 @@ Semantic Conventions defines the set of fields in the OTLP data model: - The attribute keys provided on the LogRecord - The attribute values provided on the LogRecord that are defined in a list of well-known values. - - For log records that are [Log Events](logs/event-api.md) - - The following data provided to [emit event](logs/event-api.md#emit-event): - - The event name (the value of the `event.name` attribute) + - For log records that are Events + - The following data provided to [emit event](logs/api.md#emit-a-logrecord): + - `event.name` attribute Things not listed in the above are not expected to remain stable via semantic convention and are allowed (or expected) to change. A few examples: From ffe4a1b384cd922332850b6548a01e44c4657e2d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 25 Sep 2024 10:37:04 +0200 Subject: [PATCH 02/20] Fix lint issues --- specification/logs/README.md | 2 +- specification/logs/api.md | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/logs/README.md b/specification/logs/README.md index f52a7b5de82..54e52db04d6 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -143,7 +143,7 @@ Given the above state of the logging space we took the following approach: - OpenTelemetry defines a Logs API for [emitting LogRecords](./api.md#emit-a-logrecord). It is provided for library authors to build [log appender](../glossary.md#log-appender--bridge), which use the API to bridge between existing logging libraries and the - OpenTelemetry log data model. + OpenTelemetry log data model. The [API](./api.md) is also provided for instrumentation libraries to emit log records following semantic conventions (also known as OpenTelemetry Events). Existing logging libraries generally provide a much richer set of features diff --git a/specification/logs/api.md b/specification/logs/api.md index 411e411d56b..2bcb2c087a0 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -19,7 +19,6 @@ + [Enabled](#enabled) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) -- [Artifact Naming](#artifact-naming) - [References](#references) @@ -43,7 +42,7 @@ OpenTelemetry log data model. It is provided for application developers to emit structured log recors (e.g. custom events). -Languges MAY provide a seperate Logs Bridge API if they need different +Languges MAY provide a separate Logs Bridge API if they need different ergonimics for consumers that are building log appenders/bridges. The Logs API consist of these main components: From 4dadc753b9fa1a49f56f80278fbc5fd6b63ecaae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 25 Sep 2024 10:41:22 +0200 Subject: [PATCH 03/20] Update changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ce635a47357..2e1ce448bad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,6 +29,8 @@ release. ([#4203](https://github.com/open-telemetry/opentelemetry-specification/pull/4203)) - Make all fields as identifying for Logger. Previously attributes were omitted from being identifying. ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) +- Remove Events API and SDK. Rename Logs Bridge API to Logs API and do not discourage direct usage. + ([#4225](https://github.com/open-telemetry/opentelemetry-specification/pull/4225)) ### Events From 90610d2864c1e1bb620aa5c677e045ac1efd35c5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 25 Sep 2024 10:53:32 +0200 Subject: [PATCH 04/20] Fix changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e1ce448bad..14662b5e830 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -29,7 +29,7 @@ release. ([#4203](https://github.com/open-telemetry/opentelemetry-specification/pull/4203)) - Make all fields as identifying for Logger. Previously attributes were omitted from being identifying. ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) -- Remove Events API and SDK. Rename Logs Bridge API to Logs API and do not discourage direct usage. +- Remove Events API and SDK. Rename Logs Bridge API to Logs API and do not discourage from direct usage. ([#4225](https://github.com/open-telemetry/opentelemetry-specification/pull/4225)) ### Events From 452f61b0d71ef9ef1493f8c5ba45286bff8aa11f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 25 Sep 2024 20:16:36 +0200 Subject: [PATCH 05/20] Apply suggestions from code review Co-authored-by: Cijo Thomas --- specification/logs/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index 2bcb2c087a0..ba7d1888847 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -39,11 +39,11 @@ It is provided for logging library authors to build which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. -It is provided for application developers to emit structured log recors +It is provided for application developers to emit structured log records (e.g. custom events). Languges MAY provide a separate Logs Bridge API if they need different -ergonimics for consumers that are building log appenders/bridges. +ergonomics for consumers that are building log appenders/bridges. The Logs API consist of these main components: From 4ab9a0a8ccc18809d3a8404941bdd1df3c147351 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Thu, 26 Sep 2024 06:26:32 +0200 Subject: [PATCH 06/20] Apply suggestions from code review Co-authored-by: Trask Stalnaker Co-authored-by: Reiley Yang --- specification/logs/api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index ba7d1888847..cb4ce149e50 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -27,7 +27,7 @@ ## Overview -This document defines a log *backend* API. +This document defines a log API. The API serves following use cases. @@ -42,10 +42,10 @@ OpenTelemetry log data model. It is provided for application developers to emit structured log records (e.g. custom events). -Languges MAY provide a separate Logs Bridge API if they need different +Languages MAY provide a separate Logs Bridge API if they need different ergonomics for consumers that are building log appenders/bridges. -The Logs API consist of these main components: +The Logs API consists of these main components: * [LoggerProvider](#loggerprovider) is the entry point of the API. It provides access to `Logger`s. * [Logger](#logger) is responsible for emitting logs as From daaaa1fb8662cd5c02b23f17461042c6dadde52d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 27 Sep 2024 06:34:05 +0200 Subject: [PATCH 07/20] Apply suggestions from code review Co-authored-by: Trask Stalnaker --- specification/logs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/README.md b/specification/logs/README.md index 54e52db04d6..ffaee6d0329 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -141,7 +141,7 @@ Given the above state of the logging space we took the following approach: translate them to OpenTelemetry log data model. - OpenTelemetry defines a Logs API for [emitting LogRecords](./api.md#emit-a-logrecord). - It is provided for library authors to build [log appender](../glossary.md#log-appender--bridge), + It is provided for library authors to build [log appenders](../glossary.md#log-appender--bridge), which use the API to bridge between existing logging libraries and the OpenTelemetry log data model. The [API](./api.md) is also provided for instrumentation libraries to emit log From 847b6916fe12053731c85958ae00bd5f212d25c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Fri, 27 Sep 2024 18:29:28 +0200 Subject: [PATCH 08/20] Update specification/logs/api.md Co-authored-by: Trask Stalnaker --- specification/logs/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index cb4ce149e50..4a8664e23a0 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -40,7 +40,7 @@ which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. It is provided for application developers to emit structured log records -(e.g. custom events). +(including OpenTelemetry Events). Languages MAY provide a separate Logs Bridge API if they need different ergonomics for consumers that are building log appenders/bridges. From 1409d01028aebe053bd62ee5ca5d97c5e2392034 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 30 Sep 2024 11:39:17 +0200 Subject: [PATCH 09/20] Bring back Events API and SDK --- specification/logs/event-api.md | 162 ++++++++++++++++++++++++++++++++ specification/logs/event-sdk.md | 110 ++++++++++++++++++++++ specification/logs/sdk.md | 2 +- 3 files changed, 273 insertions(+), 1 deletion(-) create mode 100644 specification/logs/event-api.md create mode 100644 specification/logs/event-sdk.md diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md new file mode 100644 index 00000000000..ea5c58116fe --- /dev/null +++ b/specification/logs/event-api.md @@ -0,0 +1,162 @@ +# Events API + +**Status**: [Development](../document-status.md) + +
+Table of Contents + + + + + +- [Event Data model](#event-data-model) +- [Event API use cases](#event-api-use-cases) +- [EventLoggerProvider](#eventloggerprovider) + * [EventLoggerProvider operations](#eventloggerprovider-operations) + + [Get an EventLogger](#get-an-eventlogger) +- [EventLogger](#eventlogger) + * [EventLogger Operations](#eventlogger-operations) + + [Emit Event](#emit-event) +- [Optional and required parameters](#optional-and-required-parameters) +- [References](#references) + + + +
+ +The Event API consists of these main components: + +* [EventLoggerProvider](#eventloggerprovider) is the entry point of the API. It + provides access to `EventLogger`s. +* [EventLogger](#eventlogger) is the component responsible for emitting events. + +## Event Data model + +Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/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](./data-model.md). 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 +[`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md), +and all Events with the same `event.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](./bridge-api.md), 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](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). + +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 + +`EventLogger`s 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`: Specifies the name of the [instrumentation scope](../glossary.md#instrumentation-scope), + such as the [instrumentation library](../glossary.md#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](../glossary.md#instrumented-library) and + [Instrumentation library](../glossary.md#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. + +The term *identical* applied to `EventLogger`s describes instances where all +parameters are equal. The term *distinct* applied to `EventLogger`s describes +instances where at least one parameter has a different value. + +## 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: + +#### 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](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). +* The (`AnyValue`) (optional) `Body` of the Event. +* The `Timestamp` (optional) of the Event. +* The [Context](../context/README.md) (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 + +- [OTEP0202 Introducing Events and Logs API](https://github.com/open-telemetry/oteps/blob/main/text/0202-events-and-logs-api.md) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md new file mode 100644 index 00000000000..1a9bc0ee829 --- /dev/null +++ b/specification/logs/event-sdk.md @@ -0,0 +1,110 @@ +# Events SDK + +**Status**: [Development](../document-status.md) + +
+Table of Contents + + + + + +- [Overview](#overview) +- [EventLoggerProvider](#eventloggerprovider) + * [EventLoggerProvider Creation](#eventloggerprovider-creation) + * [EventLogger Creation](#eventlogger-creation) + * [Configuration](#configuration) + * [ForceFlush](#forceflush) +- [EventLogger](#eventlogger) + * [Emit Event](#emit-event) + + + +
+ +Users of OpenTelemetry need a way for instrumentation interactions with the +OpenTelemetry API to actually produce telemetry. The OpenTelemetry SDK +(henceforth referred to as the SDK) is an implementation of the OpenTelemetry +API that provides users with this functionally. + +All implementations of the OpenTelemetry API MUST provide an SDK. + +## Overview + +From OpenTelemetry's perspective LogRecords and Events are both represented +using the same [data model](./event-api.md#event-data-model). Therefore, the default +implementation of an Event SDK MUST generate events using the [Logs Data Model](./data-model.md). + +The SDK MUST use the [Logs SDK](./sdk.md) to generate, process and export `LogRecord`s. + +## EventLoggerProvider + +The `EventLoggerProvider` MUST be implemented as a proxy to an instance of [`LoggerProvider`](./sdk.md#loggerprovider). + +All `LogRecord`s produced by any `EventLogger` from the `EventLoggerProvider` SHOULD be associated with the `Resource` from the provided `LoggerProvider`. + +### EventLoggerProvider Creation + +The SDK SHOULD allow the creation of multiple independent `EventLoggerProvider`s. + +### EventLogger Creation + +It SHOULD only be possible to create `EventLogger` instances through an `EventLoggerProvider` +(see [Events API](event-api.md)). + +The `EventLoggerProvider` MUST implement the [Get an EventLogger API](event-api.md#get-an-eventlogger). + +In the case where an invalid `name` (null or empty string) is specified, a +working `EventLogger` MUST be returned as a fallback rather than returning null or +throwing an exception. Its `name` SHOULD keep the original invalid value, and a +message reporting that the specified value is invalid SHOULD be logged. + +### Configuration + +The `EventLoggerProvider` MUST accept an instance of `LoggerProvider`. Any configuration +related to processing MUST be done by configuring the `LoggerProvider` directly. + +### ForceFlush + +This method provides a way for the provider to notify the delegate `LoggerProvider` +to force all registered [LogRecordProcessors](sdk.md#logrecordprocessor) to immediately export all +`LogRecords` that have not yet been exported. + +## EventLogger + +The `EventLogger` MUST be implemented as a proxy to an instance of [`Logger`](./sdk.md#logger). + +### Emit Event + +Emit a `LogRecord` representing an `Event`. + +**Implementation Requirements:** + +The implementation MUST use the parameters +to [emit a logRecord](./bridge-api.md#emit-a-logrecord) as follows: + +* The `Name` MUST be used to set + the `event.name` [Attribute](./data-model.md#field-attributes). If + the `Attributes` provided by the user contain an `event.name` attribute the + value provided in the `Name` takes precedence. +* If provided by the user, the `Body` MUST be used to set + the [Body](./data-model.md#field-body). If not provided, `Body` MUST not be + set. +* If provided by the user, the `Timestamp` MUST be used to set + the [Timestamp](./data-model.md#field-timestamp). If not provided, `Timestamp` + MUST be set to the current time when [emit](#emit-event) was called. +* The [Observed Timestamp](./data-model.md#field-observedtimestamp) MUST not be + set. (NOTE: [emit a logRecord](./bridge-api.md#emit-a-logrecord) will + set `ObservedTimestamp` to the current time when unset.) +* If provided by the user, the `Context` MUST be used to set + the [Context](./bridge-api.md#emit-a-logrecord). If not provided, `Context` + MUST be set to the current Context. +* If provided by the user, the `SeverityNumber` MUST be used to set + the [Severity Number](./data-model.md#field-severitynumber) when emitting the + logRecord. If not provided, `SeverityNumber` MUST be set + to `SEVERITY_NUMBER_INFO=9`. +* The [Severity Text](./data-model.md#field-severitytext) MUST not be set. +* If provided by the user, the `Attributes` MUST be used to set + the [Attributes](./data-model.md#field-attributes). The user + provided `Attributes` MUST not take over the `event.name` + attribute previously discussed. diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 7fcc1d34b40..eed971bbbd1 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -40,7 +40,7 @@
Users of OpenTelemetry need a way for instrumentation interactions with the -OpenTelemetry API to actually produce telemetry. The OpenTelemetry Logging SDK +[OpenTelemetry API](api.md) to actually produce telemetry. The OpenTelemetry Logging SDK (henceforth referred to as the SDK) is an implementation of the OpenTelemetry API that provides users with this functionally. From bbc8ab1fc427960df5250178be79b997035471ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 30 Sep 2024 11:40:29 +0200 Subject: [PATCH 10/20] Revert spec complaince matrix --- spec-compliance-matrix.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 54e9fe80ee8..790875d9e32 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -203,6 +203,26 @@ Disclaimer: this list of features is still a work in progress, please refer to t | Can plug custom LogRecordExporter | | | + | | + | | | + | | + | | | | Trace Context Injection | | | + | | + | | | + | | + | + | | +## Events + +Features for the [Events API](specification/logs/event-api.md) and the [Events SDK](specification/logs/event-sdk.md). +Disclaimer: Events are currently in Development status - work in progress. + +| Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | +|----------------------------------------------------------------------------|----------|----|------|----|--------|------|--------|-----|------|-----|------|-------| +| [EventLoggerProvider](specification/logs/event-api.md#eventloggerprovider) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | +| Get EventLogger | | | | | | | | | | | | | +| Get EventLogger accepts version | X | | | | | | | | | | | | +| Get EventLogger accepts schema_url | X | | | | | | | | | | | | +| Get EventLogger accepts attributes | X | | | | | | | | | | | | +| [EventLogger](specification/logs/event-api.md#eventlogger) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | +| Emit event accepts name | | | | | | | | | | | | | +| Emit event accepts AnyValue body | X | | | | | | | | | | | | +| Emit event accepts severity | X | | | | | | | | | | | | +| Emit event accepts timestamp | X | | | | | | | | | | | | +| Emit event accepts attributes | X | | | | | | | | | | | | +| Emit event accepts context | X | | | | | | | | | | | | + ## Resource | Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | From 3b32a2d1e1bf823d4249284b83bde7a2cdb026c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 30 Sep 2024 12:04:36 +0200 Subject: [PATCH 11/20] Events API and Logs API side by side --- specification/logs/api.md | 24 +++++++++++++++------- specification/logs/data-model.md | 23 +++++++++++++++++++++ specification/logs/event-api.md | 35 +++++++------------------------- 3 files changed, 47 insertions(+), 35 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index 4a8664e23a0..14b399e5fd6 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -19,6 +19,8 @@ + [Enabled](#enabled) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) +- [Convenience](#convenience) +- [Logs Bridge API](#logs-bridge-api) - [References](#references) @@ -31,20 +33,17 @@ This document defines a log API. The API serves following use cases. -It is provided for instrumentation libraries to emit events (log records following -OpenTelemetry Semantic Conventions). - It is provided for logging library authors to build [log appenders/bridges](./supplementary-guidelines.md#how-to-create-a-log4j-log-appender), which use this API to bridge between existing logging libraries and the -OpenTelemetry log data model. +OpenTelemetry log data model. See also: [Logs Bridge API](#logs-bridge-api) + +It is provided for (instrumentation) libraries to emit +[OpenTelemetry Events](data-model.md#events). It is provided for application developers to emit structured log records (including OpenTelemetry Events). -Languages MAY provide a separate Logs Bridge API if they need different -ergonomics for consumers that are building log appenders/bridges. - The Logs API consists of these main components: * [LoggerProvider](#loggerprovider) is the entry point of the API. It provides access to `Logger`s. @@ -187,6 +186,17 @@ specific guarantees and safeties. **Logger** - all methods are safe to be called concurrently. +## Convenience + +Languages MAY provide additional ergonomics and convinence APIs. For instance, +a language may provide an `Emit an Event` method that requires passing +an event name parameter. + +## Logs Bridge API + +Languages MAY provide a separate Logs Bridge API if they need different +ergonomics for consumers that are building log appenders/bridges. + ## References - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index d0281c70533..31798acf59d 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -33,6 +33,7 @@ * [Field: `InstrumentationScope`](#field-instrumentationscope) * [Field: `Attributes`](#field-attributes) + [Errors and Exceptions](#errors-and-exceptions) + * [Events](#events) - [Example Log Records](#example-log-records) - [Example Mappings](#example-mappings) - [References](#references) @@ -466,6 +467,28 @@ of the record. If included, they MUST follow the OpenTelemetry [semantic conventions for exception-related attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-logs.md). +### Events + +Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/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](./data-model.md). 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 +[`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md), +and all Events with the same `event.name` MUST conform to the same schema for +both their `Attributes` and their `Body`. + ## Example Log Records For example log records see diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index ea5c58116fe..3688c94a78f 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,7 +9,6 @@ -- [Event Data model](#event-data-model) - [Event API use cases](#event-api-use-cases) - [EventLoggerProvider](#eventloggerprovider) * [EventLoggerProvider operations](#eventloggerprovider-operations) @@ -30,35 +29,13 @@ The Event API consists of these main components: provides access to `EventLogger`s. * [EventLogger](#eventlogger) is the component responsible for emitting events. -## Event Data model - -Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/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](./data-model.md). 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 -[`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md), -and all Events with the same `event.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](./bridge-api.md), 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: +The Events API was designed to allow shared libraries to emit +[events](data-model.md#events) without needing to depend on a third party logger. +Instrumentation authors and application developers are encouraged can 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 @@ -80,6 +57,8 @@ 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. +Emitting events via [Logs API](api.md) is also acceptable. + ## EventLoggerProvider `EventLogger`s can be accessed with a `EventLoggerProvider`. From 71c0986880cc11d71c5cf66ab7976feda84109da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 30 Sep 2024 12:05:42 +0200 Subject: [PATCH 12/20] Update changelog --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5ae0538a959..698dfcbeef7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,7 +31,7 @@ release. ([#4203](https://github.com/open-telemetry/opentelemetry-specification/pull/4203)) - Make all fields as identifying for Logger. Previously attributes were omitted from being identifying. ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) -- Remove Events API and SDK. Rename Logs Bridge API to Logs API and do not discourage from direct usage. +- Make Logs Bridge API as the Logs API and do not discourage from direct usage. ([#4225](https://github.com/open-telemetry/opentelemetry-specification/pull/4225)) ### Events From 22d628d91dfcbffe73684475a54e24bfc456b493 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 30 Sep 2024 12:20:18 +0200 Subject: [PATCH 13/20] Fix hyperlink --- specification/logs/event-sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 1a9bc0ee829..91526119abe 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -81,7 +81,7 @@ Emit a `LogRecord` representing an `Event`. **Implementation Requirements:** The implementation MUST use the parameters -to [emit a logRecord](./bridge-api.md#emit-a-logrecord) as follows: +to [emit a logRecord](./api.md#emit-a-logrecord) as follows: * The `Name` MUST be used to set the `event.name` [Attribute](./data-model.md#field-attributes). If From de72b99afdf43df5e9f792e1a75ee9856c049436 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 30 Sep 2024 12:27:34 +0200 Subject: [PATCH 14/20] Fix links --- specification/logs/event-sdk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 91526119abe..9017fccee17 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -94,10 +94,10 @@ to [emit a logRecord](./api.md#emit-a-logrecord) as follows: the [Timestamp](./data-model.md#field-timestamp). If not provided, `Timestamp` MUST be set to the current time when [emit](#emit-event) was called. * The [Observed Timestamp](./data-model.md#field-observedtimestamp) MUST not be - set. (NOTE: [emit a logRecord](./bridge-api.md#emit-a-logrecord) will + set. (NOTE: [emit a logRecord](./api.md#emit-a-logrecord) will set `ObservedTimestamp` to the current time when unset.) * If provided by the user, the `Context` MUST be used to set - the [Context](./bridge-api.md#emit-a-logrecord). If not provided, `Context` + the [Context](./api.md#emit-a-logrecord). If not provided, `Context` MUST be set to the current Context. * If provided by the user, the `SeverityNumber` MUST be used to set the [Severity Number](./data-model.md#field-severitynumber) when emitting the From beff5c5d2f827aeec6aa989ee2dc34321bc91d80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 30 Sep 2024 12:30:26 +0200 Subject: [PATCH 15/20] Update README.md --- specification/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/README.md b/specification/README.md index 39100606db2..22332a7f741 100644 --- a/specification/README.md +++ b/specification/README.md @@ -29,10 +29,12 @@ path_base_for_github_subdir: - [Tracing](trace/api.md) - [Metrics](metrics/api.md) - [Logs](logs/api.md) + - [Events](logs/event-api.md) - SDK Specification - [Tracing](trace/sdk.md) - [Metrics](metrics/sdk.md) - [Logs](logs/sdk.md) + - [Events](logs/event-sdk.md) - [Resource](resource/sdk.md) - [Configuration](configuration/README.md) - Data Specification From 6e2511db0a483b61e73812299023d3d247070d4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 30 Sep 2024 12:33:15 +0200 Subject: [PATCH 16/20] Remove a badly formulated statement --- specification/logs/event-sdk.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 9017fccee17..df888bb358d 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -27,8 +27,6 @@ OpenTelemetry API to actually produce telemetry. The OpenTelemetry SDK (henceforth referred to as the SDK) is an implementation of the OpenTelemetry API that provides users with this functionally. -All implementations of the OpenTelemetry API MUST provide an SDK. - ## Overview From OpenTelemetry's perspective LogRecords and Events are both represented From ba78baa4e061c728f36ee51cd8b73297a515167e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 30 Sep 2024 12:37:33 +0200 Subject: [PATCH 17/20] Refine versioning and stability --- specification/versioning-and-stability.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 00942544e4c..bb200265f22 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -234,9 +234,8 @@ Semantic Conventions defines the set of fields in the OTLP data model: - The attribute keys provided on the LogRecord - The attribute values provided on the LogRecord that are defined in a list of well-known values. - - For log records that are Events - - The following data provided to [emit event](logs/api.md#emit-a-logrecord): - - `event.name` attribute + - For log records that are [Events](logs/data-model.md#events): + - `event.name` attribute value Things not listed in the above are not expected to remain stable via semantic convention and are allowed (or expected) to change. A few examples: From d3aefef7b4f62448e4d4302fdba9833691afa484 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 30 Sep 2024 20:57:46 +0200 Subject: [PATCH 18/20] Update api.md --- specification/logs/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index 14b399e5fd6..748ed15ca6b 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -38,7 +38,7 @@ It is provided for logging library authors to build which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. See also: [Logs Bridge API](#logs-bridge-api) -It is provided for (instrumentation) libraries to emit +It is provided for OpenTelemetry (instrumentation) libraries to emit [OpenTelemetry Events](data-model.md#events). It is provided for application developers to emit structured log records From cc0f26289786620e9708a15f7534347c777cb9b9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 30 Sep 2024 21:52:05 +0200 Subject: [PATCH 19/20] Update api.md --- specification/logs/api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index 748ed15ca6b..94db2ad7202 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -189,8 +189,8 @@ specific guarantees and safeties. ## Convenience Languages MAY provide additional ergonomics and convinence APIs. For instance, -a language may provide an `Emit an Event` method that requires passing -an event name parameter. +a language may provide an `Info` method for `Logger` which emits a log record +with `SeverityNumber` equal to `9`. ## Logs Bridge API From d286fc2eac5dd84d159a9678a9f4d15498e751fb Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Mon, 30 Sep 2024 15:40:31 -0700 Subject: [PATCH 20/20] Update specification/logs/event-api.md Co-authored-by: Trask Stalnaker --- specification/logs/event-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 3688c94a78f..c76ffea76ff 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -33,7 +33,7 @@ The Event API consists of these main components: The Events API was designed to allow shared libraries to emit [events](data-model.md#events) without needing to depend on a third party logger. -Instrumentation authors and application developers are encouraged can call this +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: