From 44495a6e743cdf2abb4d7e97d4fc1b329ac18685 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Mon, 14 Oct 2024 20:21:25 -0700 Subject: [PATCH 01/28] add EmitEvent to Log API --- specification/logs/bridge-api.md | 46 +++++++++++++++++++++++--------- 1 file changed, 34 insertions(+), 12 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index e889933e3c0..488d659f2f5 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -9,18 +9,20 @@ -- [LoggerProvider](#loggerprovider) - * [LoggerProvider operations](#loggerprovider-operations) - + [Get a Logger](#get-a-logger) -- [Logger](#logger) - * [Logger operations](#logger-operations) - + [Emit a LogRecord](#emit-a-logrecord) - + [Enabled](#enabled) -- [Logs API](#logs-api) -- [Optional and required parameters](#optional-and-required-parameters) -- [Concurrency requirements](#concurrency-requirements) -- [Artifact Naming](#artifact-naming) -- [References](#references) +- [Logs Bridge API](#logs-bridge-api) + - [LoggerProvider](#loggerprovider) + - [LoggerProvider operations](#loggerprovider-operations) + - [Get a Logger](#get-a-logger) + - [Logger](#logger) + - [Logger operations](#logger-operations) + - [Emit a LogRecord](#emit-a-logrecord) + - [Enabled](#enabled) + - [Logs API](#logs-api) + - [Emit Event](#emit-event) + - [Optional and required parameters](#optional-and-required-parameters) + - [Concurrency requirements](#concurrency-requirements) + - [Artifact Naming](#artifact-naming) + - [References](#references) @@ -153,6 +155,26 @@ up-to-date response. This set of API functions will provide the capabilities needed to emit a `LogRecord` as is currently provided by [Events API](./event-api.md). +#### Emit Event + +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 +native instrumentation emit logs, those logs SHOULD be formatted as Events. +All semantic conventions defined for logs MUST be formatted as Events. + +**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 From 9c6013cc59d156062591ce55e6ecfa58d8919cb0 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 15 Oct 2024 08:23:19 -0700 Subject: [PATCH 02/28] remove log instrumentation header --- specification/logs/bridge-api.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 488d659f2f5..cee66311932 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -18,7 +18,6 @@ - [Emit a LogRecord](#emit-a-logrecord) - [Enabled](#enabled) - [Logs API](#logs-api) - - [Emit Event](#emit-event) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [Artifact Naming](#artifact-naming) @@ -152,11 +151,6 @@ up-to-date response. **Status**: [Development](../document-status.md) -This set of API functions will provide the capabilities needed to emit a -`LogRecord` as is currently provided by [Events API](./event-api.md). - -#### Emit Event - 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 From 4fe576bd2e1e557ae5899fdb554662d4709293a0 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Wed, 16 Oct 2024 10:46:15 -0700 Subject: [PATCH 03/28] remove "native" --- specification/logs/bridge-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index cee66311932..005c22dc361 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -154,7 +154,7 @@ up-to-date response. 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 -native instrumentation emit logs, those logs SHOULD be formatted as Events. +instrumentation emits logs, those logs SHOULD be formatted as Events. All semantic conventions defined for logs MUST be formatted as Events. **Parameters:** From 0622e06917302a79e54c84f54a7b2cbb2c6045d2 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Wed, 16 Oct 2024 11:14:23 -0700 Subject: [PATCH 04/28] organize operations --- specification/logs/bridge-api.md | 46 +++++++++++++++++++++++++++++--- 1 file changed, 42 insertions(+), 4 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 005c22dc361..8bf22789aec 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -14,8 +14,11 @@ - [LoggerProvider operations](#loggerprovider-operations) - [Get a Logger](#get-a-logger) - [Logger](#logger) - - [Logger operations](#logger-operations) + - [Log Bridge operations](#log-bridge-operations) - [Emit a LogRecord](#emit-a-logrecord) + - [Log Instrumentation operations](#log-instrumentation-operations) + - [Emit an Event](#emit-an-event) + - [Helper operations](#helper-operations) - [Enabled](#enabled) - [Logs API](#logs-api) - [Optional and required parameters](#optional-and-required-parameters) @@ -93,18 +96,27 @@ instances where at least one parameter has a different value. ## Logger -The `Logger` is responsible for emitting `LogRecord`s. +The `Logger` is responsible for emitting `LogRecord`s. There are two types of +logging operations: -### Logger 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. +* **helper** operations to assist with using the logger. -The `Logger` MUST provide functions to: +The Logger contains methods for both types of operations. The `Logger` MUST +provide functions to: - [Emit a `LogRecord`](#emit-a-logrecord) +- [Emit an `Event`](#emit-an-event) The `Logger` SHOULD provide functions to: - [Report if `Logger` is `Enabled`](#enabled) +### Log Bridge operations + #### Emit a LogRecord The effect of calling this API is to emit a `LogRecord` to the processing pipeline. @@ -123,6 +135,32 @@ The API MUST accept the following parameters: - [Body](./data-model.md#field-body) (optional) - [Attributes](./data-model.md#field-attributes) (optional) +### Log Instrumentation operations + +#### Emit an Event + +**Status**: [Development](../document-status.md) + +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. + +**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`. + +### Helper operations + #### Enabled **Status**: [Development](../document-status.md) From 6b264ca9521f03ff983563ec9ef71459e5afab7c Mon Sep 17 00:00:00 2001 From: Ted Young Date: Wed, 16 Oct 2024 11:19:09 -0700 Subject: [PATCH 05/28] update links --- specification/logs/event-api.md | 23 ++++++++++++----------- specification/logs/event-sdk.md | 19 ++++++++++--------- 2 files changed, 22 insertions(+), 20 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index e84861ec024..1e95a2727e2 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,17 +9,18 @@ -- [Logs API Development](#logs-api-development) -- [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) +- [Events API](#events-api) + - [Logs API Development](#logs-api-development) + - [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) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 28bd88cee14..349ed619822 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,15 +9,16 @@ -- [Logs API Development](#logs-api-development) -- [Overview](#overview) -- [EventLoggerProvider](#eventloggerprovider) - * [EventLoggerProvider Creation](#eventloggerprovider-creation) - * [EventLogger Creation](#eventlogger-creation) - * [Configuration](#configuration) - * [ForceFlush](#forceflush) -- [EventLogger](#eventlogger) - * [Emit Event](#emit-event) +- [Events SDK](#events-sdk) + - [Logs API Development](#logs-api-development) + - [Overview](#overview) + - [EventLoggerProvider](#eventloggerprovider) + - [EventLoggerProvider Creation](#eventloggerprovider-creation) + - [EventLogger Creation](#eventlogger-creation) + - [Configuration](#configuration) + - [ForceFlush](#forceflush) + - [EventLogger](#eventlogger) + - [Emit Event](#emit-event) From 83b0ba260ed71468ca588ec5667cef771b086586 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Wed, 16 Oct 2024 11:43:25 -0700 Subject: [PATCH 06/28] clean up event api parameters --- specification/logs/bridge-api.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 8bf22789aec..b21ec4d8c99 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -149,15 +149,19 @@ All semantic conventions defined for logs MUST be formatted as Events. **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`. +* The [`Name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md) + of the Event. +* [Observed Timestamp](./data-model.md#field-observedtimestamp) (optional). If unspecified + the implementation SHOULD set it equal to the current time. +* The [Context](../context/README.md) 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](./data-model.md#field-severitynumber) (optional) +* [Severity Text](./data-model.md#field-severitytext) (optional) +* [Body](./data-model.md#field-body) (optional) +* [Attributes](./data-model.md#field-attributes) (optional) Event `Attributes` conform + to the [standard definition](../common/README.md#standard-attribute) of an attribute. ### Helper operations From 78da4101e7e25f66f6870103a09d534787023a21 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 07:40:34 -0700 Subject: [PATCH 07/28] EmitEvent should be recommended not required --- specification/logs/bridge-api.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index b21ec4d8c99..0f3714b951c 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -96,22 +96,25 @@ instances where at least one parameter has a different value. ## Logger -The `Logger` is responsible for emitting `LogRecord`s. There are two types of +The `Logger` is responsible for emitting `LogRecord`s. There are three 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. -* **helper** operations to assist with using the logger. +* **Helper** operations to assist with using the logger. -The Logger contains methods for both types of operations. The `Logger` MUST -provide functions to: +The Logger contains methods for all types of operations. The `Logger` MUST +provide a function to: - [Emit a `LogRecord`](#emit-a-logrecord) + +The `Logger` is RECOMMENDED to provide a function to: + - [Emit an `Event`](#emit-an-event) -The `Logger` SHOULD provide functions to: +The `Logger` SHOULD provide a function to: - [Report if `Logger` is `Enabled`](#enabled) From 6c13678f981cd25ab057188f91465c41b3dbe538 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 07:46:27 -0700 Subject: [PATCH 08/28] Move and rename Bridge API to API --- specification/README.md | 2 +- specification/glossary.md | 4 +- specification/logs/README.md | 10 +-- specification/logs/{bridge-api.md => api.md} | 16 ++--- specification/logs/event-api.md | 2 +- specification/logs/event-sdk.md | 6 +- specification/logs/noop.md | 10 +-- specification/logs/sdk.md | 67 ++++++++++--------- .../logs/supplementary-guidelines.md | 16 ++--- 9 files changed, 67 insertions(+), 66 deletions(-) rename specification/logs/{bridge-api.md => api.md} (96%) diff --git a/specification/README.md b/specification/README.md index d1136d70243..10bd98074a8 100644 --- a/specification/README.md +++ b/specification/README.md @@ -29,7 +29,7 @@ path_base_for_github_subdir: - [Tracing](trace/api.md) - [Metrics](metrics/api.md) - [Logs](logs/README.md) - - [Bridge API](logs/bridge-api.md) + - [API](logs/api.md) - [Event API](logs/event-api.md) - SDK Specification - [Tracing](trace/sdk.md) diff --git a/specification/glossary.md b/specification/glossary.md index c1a67d8187a..3a59616470c 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -196,7 +196,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 @@ -254,7 +254,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 [Log 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..ecf0e84d0cd 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -140,8 +140,8 @@ 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 +- OpenTelemetry defines a Logs API + for [emitting LogRecords](./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 @@ -149,7 +149,7 @@ Given the above state of the logging space we took the following approach: 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 an [SDK](./sdk.md) implementation of the [API](./api.md), which enables configuration of [processing](./sdk.md#logrecordprocessor) and [exporting](./sdk.md#logrecordexporter) LogRecords. @@ -359,7 +359,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,7 +444,7 @@ 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) diff --git a/specification/logs/bridge-api.md b/specification/logs/api.md similarity index 96% rename from specification/logs/bridge-api.md rename to specification/logs/api.md index 0f3714b951c..fa59aa8a459 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,7 +9,7 @@ -- [Logs Bridge API](#logs-bridge-api) +- [Logs API](#logs-api) - [LoggerProvider](#loggerprovider) - [LoggerProvider operations](#loggerprovider-operations) - [Get a Logger](#get-a-logger) @@ -20,7 +20,7 @@ - [Emit an Event](#emit-an-event) - [Helper operations](#helper-operations) - [Enabled](#enabled) - - [Logs API](#logs-api) + - [Logs API](#logs-api-1) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [Artifact Naming](#artifact-naming) @@ -37,7 +37,7 @@ library authors to build which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. -The Logs Bridge API consist of these main components: +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 @@ -227,7 +227,7 @@ 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. @@ -236,10 +236,10 @@ specific guarantees and safeties. ## Artifact Naming -The Logs Bridge API is not intended to be called by application developers +The Logs 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 +in the event OpenTelemetry were to add a user facing API, the Logs API would +be a natural starting point. Therefore, Log 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. diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 1e95a2727e2..ccb71c0a46d 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -67,7 +67,7 @@ both their `Attributes` and their `Body`. 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 +[Logs API](./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: diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 349ed619822..d96f509411d 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -92,7 +92,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 @@ -105,10 +105,10 @@ to [emit a logRecord](./bridge-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 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 d8228b174fa..967544d7328 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,34 +7,35 @@ -- [LoggerProvider](#loggerprovider) - * [LoggerProvider Creation](#loggerprovider-creation) - * [Logger Creation](#logger-creation) - * [Configuration](#configuration) - + [LoggerConfigurator](#loggerconfigurator) - * [Shutdown](#shutdown) - * [ForceFlush](#forceflush) -- [Logger](#logger) - * [LoggerConfig](#loggerconfig) -- [Additional LogRecord interfaces](#additional-logrecord-interfaces) - * [ReadableLogRecord](#readablelogrecord) - * [ReadWriteLogRecord](#readwritelogrecord) -- [LogRecord Limits](#logrecord-limits) -- [LogRecordProcessor](#logrecordprocessor) - * [LogRecordProcessor operations](#logrecordprocessor-operations) - + [OnEmit](#onemit) - + [ShutDown](#shutdown) - + [ForceFlush](#forceflush-1) - * [Built-in processors](#built-in-processors) - + [Simple processor](#simple-processor) - + [Batching processor](#batching-processor) - + [Isolating processor](#isolating-processor) -- [LogRecordExporter](#logrecordexporter) - * [LogRecordExporter operations](#logrecordexporter-operations) - + [Export](#export) - + [ForceFlush](#forceflush-2) - + [Shutdown](#shutdown-1) -- [Logs API](#logs-api) +- [Logs SDK](#logs-sdk) + - [LoggerProvider](#loggerprovider) + - [LoggerProvider Creation](#loggerprovider-creation) + - [Logger Creation](#logger-creation) + - [Configuration](#configuration) + - [LoggerConfigurator](#loggerconfigurator) + - [Shutdown](#shutdown) + - [ForceFlush](#forceflush) + - [Logger](#logger) + - [LoggerConfig](#loggerconfig) + - [Additional LogRecord interfaces](#additional-logrecord-interfaces) + - [ReadableLogRecord](#readablelogrecord) + - [ReadWriteLogRecord](#readwritelogrecord) + - [LogRecord Limits](#logrecord-limits) + - [LogRecordProcessor](#logrecordprocessor) + - [LogRecordProcessor operations](#logrecordprocessor-operations) + - [OnEmit](#onemit) + - [ShutDown](#shutdown-1) + - [ForceFlush](#forceflush-1) + - [Built-in processors](#built-in-processors) + - [Simple processor](#simple-processor) + - [Batching processor](#batching-processor) + - [Isolating processor](#isolating-processor) + - [LogRecordExporter](#logrecordexporter) + - [LogRecordExporter operations](#logrecordexporter-operations) + - [Export](#export) + - [ForceFlush](#forceflush-2) + - [Shutdown](#shutdown-2) + - [Logs API](#logs-api) @@ -60,9 +61,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 @@ -187,7 +188,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, @@ -208,7 +209,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 @@ -312,7 +313,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, From c9e849bf25f39b3afae085814d4f279d847d1f13 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 08:03:48 -0700 Subject: [PATCH 09/28] Changelog entry --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index ba4d9e6a111..0a974eb8d6d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -66,6 +66,7 @@ release. - Introduce initial placeholder for the new user-facing Logs API, adding references to existing API's informing of the coming changes while the definition is defined. ([#4236](https://github.com/open-telemetry/opentelemetry-specification/pull/4236)) +- Moved the EventProvider and EventLogger into to the LogProvider and Logger.([#4259](https://github.com/open-telemetry/opentelemetry-specification/pull/4259)) ### Common From 266511a3ccd2f4353a26093750685a5a4de043b9 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 08:29:44 -0700 Subject: [PATCH 10/28] TOC --- specification/logs/api.md | 29 ++++++++--------- specification/logs/event-api.md | 23 +++++++------ specification/logs/event-sdk.md | 19 ++++++----- specification/logs/sdk.md | 57 ++++++++++++++++----------------- 4 files changed, 62 insertions(+), 66 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index fa59aa8a459..31581b50beb 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -9,22 +9,21 @@ +- [LoggerProvider](#loggerprovider) + * [LoggerProvider operations](#loggerprovider-operations) + + [Get a Logger](#get-a-logger) +- [Logger](#logger) + * [Log Bridge operations](#log-bridge-operations) + + [Emit a LogRecord](#emit-a-logrecord) + * [Log Instrumentation operations](#log-instrumentation-operations) + + [Emit an Event](#emit-an-event) + * [Helper operations](#helper-operations) + + [Enabled](#enabled) - [Logs API](#logs-api) - - [LoggerProvider](#loggerprovider) - - [LoggerProvider operations](#loggerprovider-operations) - - [Get a Logger](#get-a-logger) - - [Logger](#logger) - - [Log Bridge operations](#log-bridge-operations) - - [Emit a LogRecord](#emit-a-logrecord) - - [Log Instrumentation operations](#log-instrumentation-operations) - - [Emit an Event](#emit-an-event) - - [Helper operations](#helper-operations) - - [Enabled](#enabled) - - [Logs API](#logs-api-1) - - [Optional and required parameters](#optional-and-required-parameters) - - [Concurrency requirements](#concurrency-requirements) - - [Artifact Naming](#artifact-naming) - - [References](#references) +- [Optional and required parameters](#optional-and-required-parameters) +- [Concurrency requirements](#concurrency-requirements) +- [Artifact Naming](#artifact-naming) +- [References](#references) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index ccb71c0a46d..603993493df 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,18 +9,17 @@ -- [Events API](#events-api) - - [Logs API Development](#logs-api-development) - - [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) +- [Logs API Development](#logs-api-development) +- [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) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index d96f509411d..e7bd857f23e 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,16 +9,15 @@ -- [Events SDK](#events-sdk) - - [Logs API Development](#logs-api-development) - - [Overview](#overview) - - [EventLoggerProvider](#eventloggerprovider) - - [EventLoggerProvider Creation](#eventloggerprovider-creation) - - [EventLogger Creation](#eventlogger-creation) - - [Configuration](#configuration) - - [ForceFlush](#forceflush) - - [EventLogger](#eventlogger) - - [Emit Event](#emit-event) +- [Logs API Development](#logs-api-development) +- [Overview](#overview) +- [EventLoggerProvider](#eventloggerprovider) + * [EventLoggerProvider Creation](#eventloggerprovider-creation) + * [EventLogger Creation](#eventlogger-creation) + * [Configuration](#configuration) + * [ForceFlush](#forceflush) +- [EventLogger](#eventlogger) + * [Emit Event](#emit-event) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 967544d7328..cbd169a54d5 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,35 +7,34 @@ -- [Logs SDK](#logs-sdk) - - [LoggerProvider](#loggerprovider) - - [LoggerProvider Creation](#loggerprovider-creation) - - [Logger Creation](#logger-creation) - - [Configuration](#configuration) - - [LoggerConfigurator](#loggerconfigurator) - - [Shutdown](#shutdown) - - [ForceFlush](#forceflush) - - [Logger](#logger) - - [LoggerConfig](#loggerconfig) - - [Additional LogRecord interfaces](#additional-logrecord-interfaces) - - [ReadableLogRecord](#readablelogrecord) - - [ReadWriteLogRecord](#readwritelogrecord) - - [LogRecord Limits](#logrecord-limits) - - [LogRecordProcessor](#logrecordprocessor) - - [LogRecordProcessor operations](#logrecordprocessor-operations) - - [OnEmit](#onemit) - - [ShutDown](#shutdown-1) - - [ForceFlush](#forceflush-1) - - [Built-in processors](#built-in-processors) - - [Simple processor](#simple-processor) - - [Batching processor](#batching-processor) - - [Isolating processor](#isolating-processor) - - [LogRecordExporter](#logrecordexporter) - - [LogRecordExporter operations](#logrecordexporter-operations) - - [Export](#export) - - [ForceFlush](#forceflush-2) - - [Shutdown](#shutdown-2) - - [Logs API](#logs-api) +- [LoggerProvider](#loggerprovider) + * [LoggerProvider Creation](#loggerprovider-creation) + * [Logger Creation](#logger-creation) + * [Configuration](#configuration) + + [LoggerConfigurator](#loggerconfigurator) + * [Shutdown](#shutdown) + * [ForceFlush](#forceflush) +- [Logger](#logger) + * [LoggerConfig](#loggerconfig) +- [Additional LogRecord interfaces](#additional-logrecord-interfaces) + * [ReadableLogRecord](#readablelogrecord) + * [ReadWriteLogRecord](#readwritelogrecord) +- [LogRecord Limits](#logrecord-limits) +- [LogRecordProcessor](#logrecordprocessor) + * [LogRecordProcessor operations](#logrecordprocessor-operations) + + [OnEmit](#onemit) + + [ShutDown](#shutdown) + + [ForceFlush](#forceflush-1) + * [Built-in processors](#built-in-processors) + + [Simple processor](#simple-processor) + + [Batching processor](#batching-processor) + + [Isolating processor](#isolating-processor) +- [LogRecordExporter](#logrecordexporter) + * [LogRecordExporter operations](#logrecordexporter-operations) + + [Export](#export) + + [ForceFlush](#forceflush-2) + + [Shutdown](#shutdown-1) +- [Logs API](#logs-api) From 56377880db566ef3f7bfa3a31d07d37ab27cbdbe Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 12:43:20 -0700 Subject: [PATCH 11/28] reorganize event info --- specification/logs/api.md | 88 +++++++++++++++----------------- specification/logs/data-model.md | 75 ++++++++++++++++----------- 2 files changed, 86 insertions(+), 77 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index 31581b50beb..f0577a9785f 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -9,21 +9,21 @@ -- [LoggerProvider](#loggerprovider) - * [LoggerProvider operations](#loggerprovider-operations) - + [Get a Logger](#get-a-logger) -- [Logger](#logger) - * [Log Bridge operations](#log-bridge-operations) - + [Emit a LogRecord](#emit-a-logrecord) - * [Log Instrumentation operations](#log-instrumentation-operations) - + [Emit an Event](#emit-an-event) - * [Helper operations](#helper-operations) - + [Enabled](#enabled) - [Logs API](#logs-api) -- [Optional and required parameters](#optional-and-required-parameters) -- [Concurrency requirements](#concurrency-requirements) -- [Artifact Naming](#artifact-naming) -- [References](#references) + - [LoggerProvider](#loggerprovider) + - [LoggerProvider operations](#loggerprovider-operations) + - [Get a Logger](#get-a-logger) + - [Logger](#logger) + - [Log Bridge operations](#log-bridge-operations) + - [Emit a LogRecord](#emit-a-logrecord) + - [Enabled](#enabled) + - [Log Instrumentation operations](#log-instrumentation-operations) + - [Emit an Event](#emit-an-event) + - [Logs API](#logs-api-1) + - [Optional and required parameters](#optional-and-required-parameters) + - [Concurrency requirements](#concurrency-requirements) + - [Artifact Naming](#artifact-naming) + - [References](#references) @@ -109,12 +109,9 @@ provide a function to: - [Emit a `LogRecord`](#emit-a-logrecord) -The `Logger` is RECOMMENDED to provide a function to: +The `Logger` SHOULD provide functions to: - [Emit an `Event`](#emit-an-event) - -The `Logger` SHOULD provide a function to: - - [Report if `Logger` is `Enabled`](#enabled) ### Log Bridge operations @@ -137,36 +134,6 @@ The API MUST accept the following parameters: - [Body](./data-model.md#field-body) (optional) - [Attributes](./data-model.md#field-attributes) (optional) -### Log Instrumentation operations - -#### Emit an Event - -**Status**: [Development](../document-status.md) - -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. - -**Parameters:** - -* The [`Name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md) - of the Event. -* [Observed Timestamp](./data-model.md#field-observedtimestamp) (optional). If unspecified - the implementation SHOULD set it equal to the current time. -* The [Context](../context/README.md) 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](./data-model.md#field-severitynumber) (optional) -* [Severity Text](./data-model.md#field-severitytext) (optional) -* [Body](./data-model.md#field-body) (optional) -* [Attributes](./data-model.md#field-attributes) (optional) Event `Attributes` conform - to the [standard definition](../common/README.md#standard-attribute) of an attribute. - -### Helper operations - #### Enabled **Status**: [Development](../document-status.md) @@ -191,6 +158,31 @@ SHOULD be documented that instrumentation authors needs to call this API each time they [emit a LogRecord](#emit-a-logrecord) to ensure they have the most up-to-date response. +### Log Instrumentation operations + +#### Emit an Event + +**Status**: [Development](../document-status.md) + +The effect of calling this API is to emit a `LogRecord` to the processing pipeline +formatted as an [event](./data-model.md#events). + +**Parameters:** + +* The [`Name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md) + of the Event. +* [Observed Timestamp](./data-model.md#field-observedtimestamp) (optional). If unspecified + the implementation SHOULD set it equal to the current time. +* The [Context](../context/README.md) 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](./data-model.md#field-severitynumber) (optional) +* [Severity Text](./data-model.md#field-severitytext) (optional) +* [Body](./data-model.md#field-body) (optional) +* [Attributes](./data-model.md#field-attributes) (optional) Event `Attributes` conform + to the [standard definition](../common/README.md#standard-attribute) of an attribute. + ## Logs API **Status**: [Development](../document-status.md) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index d0281c70533..9062d26ef7a 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -7,35 +7,37 @@ -- [Design Notes](#design-notes) - * [Requirements](#requirements) - * [Definitions Used in this Document](#definitions-used-in-this-document) - + [Type `any`](#type-any) - + [Type `map`](#type-mapstring-any) - * [Field Kinds](#field-kinds) -- [Log and Event Record Definition](#log-and-event-record-definition) - * [Field: `Timestamp`](#field-timestamp) - * [Field: `ObservedTimestamp`](#field-observedtimestamp) - * [Trace Context Fields](#trace-context-fields) - + [Field: `TraceId`](#field-traceid) - + [Field: `SpanId`](#field-spanid) - + [Field: `TraceFlags`](#field-traceflags) - * [Severity Fields](#severity-fields) - + [Field: `SeverityText`](#field-severitytext) - + [Field: `SeverityNumber`](#field-severitynumber) - + [Mapping of `SeverityNumber`](#mapping-of-severitynumber) - + [Reverse Mapping](#reverse-mapping) - + [Error Semantics](#error-semantics) - + [Displaying Severity](#displaying-severity) - + [Comparing Severity](#comparing-severity) - * [Field: `Body`](#field-body) - * [Field: `Resource`](#field-resource) - * [Field: `InstrumentationScope`](#field-instrumentationscope) - * [Field: `Attributes`](#field-attributes) - + [Errors and Exceptions](#errors-and-exceptions) -- [Example Log Records](#example-log-records) -- [Example Mappings](#example-mappings) -- [References](#references) +- [Logs Data Model](#logs-data-model) + - [Design Notes](#design-notes) + - [Requirements](#requirements) + - [Events](#events) + - [Definitions Used in this Document](#definitions-used-in-this-document) + - [Type `any`](#type-any) + - [Type `map`](#type-mapstring-any) + - [Field Kinds](#field-kinds) + - [Log and Event Record Definition](#log-and-event-record-definition) + - [Field: `Timestamp`](#field-timestamp) + - [Field: `ObservedTimestamp`](#field-observedtimestamp) + - [Trace Context Fields](#trace-context-fields) + - [Field: `TraceId`](#field-traceid) + - [Field: `SpanId`](#field-spanid) + - [Field: `TraceFlags`](#field-traceflags) + - [Severity Fields](#severity-fields) + - [Field: `SeverityText`](#field-severitytext) + - [Field: `SeverityNumber`](#field-severitynumber) + - [Mapping of `SeverityNumber`](#mapping-of-severitynumber) + - [Reverse Mapping](#reverse-mapping) + - [Error Semantics](#error-semantics) + - [Displaying Severity](#displaying-severity) + - [Comparing Severity](#comparing-severity) + - [Field: `Body`](#field-body) + - [Field: `Resource`](#field-resource) + - [Field: `InstrumentationScope`](#field-instrumentationscope) + - [Field: `Attributes`](#field-attributes) + - [Errors and Exceptions](#errors-and-exceptions) + - [Example Log Records](#example-log-records) + - [Example Mappings](#example-mappings) + - [References](#references) @@ -97,6 +99,21 @@ The Data Model aims to successfully represent 3 sorts of logs and events: we include in the logs. We can likely modify the source code of the application if needed. +### Events + +**Status**: [Development](../document-status.md) + +Events are OpenTelemetry's standardized format for LogRecords. All semantic +conventions defined for logs MUST be formatted as Events. + +Events are intended to be used by OpenTelemetry instrumentation. It is not a +requirement that all LogRecords be formatted as Events. + +The Event format is as follows. Events are defined by an +[`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). +All Events with the same `event.name` MUST conform to the same schema for +both their `Attributes` and their `Body`. + ### Definitions Used in this Document In this document we refer to types `any` and `map`, defined as From 9660162b5f533ca55aea6c40772952cd74704fb9 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 12:46:20 -0700 Subject: [PATCH 12/28] fix broken link --- specification/logs/event-api.md | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 603993493df..4d0b3603f5a 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,17 +9,18 @@ -- [Logs API Development](#logs-api-development) -- [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) +- [Events API](#events-api) + - [Logs API Development](#logs-api-development) + - [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) @@ -34,7 +35,7 @@ The Event API consists of these main components: ## Logs API Development > [!NOTE] -> We are currently in the process of defining a new [Logs API](./bridge-api.md#logs-api). +> We are currently in the process of defining a new [Logs API](./api.md#logs-api). The intent is that this Logs API will incorporate the current functionality of this existing Events API and once it is defined and implemented, the Events API usage will be migrated, deprecated, renamed and eventually removed. From 71969538a3336cc55c9ed1af4c5f62bb9d13385a Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 12:49:28 -0700 Subject: [PATCH 13/28] TOC --- specification/logs/api.md | 50 +++++++------------------- specification/logs/data-model.md | 61 ++++++++++++++++---------------- specification/logs/event-api.md | 23 ++++++------ 3 files changed, 54 insertions(+), 80 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index f0577a9785f..ee8cae4c584 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -9,21 +9,19 @@ -- [Logs API](#logs-api) - - [LoggerProvider](#loggerprovider) - - [LoggerProvider operations](#loggerprovider-operations) - - [Get a Logger](#get-a-logger) - - [Logger](#logger) - - [Log Bridge operations](#log-bridge-operations) - - [Emit a LogRecord](#emit-a-logrecord) - - [Enabled](#enabled) - - [Log Instrumentation operations](#log-instrumentation-operations) - - [Emit an Event](#emit-an-event) - - [Logs API](#logs-api-1) - - [Optional and required parameters](#optional-and-required-parameters) - - [Concurrency requirements](#concurrency-requirements) - - [Artifact Naming](#artifact-naming) - - [References](#references) +- [LoggerProvider](#loggerprovider) + * [LoggerProvider operations](#loggerprovider-operations) + + [Get a Logger](#get-a-logger) +- [Logger](#logger) + * [Log Bridge operations](#log-bridge-operations) + + [Emit a LogRecord](#emit-a-logrecord) + + [Enabled](#enabled) + * [Log Instrumentation operations](#log-instrumentation-operations) + + [Emit an Event](#emit-an-event) +- [Optional and required parameters](#optional-and-required-parameters) +- [Concurrency requirements](#concurrency-requirements) +- [Artifact Naming](#artifact-naming) +- [References](#references) @@ -183,28 +181,6 @@ formatted as an [event](./data-model.md#events). * [Attributes](./data-model.md#field-attributes) (optional) Event `Attributes` conform to the [standard definition](../common/README.md#standard-attribute) of an attribute. -## Logs API - -**Status**: [Development](../document-status.md) - -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. - -**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 diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index 9062d26ef7a..ca9d815b3ff 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -7,37 +7,36 @@ -- [Logs Data Model](#logs-data-model) - - [Design Notes](#design-notes) - - [Requirements](#requirements) - - [Events](#events) - - [Definitions Used in this Document](#definitions-used-in-this-document) - - [Type `any`](#type-any) - - [Type `map`](#type-mapstring-any) - - [Field Kinds](#field-kinds) - - [Log and Event Record Definition](#log-and-event-record-definition) - - [Field: `Timestamp`](#field-timestamp) - - [Field: `ObservedTimestamp`](#field-observedtimestamp) - - [Trace Context Fields](#trace-context-fields) - - [Field: `TraceId`](#field-traceid) - - [Field: `SpanId`](#field-spanid) - - [Field: `TraceFlags`](#field-traceflags) - - [Severity Fields](#severity-fields) - - [Field: `SeverityText`](#field-severitytext) - - [Field: `SeverityNumber`](#field-severitynumber) - - [Mapping of `SeverityNumber`](#mapping-of-severitynumber) - - [Reverse Mapping](#reverse-mapping) - - [Error Semantics](#error-semantics) - - [Displaying Severity](#displaying-severity) - - [Comparing Severity](#comparing-severity) - - [Field: `Body`](#field-body) - - [Field: `Resource`](#field-resource) - - [Field: `InstrumentationScope`](#field-instrumentationscope) - - [Field: `Attributes`](#field-attributes) - - [Errors and Exceptions](#errors-and-exceptions) - - [Example Log Records](#example-log-records) - - [Example Mappings](#example-mappings) - - [References](#references) +- [Design Notes](#design-notes) + * [Requirements](#requirements) + * [Events](#events) + * [Definitions Used in this Document](#definitions-used-in-this-document) + + [Type `any`](#type-any) + + [Type `map`](#type-mapstring-any) + * [Field Kinds](#field-kinds) +- [Log and Event Record Definition](#log-and-event-record-definition) + * [Field: `Timestamp`](#field-timestamp) + * [Field: `ObservedTimestamp`](#field-observedtimestamp) + * [Trace Context Fields](#trace-context-fields) + + [Field: `TraceId`](#field-traceid) + + [Field: `SpanId`](#field-spanid) + + [Field: `TraceFlags`](#field-traceflags) + * [Severity Fields](#severity-fields) + + [Field: `SeverityText`](#field-severitytext) + + [Field: `SeverityNumber`](#field-severitynumber) + + [Mapping of `SeverityNumber`](#mapping-of-severitynumber) + + [Reverse Mapping](#reverse-mapping) + + [Error Semantics](#error-semantics) + + [Displaying Severity](#displaying-severity) + + [Comparing Severity](#comparing-severity) + * [Field: `Body`](#field-body) + * [Field: `Resource`](#field-resource) + * [Field: `InstrumentationScope`](#field-instrumentationscope) + * [Field: `Attributes`](#field-attributes) + + [Errors and Exceptions](#errors-and-exceptions) +- [Example Log Records](#example-log-records) +- [Example Mappings](#example-mappings) +- [References](#references) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 4d0b3603f5a..74957871fa3 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,18 +9,17 @@ -- [Events API](#events-api) - - [Logs API Development](#logs-api-development) - - [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) +- [Logs API Development](#logs-api-development) +- [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) From a839c35e004a1a8a3b05813db2aa3fb6c799a4d2 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 12:51:56 -0700 Subject: [PATCH 14/28] fix link --- specification/logs/event-sdk.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index e7bd857f23e..34b640b2fda 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,15 +9,16 @@ -- [Logs API Development](#logs-api-development) -- [Overview](#overview) -- [EventLoggerProvider](#eventloggerprovider) - * [EventLoggerProvider Creation](#eventloggerprovider-creation) - * [EventLogger Creation](#eventlogger-creation) - * [Configuration](#configuration) - * [ForceFlush](#forceflush) -- [EventLogger](#eventlogger) - * [Emit Event](#emit-event) +- [Events SDK](#events-sdk) + - [Logs API Development](#logs-api-development) + - [Overview](#overview) + - [EventLoggerProvider](#eventloggerprovider) + - [EventLoggerProvider Creation](#eventloggerprovider-creation) + - [EventLogger Creation](#eventlogger-creation) + - [Configuration](#configuration) + - [ForceFlush](#forceflush) + - [EventLogger](#eventlogger) + - [Emit Event](#emit-event) @@ -33,7 +34,7 @@ All implementations of the OpenTelemetry API MUST provide an SDK. ## Logs API Development > [!NOTE] -> We are currently in the process of defining a new [Logs API](./bridge-api.md#logs-api). +> We are currently in the process of defining a new [Logs API](./api.md#logs-api). The intent is that Logs SDK will incorporate the current functionality of this existing Events SDK and once it is defined and implemented, the Events SDK usage will be migrated, deprecated, renamed and eventually removed. From b36c8d92f307f48232e0b2c37b0a548c88064e2d Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 12:54:00 -0700 Subject: [PATCH 15/28] TOC --- specification/logs/event-sdk.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/specification/logs/event-sdk.md b/specification/logs/event-sdk.md index 34b640b2fda..37220a42a9b 100644 --- a/specification/logs/event-sdk.md +++ b/specification/logs/event-sdk.md @@ -9,16 +9,15 @@ -- [Events SDK](#events-sdk) - - [Logs API Development](#logs-api-development) - - [Overview](#overview) - - [EventLoggerProvider](#eventloggerprovider) - - [EventLoggerProvider Creation](#eventloggerprovider-creation) - - [EventLogger Creation](#eventlogger-creation) - - [Configuration](#configuration) - - [ForceFlush](#forceflush) - - [EventLogger](#eventlogger) - - [Emit Event](#emit-event) +- [Logs API Development](#logs-api-development) +- [Overview](#overview) +- [EventLoggerProvider](#eventloggerprovider) + * [EventLoggerProvider Creation](#eventloggerprovider-creation) + * [EventLogger Creation](#eventlogger-creation) + * [Configuration](#configuration) + * [ForceFlush](#forceflush) +- [EventLogger](#eventlogger) + * [Emit Event](#emit-event) From 88d3a94aa94fc143090f0801057db850e9d1535d Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 12:54:52 -0700 Subject: [PATCH 16/28] fix link --- specification/logs/sdk.md | 59 ++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index cbd169a54d5..310b0c9c1fe 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,34 +7,35 @@ -- [LoggerProvider](#loggerprovider) - * [LoggerProvider Creation](#loggerprovider-creation) - * [Logger Creation](#logger-creation) - * [Configuration](#configuration) - + [LoggerConfigurator](#loggerconfigurator) - * [Shutdown](#shutdown) - * [ForceFlush](#forceflush) -- [Logger](#logger) - * [LoggerConfig](#loggerconfig) -- [Additional LogRecord interfaces](#additional-logrecord-interfaces) - * [ReadableLogRecord](#readablelogrecord) - * [ReadWriteLogRecord](#readwritelogrecord) -- [LogRecord Limits](#logrecord-limits) -- [LogRecordProcessor](#logrecordprocessor) - * [LogRecordProcessor operations](#logrecordprocessor-operations) - + [OnEmit](#onemit) - + [ShutDown](#shutdown) - + [ForceFlush](#forceflush-1) - * [Built-in processors](#built-in-processors) - + [Simple processor](#simple-processor) - + [Batching processor](#batching-processor) - + [Isolating processor](#isolating-processor) -- [LogRecordExporter](#logrecordexporter) - * [LogRecordExporter operations](#logrecordexporter-operations) - + [Export](#export) - + [ForceFlush](#forceflush-2) - + [Shutdown](#shutdown-1) -- [Logs API](#logs-api) +- [Logs SDK](#logs-sdk) + - [LoggerProvider](#loggerprovider) + - [LoggerProvider Creation](#loggerprovider-creation) + - [Logger Creation](#logger-creation) + - [Configuration](#configuration) + - [LoggerConfigurator](#loggerconfigurator) + - [Shutdown](#shutdown) + - [ForceFlush](#forceflush) + - [Logger](#logger) + - [LoggerConfig](#loggerconfig) + - [Additional LogRecord interfaces](#additional-logrecord-interfaces) + - [ReadableLogRecord](#readablelogrecord) + - [ReadWriteLogRecord](#readwritelogrecord) + - [LogRecord Limits](#logrecord-limits) + - [LogRecordProcessor](#logrecordprocessor) + - [LogRecordProcessor operations](#logrecordprocessor-operations) + - [OnEmit](#onemit) + - [ShutDown](#shutdown-1) + - [ForceFlush](#forceflush-1) + - [Built-in processors](#built-in-processors) + - [Simple processor](#simple-processor) + - [Batching processor](#batching-processor) + - [Isolating processor](#isolating-processor) + - [LogRecordExporter](#logrecordexporter) + - [LogRecordExporter operations](#logrecordexporter-operations) + - [Export](#export) + - [ForceFlush](#forceflush-2) + - [Shutdown](#shutdown-2) + - [Logs API](#logs-api) @@ -542,6 +543,6 @@ authors MAY decide if they want to make the shutdown timeout configurable. ## Logs API > [!NOTE] -> We are currently in the process of defining a new [Logs API](./bridge-api.md#logs-api). +> We are currently in the process of defining a new [Logs API](./api.md#logs-api). - [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md) From 5435cade48dc59fdf60dfabe2285c8c7d2ae4468 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 12:57:01 -0700 Subject: [PATCH 17/28] toc --- specification/logs/sdk.md | 57 +++++++++++++++++++-------------------- 1 file changed, 28 insertions(+), 29 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 310b0c9c1fe..dfdb4b55fa6 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -7,35 +7,34 @@ -- [Logs SDK](#logs-sdk) - - [LoggerProvider](#loggerprovider) - - [LoggerProvider Creation](#loggerprovider-creation) - - [Logger Creation](#logger-creation) - - [Configuration](#configuration) - - [LoggerConfigurator](#loggerconfigurator) - - [Shutdown](#shutdown) - - [ForceFlush](#forceflush) - - [Logger](#logger) - - [LoggerConfig](#loggerconfig) - - [Additional LogRecord interfaces](#additional-logrecord-interfaces) - - [ReadableLogRecord](#readablelogrecord) - - [ReadWriteLogRecord](#readwritelogrecord) - - [LogRecord Limits](#logrecord-limits) - - [LogRecordProcessor](#logrecordprocessor) - - [LogRecordProcessor operations](#logrecordprocessor-operations) - - [OnEmit](#onemit) - - [ShutDown](#shutdown-1) - - [ForceFlush](#forceflush-1) - - [Built-in processors](#built-in-processors) - - [Simple processor](#simple-processor) - - [Batching processor](#batching-processor) - - [Isolating processor](#isolating-processor) - - [LogRecordExporter](#logrecordexporter) - - [LogRecordExporter operations](#logrecordexporter-operations) - - [Export](#export) - - [ForceFlush](#forceflush-2) - - [Shutdown](#shutdown-2) - - [Logs API](#logs-api) +- [LoggerProvider](#loggerprovider) + * [LoggerProvider Creation](#loggerprovider-creation) + * [Logger Creation](#logger-creation) + * [Configuration](#configuration) + + [LoggerConfigurator](#loggerconfigurator) + * [Shutdown](#shutdown) + * [ForceFlush](#forceflush) +- [Logger](#logger) + * [LoggerConfig](#loggerconfig) +- [Additional LogRecord interfaces](#additional-logrecord-interfaces) + * [ReadableLogRecord](#readablelogrecord) + * [ReadWriteLogRecord](#readwritelogrecord) +- [LogRecord Limits](#logrecord-limits) +- [LogRecordProcessor](#logrecordprocessor) + * [LogRecordProcessor operations](#logrecordprocessor-operations) + + [OnEmit](#onemit) + + [ShutDown](#shutdown) + + [ForceFlush](#forceflush-1) + * [Built-in processors](#built-in-processors) + + [Simple processor](#simple-processor) + + [Batching processor](#batching-processor) + + [Isolating processor](#isolating-processor) +- [LogRecordExporter](#logrecordexporter) + * [LogRecordExporter operations](#logrecordexporter-operations) + + [Export](#export) + + [ForceFlush](#forceflush-2) + + [Shutdown](#shutdown-1) +- [Logs API](#logs-api) From 5982ca3c6d066c05158e91384403541d8b99ae52 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 12:59:19 -0700 Subject: [PATCH 18/28] should --- specification/logs/data-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index ca9d815b3ff..42d1733b9b9 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -103,7 +103,7 @@ The Data Model aims to successfully represent 3 sorts of logs and events: **Status**: [Development](../document-status.md) Events are OpenTelemetry's standardized format for LogRecords. All semantic -conventions defined for logs MUST be formatted as Events. +conventions defined for logs SHOULD be formatted as Events. Events are intended to be used by OpenTelemetry instrumentation. It is not a requirement that all LogRecords be formatted as Events. From e9809b7f9d4483ed1f21b20fc9fe628cb133b6ff Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 22 Oct 2024 14:49:30 -0700 Subject: [PATCH 19/28] grammar --- specification/logs/data-model.md | 63 ++++++++++++++++---------------- 1 file changed, 32 insertions(+), 31 deletions(-) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index 42d1733b9b9..3a0bae2aa2e 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -7,36 +7,37 @@ -- [Design Notes](#design-notes) - * [Requirements](#requirements) - * [Events](#events) - * [Definitions Used in this Document](#definitions-used-in-this-document) - + [Type `any`](#type-any) - + [Type `map`](#type-mapstring-any) - * [Field Kinds](#field-kinds) -- [Log and Event Record Definition](#log-and-event-record-definition) - * [Field: `Timestamp`](#field-timestamp) - * [Field: `ObservedTimestamp`](#field-observedtimestamp) - * [Trace Context Fields](#trace-context-fields) - + [Field: `TraceId`](#field-traceid) - + [Field: `SpanId`](#field-spanid) - + [Field: `TraceFlags`](#field-traceflags) - * [Severity Fields](#severity-fields) - + [Field: `SeverityText`](#field-severitytext) - + [Field: `SeverityNumber`](#field-severitynumber) - + [Mapping of `SeverityNumber`](#mapping-of-severitynumber) - + [Reverse Mapping](#reverse-mapping) - + [Error Semantics](#error-semantics) - + [Displaying Severity](#displaying-severity) - + [Comparing Severity](#comparing-severity) - * [Field: `Body`](#field-body) - * [Field: `Resource`](#field-resource) - * [Field: `InstrumentationScope`](#field-instrumentationscope) - * [Field: `Attributes`](#field-attributes) - + [Errors and Exceptions](#errors-and-exceptions) -- [Example Log Records](#example-log-records) -- [Example Mappings](#example-mappings) -- [References](#references) +- [Logs Data Model](#logs-data-model) + - [Design Notes](#design-notes) + - [Requirements](#requirements) + - [Events](#events) + - [Definitions Used in this Document](#definitions-used-in-this-document) + - [Type `any`](#type-any) + - [Type `map`](#type-mapstring-any) + - [Field Kinds](#field-kinds) + - [Log and Event Record Definition](#log-and-event-record-definition) + - [Field: `Timestamp`](#field-timestamp) + - [Field: `ObservedTimestamp`](#field-observedtimestamp) + - [Trace Context Fields](#trace-context-fields) + - [Field: `TraceId`](#field-traceid) + - [Field: `SpanId`](#field-spanid) + - [Field: `TraceFlags`](#field-traceflags) + - [Severity Fields](#severity-fields) + - [Field: `SeverityText`](#field-severitytext) + - [Field: `SeverityNumber`](#field-severitynumber) + - [Mapping of `SeverityNumber`](#mapping-of-severitynumber) + - [Reverse Mapping](#reverse-mapping) + - [Error Semantics](#error-semantics) + - [Displaying Severity](#displaying-severity) + - [Comparing Severity](#comparing-severity) + - [Field: `Body`](#field-body) + - [Field: `Resource`](#field-resource) + - [Field: `InstrumentationScope`](#field-instrumentationscope) + - [Field: `Attributes`](#field-attributes) + - [Errors and Exceptions](#errors-and-exceptions) + - [Example Log Records](#example-log-records) + - [Example Mappings](#example-mappings) + - [References](#references) @@ -106,7 +107,7 @@ Events are OpenTelemetry's standardized format for LogRecords. All semantic conventions defined for logs SHOULD be formatted as Events. Events are intended to be used by OpenTelemetry instrumentation. It is not a -requirement that all LogRecords be formatted as Events. +requirement that all LogRecords are formatted as Events. The Event format is as follows. Events are defined by an [`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). From a11187114a65c782622d5ddda90f6899e19a4b55 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Wed, 23 Oct 2024 10:09:10 -0700 Subject: [PATCH 20/28] add timestamp to EmitEvent --- specification/logs/api.md | 1 + specification/logs/data-model.md | 61 ++++++++++++++++---------------- 2 files changed, 31 insertions(+), 31 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index ee8cae4c584..43bdbf33f6a 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -169,6 +169,7 @@ formatted as an [event](./data-model.md#events). * The [`Name`](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md) of the Event. +* [Timestamp](./data-model.md#field-timestamp) (optional) * [Observed Timestamp](./data-model.md#field-observedtimestamp) (optional). If unspecified the implementation SHOULD set it equal to the current time. * The [Context](../context/README.md) associated with the `Event`. When implicit diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index 3a0bae2aa2e..07efb4a7aff 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -7,37 +7,36 @@ -- [Logs Data Model](#logs-data-model) - - [Design Notes](#design-notes) - - [Requirements](#requirements) - - [Events](#events) - - [Definitions Used in this Document](#definitions-used-in-this-document) - - [Type `any`](#type-any) - - [Type `map`](#type-mapstring-any) - - [Field Kinds](#field-kinds) - - [Log and Event Record Definition](#log-and-event-record-definition) - - [Field: `Timestamp`](#field-timestamp) - - [Field: `ObservedTimestamp`](#field-observedtimestamp) - - [Trace Context Fields](#trace-context-fields) - - [Field: `TraceId`](#field-traceid) - - [Field: `SpanId`](#field-spanid) - - [Field: `TraceFlags`](#field-traceflags) - - [Severity Fields](#severity-fields) - - [Field: `SeverityText`](#field-severitytext) - - [Field: `SeverityNumber`](#field-severitynumber) - - [Mapping of `SeverityNumber`](#mapping-of-severitynumber) - - [Reverse Mapping](#reverse-mapping) - - [Error Semantics](#error-semantics) - - [Displaying Severity](#displaying-severity) - - [Comparing Severity](#comparing-severity) - - [Field: `Body`](#field-body) - - [Field: `Resource`](#field-resource) - - [Field: `InstrumentationScope`](#field-instrumentationscope) - - [Field: `Attributes`](#field-attributes) - - [Errors and Exceptions](#errors-and-exceptions) - - [Example Log Records](#example-log-records) - - [Example Mappings](#example-mappings) - - [References](#references) +- [Design Notes](#design-notes) + * [Requirements](#requirements) + * [Events](#events) + * [Definitions Used in this Document](#definitions-used-in-this-document) + + [Type `any`](#type-any) + + [Type `map`](#type-mapstring-any) + * [Field Kinds](#field-kinds) +- [Log and Event Record Definition](#log-and-event-record-definition) + * [Field: `Timestamp`](#field-timestamp) + * [Field: `ObservedTimestamp`](#field-observedtimestamp) + * [Trace Context Fields](#trace-context-fields) + + [Field: `TraceId`](#field-traceid) + + [Field: `SpanId`](#field-spanid) + + [Field: `TraceFlags`](#field-traceflags) + * [Severity Fields](#severity-fields) + + [Field: `SeverityText`](#field-severitytext) + + [Field: `SeverityNumber`](#field-severitynumber) + + [Mapping of `SeverityNumber`](#mapping-of-severitynumber) + + [Reverse Mapping](#reverse-mapping) + + [Error Semantics](#error-semantics) + + [Displaying Severity](#displaying-severity) + + [Comparing Severity](#comparing-severity) + * [Field: `Body`](#field-body) + * [Field: `Resource`](#field-resource) + * [Field: `InstrumentationScope`](#field-instrumentationscope) + * [Field: `Attributes`](#field-attributes) + + [Errors and Exceptions](#errors-and-exceptions) +- [Example Log Records](#example-log-records) +- [Example Mappings](#example-mappings) +- [References](#references) From 7675a7fe65859ac1d630cc38b82c4a4d4f1793d3 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Wed, 23 Oct 2024 10:10:39 -0700 Subject: [PATCH 21/28] remove helpers from logger --- specification/logs/api.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index 43bdbf33f6a..c1d60048d30 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -93,16 +93,15 @@ instances where at least one parameter has a different value. ## Logger -The `Logger` is responsible for emitting `LogRecord`s. There are three types of +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. -* **Helper** operations to assist with using the logger. -The Logger contains methods for all types of operations. The `Logger` MUST +The Logger contains methods for both types of operations. The `Logger` MUST provide a function to: - [Emit a `LogRecord`](#emit-a-logrecord) From c5df930077228a80b03833da105c941ebebed9a4 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Wed, 23 Oct 2024 10:17:08 -0700 Subject: [PATCH 22/28] remove artifact naming section --- specification/logs/api.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/specification/logs/api.md b/specification/logs/api.md index c1d60048d30..f529c8c373e 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -20,7 +20,6 @@ + [Emit an Event](#emit-an-event) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) -- [Artifact Naming](#artifact-naming) - [References](#references) @@ -201,15 +200,6 @@ specific guarantees and safeties. **Logger** - all methods are safe to be called concurrently. -## Artifact Naming - -The Logs 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 API would -be a natural starting point. Therefore, Log 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) From fccd2740b04dfa87a3cb3f84a8f5bfadbfe8b39c Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 29 Oct 2024 09:45:24 -0500 Subject: [PATCH 23/28] clarify requirements for events --- specification/logs/data-model.md | 64 ++++++++++++++++---------------- 1 file changed, 33 insertions(+), 31 deletions(-) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index 07efb4a7aff..f4c9ba0bcc4 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -7,36 +7,37 @@ -- [Design Notes](#design-notes) - * [Requirements](#requirements) - * [Events](#events) - * [Definitions Used in this Document](#definitions-used-in-this-document) - + [Type `any`](#type-any) - + [Type `map`](#type-mapstring-any) - * [Field Kinds](#field-kinds) -- [Log and Event Record Definition](#log-and-event-record-definition) - * [Field: `Timestamp`](#field-timestamp) - * [Field: `ObservedTimestamp`](#field-observedtimestamp) - * [Trace Context Fields](#trace-context-fields) - + [Field: `TraceId`](#field-traceid) - + [Field: `SpanId`](#field-spanid) - + [Field: `TraceFlags`](#field-traceflags) - * [Severity Fields](#severity-fields) - + [Field: `SeverityText`](#field-severitytext) - + [Field: `SeverityNumber`](#field-severitynumber) - + [Mapping of `SeverityNumber`](#mapping-of-severitynumber) - + [Reverse Mapping](#reverse-mapping) - + [Error Semantics](#error-semantics) - + [Displaying Severity](#displaying-severity) - + [Comparing Severity](#comparing-severity) - * [Field: `Body`](#field-body) - * [Field: `Resource`](#field-resource) - * [Field: `InstrumentationScope`](#field-instrumentationscope) - * [Field: `Attributes`](#field-attributes) - + [Errors and Exceptions](#errors-and-exceptions) -- [Example Log Records](#example-log-records) -- [Example Mappings](#example-mappings) -- [References](#references) +- [Logs Data Model](#logs-data-model) + - [Design Notes](#design-notes) + - [Requirements](#requirements) + - [Events](#events) + - [Definitions Used in this Document](#definitions-used-in-this-document) + - [Type `any`](#type-any) + - [Type `map`](#type-mapstring-any) + - [Field Kinds](#field-kinds) + - [Log and Event Record Definition](#log-and-event-record-definition) + - [Field: `Timestamp`](#field-timestamp) + - [Field: `ObservedTimestamp`](#field-observedtimestamp) + - [Trace Context Fields](#trace-context-fields) + - [Field: `TraceId`](#field-traceid) + - [Field: `SpanId`](#field-spanid) + - [Field: `TraceFlags`](#field-traceflags) + - [Severity Fields](#severity-fields) + - [Field: `SeverityText`](#field-severitytext) + - [Field: `SeverityNumber`](#field-severitynumber) + - [Mapping of `SeverityNumber`](#mapping-of-severitynumber) + - [Reverse Mapping](#reverse-mapping) + - [Error Semantics](#error-semantics) + - [Displaying Severity](#displaying-severity) + - [Comparing Severity](#comparing-severity) + - [Field: `Body`](#field-body) + - [Field: `Resource`](#field-resource) + - [Field: `InstrumentationScope`](#field-instrumentationscope) + - [Field: `Attributes`](#field-attributes) + - [Errors and Exceptions](#errors-and-exceptions) + - [Example Log Records](#example-log-records) + - [Example Mappings](#example-mappings) + - [References](#references) @@ -111,7 +112,8 @@ requirement that all LogRecords are formatted as Events. The Event format is as follows. Events are defined by an [`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). All Events with the same `event.name` MUST conform to the same schema for -both their `Attributes` and their `Body`. +both their `Attributes` and their `Body`. Any additional requirements for +individual events can be found in the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). ### Definitions Used in this Document From f22d8cb1f0e5c3bb925e5650682b173bff533429 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 29 Oct 2024 10:51:39 -0500 Subject: [PATCH 24/28] move all event data model requirements to semconv --- specification/logs/data-model.md | 69 ++++++++++++++------------------ 1 file changed, 31 insertions(+), 38 deletions(-) diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index f4c9ba0bcc4..c7e88dd745b 100644 --- a/specification/logs/data-model.md +++ b/specification/logs/data-model.md @@ -7,37 +7,36 @@ -- [Logs Data Model](#logs-data-model) - - [Design Notes](#design-notes) - - [Requirements](#requirements) - - [Events](#events) - - [Definitions Used in this Document](#definitions-used-in-this-document) - - [Type `any`](#type-any) - - [Type `map`](#type-mapstring-any) - - [Field Kinds](#field-kinds) - - [Log and Event Record Definition](#log-and-event-record-definition) - - [Field: `Timestamp`](#field-timestamp) - - [Field: `ObservedTimestamp`](#field-observedtimestamp) - - [Trace Context Fields](#trace-context-fields) - - [Field: `TraceId`](#field-traceid) - - [Field: `SpanId`](#field-spanid) - - [Field: `TraceFlags`](#field-traceflags) - - [Severity Fields](#severity-fields) - - [Field: `SeverityText`](#field-severitytext) - - [Field: `SeverityNumber`](#field-severitynumber) - - [Mapping of `SeverityNumber`](#mapping-of-severitynumber) - - [Reverse Mapping](#reverse-mapping) - - [Error Semantics](#error-semantics) - - [Displaying Severity](#displaying-severity) - - [Comparing Severity](#comparing-severity) - - [Field: `Body`](#field-body) - - [Field: `Resource`](#field-resource) - - [Field: `InstrumentationScope`](#field-instrumentationscope) - - [Field: `Attributes`](#field-attributes) - - [Errors and Exceptions](#errors-and-exceptions) - - [Example Log Records](#example-log-records) - - [Example Mappings](#example-mappings) - - [References](#references) +- [Design Notes](#design-notes) + * [Requirements](#requirements) + * [Events](#events) + * [Definitions Used in this Document](#definitions-used-in-this-document) + + [Type `any`](#type-any) + + [Type `map`](#type-mapstring-any) + * [Field Kinds](#field-kinds) +- [Log and Event Record Definition](#log-and-event-record-definition) + * [Field: `Timestamp`](#field-timestamp) + * [Field: `ObservedTimestamp`](#field-observedtimestamp) + * [Trace Context Fields](#trace-context-fields) + + [Field: `TraceId`](#field-traceid) + + [Field: `SpanId`](#field-spanid) + + [Field: `TraceFlags`](#field-traceflags) + * [Severity Fields](#severity-fields) + + [Field: `SeverityText`](#field-severitytext) + + [Field: `SeverityNumber`](#field-severitynumber) + + [Mapping of `SeverityNumber`](#mapping-of-severitynumber) + + [Reverse Mapping](#reverse-mapping) + + [Error Semantics](#error-semantics) + + [Displaying Severity](#displaying-severity) + + [Comparing Severity](#comparing-severity) + * [Field: `Body`](#field-body) + * [Field: `Resource`](#field-resource) + * [Field: `InstrumentationScope`](#field-instrumentationscope) + * [Field: `Attributes`](#field-attributes) + + [Errors and Exceptions](#errors-and-exceptions) +- [Example Log Records](#example-log-records) +- [Example Mappings](#example-mappings) +- [References](#references) @@ -104,17 +103,11 @@ The Data Model aims to successfully represent 3 sorts of logs and events: **Status**: [Development](../document-status.md) Events are OpenTelemetry's standardized format for LogRecords. All semantic -conventions defined for logs SHOULD be formatted as Events. +conventions defined for logs SHOULD be formatted as Events. Requirements and details for the Event format can be found in the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). Events are intended to be used by OpenTelemetry instrumentation. It is not a requirement that all LogRecords are formatted as Events. -The Event format is as follows. Events are defined by an -[`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). -All Events with the same `event.name` MUST conform to the same schema for -both their `Attributes` and their `Body`. Any additional requirements for -individual events can be found in the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). - ### Definitions Used in this Document In this document we refer to types `any` and `map`, defined as From 418e39302666bbc72c3a77519397aa376d9fc1bd Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 29 Oct 2024 16:00:39 -0500 Subject: [PATCH 25/28] add documentation guidelines for log bridge --- specification/logs/api.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/logs/api.md b/specification/logs/api.md index f529c8c373e..9ef141cfdd9 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -112,6 +112,9 @@ 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. From 2a528590a2af4fc42bb8a79f7f1d705535950d20 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 29 Oct 2024 16:03:20 -0500 Subject: [PATCH 26/28] update changelog --- CHANGELOG.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0a974eb8d6d..dc5f58f9b2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -66,7 +66,9 @@ release. - Introduce initial placeholder for the new user-facing Logs API, adding references to existing API's informing of the coming changes while the definition is defined. ([#4236](https://github.com/open-telemetry/opentelemetry-specification/pull/4236)) -- Moved the EventProvider and EventLogger into to the LogProvider and Logger.([#4259](https://github.com/open-telemetry/opentelemetry-specification/pull/4259)) +- Renamed Log Bridge API to Logs API. Defined the existing Logger methods to be + Log Bridge Operations. Added EmitEvent to the Logger as an Instrumentation Operation. + ([#4259](https://github.com/open-telemetry/opentelemetry-specification/pull/4259)) ### Common From dfc980f64a475c02e58b759070210382a11566bd Mon Sep 17 00:00:00 2001 From: Ted Young Date: Tue, 29 Oct 2024 16:08:12 -0500 Subject: [PATCH 27/28] whitespace --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bfe809b14eb..f399bde7437 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -77,7 +77,7 @@ release. - Introduce initial placeholder for the new user-facing Logs API, adding references to existing API's informing of the coming changes while the definition is defined. ([#4236](https://github.com/open-telemetry/opentelemetry-specification/pull/4236)) -- Renamed Log Bridge API to Logs API. Defined the existing Logger methods to be +- Renamed Log Bridge API to Logs API. Defined the existing Logger methods to be Log Bridge Operations. Added EmitEvent to the Logger as an Instrumentation Operation. ([#4259](https://github.com/open-telemetry/opentelemetry-specification/pull/4259)) From 37ad4bd517c6fafb54900828561c34eb41988f7d Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 30 Oct 2024 11:59:06 -0700 Subject: [PATCH 28/28] Update CHANGELOG.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Robert Pająk --- CHANGELOG.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f399bde7437..17d34986b20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -77,8 +77,8 @@ release. - Introduce initial placeholder for the new user-facing Logs API, adding references to existing API's informing of the coming changes while the definition is defined. ([#4236](https://github.com/open-telemetry/opentelemetry-specification/pull/4236)) -- Renamed Log Bridge API to Logs API. Defined the existing Logger methods to be - Log Bridge Operations. Added EmitEvent to the Logger as an Instrumentation Operation. +- Rename Log Bridge API to Logs API. Define the existing Logger methods to be + Log Bridge Operations. Add EmitEvent to the Logger as an Instrumentation Operation. ([#4259](https://github.com/open-telemetry/opentelemetry-specification/pull/4259)) ### Common