From 105018521099e4e2abc4409ee3a1f8aa1f06b846 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 29 Mar 2024 14:27:52 -0700 Subject: [PATCH 01/19] Further define the definition and use cases for Events --- specification/logs/event-api.md | 49 +++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 17 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index db098cc1ec2..baada216bd2 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,15 +9,16 @@ -- [Data model](#data-model) -- [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) + - [Data model](#data-model) + - [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) @@ -36,17 +37,31 @@ Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file): >operating system or other software runs. From OpenTelemetry's perspective LogRecords and Events are both represented -using the same [data model](./data-model.md). +using the same [data model](./data-model.md). An Event is a specialized type +of LogRecord, not a seperate concept. -However, OpenTelemetry does recognize a subtle semantic difference between -LogRecords and Events: Events are LogRecords which have a `name` which uniquely -defines a particular class or type of event. All events with the same `name` -have `Body` that conform to the same schema, which assists in analysis in -observability platforms. Events are described in more detail in -the [semantic conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md). +Events contain all of the features provided by LogRecords, plus one additional +feature. All Events have a `name`. Events with the same `name` MUST conform to +the same schema for both their `Attributes` and their `Body`. Unlike the [Logs Bridge API](./bridge-api.md), application developers and -instrumentation authors are encouraged to call this API directly. +instrumentation authors are encouraged to call this API directly. It is +appropriate to use the Event API when these properties fit your requirements: + +* A consistent schema that can be identified by a name is necessary. +* A semantic convention needs to be defined. We do not define semantic + conventions for logs. +* Analysis by an Observability platform is the intended use case. For + example: statistics, indexing, machine learning, session replay. + +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 Events are sent directly to the OTel Log SDK, which currently lacks a +number of advanced features present in popular log frameworks. For example: +pattern logging, file rotation, network appenders, etc. These features cannot be +used with events at this time. ## EventLoggerProvider From c0e9ff01f950a5f0acf156334ec6ce3918bd78e3 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 29 Mar 2024 14:36:55 -0700 Subject: [PATCH 02/19] cleanup --- specification/logs/event-api.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index baada216bd2..d193bd671dd 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -49,19 +49,18 @@ instrumentation authors are encouraged to call this API directly. It is appropriate to use the Event API when these properties fit your requirements: * A consistent schema that can be identified by a name is necessary. -* A semantic convention needs to be defined. We do not define semantic - conventions for logs. * Analysis by an Observability platform is the intended use case. For example: statistics, indexing, machine learning, session replay. +* A semantic convention needs to be defined. We do not define semantic + conventions for LogRecords that are not Events. 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 Events are sent directly to the OTel Log SDK, which currently lacks a number of advanced features present in popular log frameworks. For example: pattern logging, file rotation, network appenders, etc. These features cannot be -used with events at this time. +used with Events at this time. ## EventLoggerProvider From c6f026f5dc2bfa10b941bf07850729c3aa4e677c Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 29 Mar 2024 14:46:06 -0700 Subject: [PATCH 03/19] grammar --- 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 d193bd671dd..2ce9efc1042 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -55,7 +55,7 @@ appropriate to use the Event API when these properties fit your requirements: conventions for LogRecords that are not Events. 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). +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 Events are sent directly to the OTel Log SDK, which currently lacks a number of advanced features present in popular log frameworks. For example: From 0b45d08198639fc1057518a8b634825b7547208c Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 29 Mar 2024 14:52:00 -0700 Subject: [PATCH 04/19] whitespace --- specification/logs/event-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 2ce9efc1042..237a5182d11 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -45,7 +45,7 @@ feature. All Events have a `name`. Events with the same `name` MUST conform to the same schema for both their `Attributes` and their `Body`. Unlike the [Logs Bridge API](./bridge-api.md), application developers and -instrumentation authors are encouraged to call this API directly. It is +instrumentation authors are encouraged to call this API directly. It is appropriate to use the Event API when these properties fit your requirements: * A consistent schema that can be identified by a name is necessary. @@ -58,7 +58,7 @@ If any of these properties fit your requirements, we recommend using the Event A 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 Events are sent directly to the OTel Log SDK, which currently lacks a -number of advanced features present in popular log frameworks. For example: +number of advanced features present in popular log frameworks. For example: pattern logging, file rotation, network appenders, etc. These features cannot be used with Events at this time. From 2d72603d1142c081cc69dd2aa848064954452b65 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 29 Mar 2024 14:53:03 -0700 Subject: [PATCH 05/19] spelling --- 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 237a5182d11..629939003de 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -38,7 +38,7 @@ Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file): 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 seperate concept. +of LogRecord, not a separate concept. Events contain all of the features provided by LogRecords, plus one additional feature. All Events have a `name`. Events with the same `name` MUST conform to From a1e43989d677b4e8d6bb29656a1577c482b502be Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 29 Mar 2024 19:03:09 -0700 Subject: [PATCH 06/19] Note about log frameworks --- specification/logs/event-api.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 629939003de..5493adff7b2 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -60,7 +60,9 @@ Events are described in more detail in the [semantic conventions](https://github Please note that Events are sent directly to the OTel Log SDK, which currently lacks a number of advanced features present in popular log frameworks. For example: pattern logging, file rotation, network appenders, etc. These features cannot be -used with Events at this time. +used with the Event API at this time. If a log framework is capable of creating +logs which correctly map to the Event data model, that is also an acceptable +way to create Events. ## EventLoggerProvider From 4241da2ea6ebaf3c0d761673b45959697554b58f Mon Sep 17 00:00:00 2001 From: Ted Young Date: Thu, 16 May 2024 15:38:44 -0700 Subject: [PATCH 07/19] Update event-api.md Refine use cases based issue #4045 --- specification/logs/event-api.md | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 5493adff7b2..03bccdc0a73 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -41,28 +41,35 @@ using the same [data model](./data-model.md). An Event is a specialized type of LogRecord, not a separate concept. Events contain all of the features provided by LogRecords, plus one additional -feature. All Events have a `name`. Events with the same `name` MUST conform to -the same schema for both their `Attributes` and their `Body`. +feature: every event is a semantic convention. All Events have a +`name`, and all Events with the same `name` MUST conform to the same schema for +both their `Attributes` and their `Body`. This additional -Unlike the [Logs Bridge API](./bridge-api.md), application developers and -instrumentation authors 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 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 and are encouraged +to call this API directly. It is appropriate to use the Event API when these properties fit your requirements: -* A consistent schema that can be identified by a name is necessary. -* Analysis by an Observability platform is the intended use case. For - example: statistics, indexing, machine learning, session replay. +* 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 Events are sent directly to the OTel Log SDK, which currently lacks a -number of advanced features present in popular log frameworks. For example: +Please note that Events are sent directly to the OTel Log SDK, which currently +lacks a number of advanced features present in popular log frameworks. For example: pattern logging, file rotation, network appenders, etc. These features cannot be -used with the Event API at this time. If a log framework is capable of creating -logs which correctly map to the Event data model, that is also an acceptable -way to create Events. +used with the Event API at this time. + +If a third party logging framework is capable of creating logs which correctly map +to the Event data model, loggin in this manner is also an acceptable way to create +Events. For application developers that need additional logging features, we +recommend using this approach. For shared libraries and instrumentation, we recommend +using the Event API directly, to avoid taking a dependecy on a third party logger. ## EventLoggerProvider From ad29846ceaa41b37862deaa6f4a987d50b975430 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Thu, 16 May 2024 17:19:27 -0700 Subject: [PATCH 08/19] Update event-api.md typo --- 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 03bccdc0a73..2b0b1d82457 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -66,7 +66,7 @@ pattern logging, file rotation, network appenders, etc. These features cannot be used with the Event API at this time. If a third party logging framework is capable of creating logs which correctly map -to the Event data model, loggin in this manner is also an acceptable way to create +to the Event data model, logging in this manner is also an acceptable way to create Events. For application developers that need additional logging features, we recommend using this approach. For shared libraries and instrumentation, we recommend using the Event API directly, to avoid taking a dependecy on a third party logger. From 1c4845b98dc199d546f4c11d2b8c714b46e28d16 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 17 May 2024 15:22:58 -0700 Subject: [PATCH 09/19] Simplify adivce for using 3rd party loggers --- specification/logs/event-api.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 2b0b1d82457..ac39101c437 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -26,7 +26,8 @@ The Event API consists of these main components: -* [EventLoggerProvider](#eventloggerprovider) is the entry point of the API. It provides access to `EventLogger`s. +* [EventLoggerProvider](#eventloggerprovider) is the entry point of the API. It + provides access to `EventLogger`s. * [EventLogger](#eventlogger) is the component responsible for emitting events. ## Data model @@ -46,8 +47,10 @@ feature: every event is a semantic convention. All Events have a both their `Attributes` and their `Body`. This additional 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 and are encouraged -to call this API directly. It is appropriate to use the Event API when these properties fit your requirements: +logs without needing to depend on a third party logger. Unlike the +[Logs Bridge API](./bridge-api.md), instrumentation authors and application +developers and 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 @@ -65,11 +68,9 @@ lacks a number of advanced features present in popular log frameworks. For examp pattern logging, file rotation, network appenders, etc. These features cannot be used with the Event API at this time. -If a third party logging framework 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. For application developers that need additional logging features, we -recommend using this approach. For shared libraries and instrumentation, we recommend -using the Event API directly, to avoid taking a dependecy on a third party logger. +If a logging framework 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 From 53d1d8ecb9a50d43b77e0f6e8b445890ddf73153 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 17 May 2024 15:24:43 -0700 Subject: [PATCH 10/19] typo --- 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 ac39101c437..9467cff52b7 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -44,7 +44,7 @@ of LogRecord, not a separate concept. Events contain all of the features provided by LogRecords, plus one additional feature: every event is a semantic convention. All Events have a `name`, and all Events with the same `name` MUST conform to the same schema for -both their `Attributes` and their `Body`. This additional +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 From 1d9e73c524ea443158c0fbd2c359ee080d05099d Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 17 May 2024 15:31:52 -0700 Subject: [PATCH 11/19] update toc --- specification/logs/event-api.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 9467cff52b7..b072de1688c 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,16 +9,15 @@ -- [Events API](#events-api) - - [Data model](#data-model) - - [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) +- [Data model](#data-model) +- [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 933ce141032bac78e9dce12e51ef09afca51e1d4 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Wed, 29 May 2024 11:52:50 -0700 Subject: [PATCH 12/19] typo --- 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 b072de1688c..6c3a77a70b2 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -48,7 +48,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 -developers and are encouraged to call this API directly. It is appropriate to +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. From 2e8bd763a5a74e8898469ae6a1768b6a62b87189 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Thu, 30 May 2024 11:37:21 -0700 Subject: [PATCH 13/19] seperate data model section from API usecases --- specification/logs/event-api.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 6c3a77a70b2..1e6f6974157 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,15 +9,17 @@ -- [Data model](#data-model) -- [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) + - [Event Data model](#event-data-model) + - [Event API usecases](#event-api-usecases) + - [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) @@ -29,7 +31,7 @@ The Event API consists of these main components: provides access to `EventLogger`s. * [EventLogger](#eventlogger) is the component responsible for emitting events. -## Data model +## Event Data model Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file): @@ -45,6 +47,8 @@ feature: every event is a semantic convention. All Events have a `name`, and all Events with the same `name` MUST conform to the same schema for both their `Attributes` and their `Body`. +## Event API usecases + 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 From 234854580480a8a6eefc84e597f1409c1342d383 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Thu, 30 May 2024 11:44:44 -0700 Subject: [PATCH 14/19] clarify that Events are a semantic format for LogRecods --- specification/logs/event-api.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 1e6f6974157..09cb4ccaefd 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -42,10 +42,15 @@ 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 contain all of the features provided by LogRecords, plus one additional -feature: every event is a semantic convention. All Events have a -`name`, and all Events with the same `name` MUST conform to the same schema for -both their `Attributes` and their `Body`. +Events are OpenTelemetry's standardized semantic formatting for LogRecords. +Beyond the structure provided by the LogRecord data model, it is helpful for +logs to have a common format within that structure. When OpenTelemetry +instrumentation emits logs, those logs SHOULD be formatted as Events. All +semantic conventions defined for logs MUST be formatted as Events. + +The Event format is as follows. All Events have a `name` attribute, and all +Events with the same `name` MUST conform to the same schema for both their +`Attributes` and their `Body`. ## Event API usecases From 526c64d8a67ab1e783282d001e92bfe385bc40fa Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 31 May 2024 10:19:12 -0700 Subject: [PATCH 15/19] update toc --- specification/logs/event-api.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 09cb4ccaefd..0f66c82eb48 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,17 +9,16 @@ -- [Events API](#events-api) - - [Event Data model](#event-data-model) - - [Event API usecases](#event-api-usecases) - - [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) +- [Event Data model](#event-data-model) +- [Event API usecases](#event-api-usecases) +- [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 f0ace1418b8605f1c431fd2c936a466c9e0de30e Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 31 May 2024 10:23:09 -0700 Subject: [PATCH 16/19] nits --- 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 0f66c82eb48..3c87125fa3f 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,16 +9,17 @@ -- [Event Data model](#event-data-model) -- [Event API usecases](#event-api-usecases) -- [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) + - [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) @@ -51,7 +52,7 @@ The Event format is as follows. All Events have a `name` attribute, and all Events with the same `name` MUST conform to the same schema for both their `Attributes` and their `Body`. -## Event API usecases +## 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 @@ -75,7 +76,7 @@ lacks a number of advanced features present in popular log frameworks. For examp pattern logging, file rotation, network appenders, etc. These features cannot be used with the Event API at this time. -If a logging framework is capable of creating logs which correctly map +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. From dc6eb3b26f944056f0e3b2c354ddd07fe7a2450d Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 31 May 2024 10:28:49 -0700 Subject: [PATCH 17/19] clarify that the lack of features is specific to the SDK --- specification/logs/event-api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 3c87125fa3f..42e003763df 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -71,10 +71,10 @@ use the Event API when these properties fit your requirements: 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 Events are sent directly to the OTel Log SDK, which currently -lacks a number of advanced features present in popular log frameworks. For example: -pattern logging, file rotation, network appenders, etc. These features cannot be -used with the Event API at this time. +Please note that the OpenTelemetry Log SDK currently lacks a number of advanced +features present in popular log frameworks. 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 From 493473f642d904ac1a58410fbb0dae46293dbd58 Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 31 May 2024 10:40:31 -0700 Subject: [PATCH 18/19] nits --- 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 42e003763df..46f0e0dc25c 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -72,7 +72,7 @@ If any of these properties fit your requirements, we recommend using the Event A 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 log frameworks. For example: pattern logging, file +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. From f8fdcebe772d403720dc69ad6239dd33d150ea1a Mon Sep 17 00:00:00 2001 From: Ted Young Date: Fri, 31 May 2024 10:45:18 -0700 Subject: [PATCH 19/19] update toc --- specification/logs/event-api.md | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 46f0e0dc25c..0602db47503 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,17 +9,16 @@ -- [Events API](#events-api) - - [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) +- [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)