From f4a9f437d574cb6cec6efc505ff39fad4e05de97 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 27 Aug 2024 12:10:46 -0700 Subject: [PATCH 01/27] Event basics --- text/9999-event-vision.md | 60 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 text/9999-event-vision.md diff --git a/text/9999-event-vision.md b/text/9999-event-vision.md new file mode 100644 index 000000000..675370fa6 --- /dev/null +++ b/text/9999-event-vision.md @@ -0,0 +1,60 @@ +# Event basics + +## Motivation + +The introduction of Events has been contentious, so we want to write down and agree on a few basics. + +### What are events? + +Events are a type of log which has a required event name and a specific structure which is implied by that event name. + +The event name and its implied structure make events much more suitable for observability compared to traditional logs. + +Because of this, the OpenTelemetry project wants to encourage the transition from traditional logs to events. + +### OTLP + +Since events are a type of log, they share the same OTLP data structure and OTLP pipeline. + +### API + +OpenTelemetry should have an Event API. This will help to promote the distinction between events and traditional logs, +and encourage the use of events over traditional logs. + +### Interoperability with traditional logs + +It should be possible to send events from the Event API to a traditional logging library (e.g. Log4j). +This allows users to integrate events from the Event API into an existing (non-OpenTelemetry) log stream. + +Note: If a user chooses to send events from the Event API to a traditional logging library, and they have +also chosen to send the logs from their traditional logging library to the OpenTelemetry Logging SDK, then they should +avoid sending events from the Event API directly to the OpenTelemetry Logging SDK since that would lead to duplicate +capture of events that were sent from the Event API. + +It should be possible to bypass the Event API entirely and emit Events directly via an existing language-specific logging libraries. +This helps reinforce the idea that events are just a specific type of log. + +Note: Because of this, generic event processors should be implemented as Log SDK processors. + +### SDK + +The Event SDK needs to support two destinations for events: + +* OpenTelemetry Logging SDK +* Language-specific logging libraries + +## Trade-offs and mitigations + +TODO + +## Prior art and alternatives + +TODO + +## Open questions + +TODO + +## Future possibilities + +TODO From 5c2ab4bcc9ec614e41af1637eb16653450105549 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 28 Aug 2024 07:45:43 -0700 Subject: [PATCH 02/27] feedback --- text/{9999-event-vision.md => 0265-event-vision.md} | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) rename text/{9999-event-vision.md => 0265-event-vision.md} (80%) diff --git a/text/9999-event-vision.md b/text/0265-event-vision.md similarity index 80% rename from text/9999-event-vision.md rename to text/0265-event-vision.md index 675370fa6..e83083f74 100644 --- a/text/9999-event-vision.md +++ b/text/0265-event-vision.md @@ -36,6 +36,11 @@ This helps reinforce the idea that events are just a specific type of log. Note: Because of this, generic event processors should be implemented as Log SDK processors. +OpenTelemetry will recommend that +[instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library) +use the Event API over emitting event via a traditional logging library in order to give users a simple and consistent +onboarding story that doesn't involve mixing the two approaches. + ### SDK The Event SDK needs to support two destinations for events: @@ -57,4 +62,4 @@ TODO ## Future possibilities -TODO +The Event API will probably need an `IsEnabled` function based on severity level, scope name, and event name. From e9fce2245c1482225684a7cb33579460b6ecf5e0 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 28 Aug 2024 07:55:06 -0700 Subject: [PATCH 03/27] feedback --- text/0265-event-vision.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index e83083f74..d0253a8c1 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -38,9 +38,16 @@ Note: Because of this, generic event processors should be implemented as Log SDK OpenTelemetry will recommend that [instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library) -use the Event API over emitting event via a traditional logging library in order to give users a simple and consistent +use the Event API over emitting events via a traditional logging library in order to give users a simple and consistent onboarding story that doesn't involve mixing the two approaches. +OpenTelemetry will recommend that application developers also use the Event API over emitting events via a traditional +logging library since it avoid accidentally emitting (non-event) traditional logs. + +Also, recommending the Event API over emitting events via a traditional logging library makes for a clearer overall +OpenTelemetry API story - with first class user facing APIs for traces, metrics, and events, +all suitable for using directly in native instrumentation. + ### SDK The Event SDK needs to support two destinations for events: From dbe75df24baff88a1b4d60cd3cd320e5ead5f8a3 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 29 Aug 2024 07:28:52 -0700 Subject: [PATCH 04/27] future possibilities - ergonomics --- text/0265-event-vision.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index d0253a8c1..cbe78ae76 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -70,3 +70,5 @@ TODO ## Future possibilities The Event API will probably need an `IsEnabled` function based on severity level, scope name, and event name. + +Ergonomic improvements to make it more attractive from the perspective of being a replacement for traditional logging APIs. From cbcce6268038b95d3a6f5efe50f707b668a39362 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 29 Aug 2024 07:33:28 -0700 Subject: [PATCH 05/27] traditional logs -> generic logs --- text/0265-event-vision.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index cbe78ae76..6e2510209 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -8,9 +8,9 @@ The introduction of Events has been contentious, so we want to write down and ag Events are a type of log which has a required event name and a specific structure which is implied by that event name. -The event name and its implied structure make events much more suitable for observability compared to traditional logs. +The event name and its implied structure make events much more suitable for observability compared to generic logs. -Because of this, the OpenTelemetry project wants to encourage the transition from traditional logs to events. +Because of this, the OpenTelemetry project wants to encourage the transition from generic logs to events. ### OTLP @@ -18,16 +18,16 @@ Since events are a type of log, they share the same OTLP data structure and OTLP ### API -OpenTelemetry should have an Event API. This will help to promote the distinction between events and traditional logs, -and encourage the use of events over traditional logs. +OpenTelemetry should have an Event API. This will help to promote the distinction between events and generic logs, +and encourage the use of events over generic logs. -### Interoperability with traditional logs +### Interoperability with generic logging libraries -It should be possible to send events from the Event API to a traditional logging library (e.g. Log4j). +It should be possible to send events from the Event API to a generic logging library (e.g. Log4j). This allows users to integrate events from the Event API into an existing (non-OpenTelemetry) log stream. -Note: If a user chooses to send events from the Event API to a traditional logging library, and they have -also chosen to send the logs from their traditional logging library to the OpenTelemetry Logging SDK, then they should +Note: If a user chooses to send events from the Event API to a generic logging library, and they have +also chosen to send the logs from their generic logging library to the OpenTelemetry Logging SDK, then they should avoid sending events from the Event API directly to the OpenTelemetry Logging SDK since that would lead to duplicate capture of events that were sent from the Event API. @@ -38,13 +38,13 @@ Note: Because of this, generic event processors should be implemented as Log SDK OpenTelemetry will recommend that [instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library) -use the Event API over emitting events via a traditional logging library in order to give users a simple and consistent +use the Event API over emitting events via a generic logging library in order to give users a simple and consistent onboarding story that doesn't involve mixing the two approaches. -OpenTelemetry will recommend that application developers also use the Event API over emitting events via a traditional -logging library since it avoid accidentally emitting (non-event) traditional logs. +OpenTelemetry will recommend that application developers also use the Event API over emitting events via a generic +logging library since it avoid accidentally emitting logs which lack an event name or are unstructured. -Also, recommending the Event API over emitting events via a traditional logging library makes for a clearer overall +Also, recommending the Event API over emitting events via a generic logging library makes for a clearer overall OpenTelemetry API story - with first class user facing APIs for traces, metrics, and events, all suitable for using directly in native instrumentation. @@ -71,4 +71,4 @@ TODO The Event API will probably need an `IsEnabled` function based on severity level, scope name, and event name. -Ergonomic improvements to make it more attractive from the perspective of being a replacement for traditional logging APIs. +Ergonomic improvements to make it more attractive from the perspective of being a replacement for generic logging APIs. From 2b2b9d882ce2b9e71b0a2c1c3d5c224c5e5e7e05 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 4 Sep 2024 15:50:54 -0700 Subject: [PATCH 06/27] feedback --- text/0265-event-vision.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 6e2510209..d4910e51f 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -48,6 +48,13 @@ Also, recommending the Event API over emitting events via a generic logging libr OpenTelemetry API story - with first class user facing APIs for traces, metrics, and events, all suitable for using directly in native instrumentation. +### Relationship to Span Events + +Events are intended to replace Span Events in the long-term. +Span Events will be deprecated to signal that users should prefer Events. + +Interoperability between Events and Span Events will be defined in the short-term. + ### SDK The Event SDK needs to support two destinations for events: @@ -65,10 +72,18 @@ TODO ## Open questions -TODO +How do Event bodies interop with generic logging libraries? + +How do Event bodies interop with Span Events? ## Future possibilities The Event API will probably need an `IsEnabled` function based on severity level, scope name, and event name. Ergonomic improvements to make it more attractive from the perspective of being a replacement for generic logging APIs. + +Capturing raw metric events as opposed to aggregating and emitting them as OpenTelemetry Metric data +(e.g. https://github.com/open-telemetry/opentelemetry-specification/issues/617). + +Capturing raw span events as opposed to aggregating and emitting them as OpenTelemetry Span data +(e.g. a [streaming SDK](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-specification+%22streaming+sdk%22&type=issues)). From cf91d7d8f660a1abb9b88ce589447c77b305e85e Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 4 Sep 2024 15:52:37 -0700 Subject: [PATCH 07/27] fix --- text/0265-event-vision.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index d4910e51f..d2e9753b4 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -83,7 +83,7 @@ The Event API will probably need an `IsEnabled` function based on severity level Ergonomic improvements to make it more attractive from the perspective of being a replacement for generic logging APIs. Capturing raw metric events as opposed to aggregating and emitting them as OpenTelemetry Metric data -(e.g. https://github.com/open-telemetry/opentelemetry-specification/issues/617). +(e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). Capturing raw span events as opposed to aggregating and emitting them as OpenTelemetry Span data (e.g. a [streaming SDK](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-specification+%22streaming+sdk%22&type=issues)). From e600aef8fdfb140d32f471b891693afd64744fb5 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 4 Sep 2024 16:56:32 -0700 Subject: [PATCH 08/27] feedback --- text/0265-event-vision.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index d2e9753b4..0637ad903 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -87,3 +87,5 @@ Capturing raw metric events as opposed to aggregating and emitting them as OpenT Capturing raw span events as opposed to aggregating and emitting them as OpenTelemetry Span data (e.g. a [streaming SDK](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-specification+%22streaming+sdk%22&type=issues)). + +Capturing events and computing metrics from them. From 02a695d994d87cf2699ba6171814baca7e921f9e Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 11 Sep 2024 20:39:26 -0700 Subject: [PATCH 09/27] feedback --- text/0265-event-vision.md | 44 +++++++++++++++------------------------ 1 file changed, 17 insertions(+), 27 deletions(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 0637ad903..4fa092380 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -4,47 +4,37 @@ The introduction of Events has been contentious, so we want to write down and agree on a few basics. -### What are events? +### What are OpenTelemetry Events? -Events are a type of log which has a required event name and a specific structure which is implied by that event name. +OpenTelemetry Events are a type of log which have a required event name and a specific structure which is implied by that event name. -The event name and its implied structure make events much more suitable for observability compared to generic logs. - -Because of this, the OpenTelemetry project wants to encourage the transition from generic logs to events. +OpenTelemetry Events are a core concept in OpenTelemetry Semantic Conventions. ### OTLP -Since events are a type of log, they share the same OTLP data structure and OTLP pipeline. +Since events are a type of log, they share the same OTLP data structure and the same OTLP pipeline. ### API -OpenTelemetry should have an Event API. This will help to promote the distinction between events and generic logs, -and encourage the use of events over generic logs. +OpenTelemetry should have a (user-facing) Log API which includes the ability to emit OpenTelemetry Events. ### Interoperability with generic logging libraries -It should be possible to send events from the Event API to a generic logging library (e.g. Log4j). -This allows users to integrate events from the Event API into an existing (non-OpenTelemetry) log stream. - -Note: If a user chooses to send events from the Event API to a generic logging library, and they have -also chosen to send the logs from their generic logging library to the OpenTelemetry Logging SDK, then they should -avoid sending events from the Event API directly to the OpenTelemetry Logging SDK since that would lead to duplicate -capture of events that were sent from the Event API. - -It should be possible to bypass the Event API entirely and emit Events directly via an existing language-specific logging libraries. -This helps reinforce the idea that events are just a specific type of log. +It should be possible to send OpenTelemetry Logs from the OpenTelemetry Log API to a generic logging library (e.g. Log4j). +This allows users to integrate OpenTelemetry Logs into an existing (non-OpenTelemetry) log stream. -Note: Because of this, generic event processors should be implemented as Log SDK processors. +It should be possible to bypass the OpenTelemetry Log API entirely and emit OpenTelemetry Logs (including events) +directly via an existing language-specific logging libraries. OpenTelemetry will recommend that [instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library) -use the Event API over emitting events via a generic logging library in order to give users a simple and consistent +use the OpenTelemetry Log API to emit OpenTelemetry Events over emitting events via a generic logging library in order to give users a simple and consistent onboarding story that doesn't involve mixing the two approaches. -OpenTelemetry will recommend that application developers also use the Event API over emitting events via a generic +OpenTelemetry will recommend that application developers also use the OpenTelemetry Log API to emit OpenTelemetry Events over emitting events via a generic logging library since it avoid accidentally emitting logs which lack an event name or are unstructured. -Also, recommending the Event API over emitting events via a generic logging library makes for a clearer overall +Also, recommending the OpenTelemetry Log API for emitting OpenTelemetry Events over emitting events via a generic logging library makes for a clearer overall OpenTelemetry API story - with first class user facing APIs for traces, metrics, and events, all suitable for using directly in native instrumentation. @@ -57,10 +47,7 @@ Interoperability between Events and Span Events will be defined in the short-ter ### SDK -The Event SDK needs to support two destinations for events: - -* OpenTelemetry Logging SDK -* Language-specific logging libraries +This is the (existing) OpenTelemetry Log SDK. ## Trade-offs and mitigations @@ -72,7 +59,10 @@ TODO ## Open questions -How do Event bodies interop with generic logging libraries? +How to support routing logs from the Log API to a language-specific logging library, +while at the same time routing logs from the language-specific logging library to a OpenTelemetry Logging Exporter. + +How do Log bodies interop with generic logging libraries? How do Event bodies interop with Span Events? From bfc4d5aef9babde97495372f272460f0d24b9b5a Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Wed, 11 Sep 2024 20:44:33 -0700 Subject: [PATCH 10/27] editorial --- text/0265-event-vision.md | 68 ++++++++++++++++++--------------------- 1 file changed, 31 insertions(+), 37 deletions(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 4fa092380..f7ea16918 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -1,53 +1,53 @@ -# Event basics +# Event Basics ## Motivation -The introduction of Events has been contentious, so we want to write down and agree on a few basics. +The introduction of Events has been contentious, so we want to document and agree on a few basics. ### What are OpenTelemetry Events? -OpenTelemetry Events are a type of log which have a required event name and a specific structure which is implied by that event name. +OpenTelemetry Events are a type of OpenTelemetry Log that requires an event name and follows a specific structure implied by that event name. -OpenTelemetry Events are a core concept in OpenTelemetry Semantic Conventions. +They are a core concept in OpenTelemetry Semantic Conventions. ### OTLP -Since events are a type of log, they share the same OTLP data structure and the same OTLP pipeline. +Since OpenTelemetry Events are a type of OpenTelemetry Log, they share the same OTLP log data structure and pipeline. ### API -OpenTelemetry should have a (user-facing) Log API which includes the ability to emit OpenTelemetry Events. +OpenTelemetry should provide a (user-facing) Log API that includes the capability to emit OpenTelemetry Events. -### Interoperability with generic logging libraries +### Interoperability with Generic Logging Libraries -It should be possible to send OpenTelemetry Logs from the OpenTelemetry Log API to a generic logging library (e.g. Log4j). +It should be possible to send OpenTelemetry Logs from the OpenTelemetry Log API to a generic logging library (e.g., Log4j). This allows users to integrate OpenTelemetry Logs into an existing (non-OpenTelemetry) log stream. -It should be possible to bypass the OpenTelemetry Log API entirely and emit OpenTelemetry Logs (including events) -directly via an existing language-specific logging libraries. +It should also be possible to bypass the OpenTelemetry Log API entirely and emit OpenTelemetry Logs (including Events) +directly via existing language-specific logging libraries. OpenTelemetry will recommend that [instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library) -use the OpenTelemetry Log API to emit OpenTelemetry Events over emitting events via a generic logging library in order to give users a simple and consistent -onboarding story that doesn't involve mixing the two approaches. +use the OpenTelemetry Log API to emit OpenTelemetry Events rather than using a generic logging library. This recommendation aims to provide users with a simple and consistent +onboarding experience that avoids mixing approaches. -OpenTelemetry will recommend that application developers also use the OpenTelemetry Log API to emit OpenTelemetry Events over emitting events via a generic -logging library since it avoid accidentally emitting logs which lack an event name or are unstructured. +OpenTelemetry will also recommend that application developers use the OpenTelemetry Log API to emit OpenTelemetry Events instead of using a generic +logging library, as this helps prevent accidentally emitting logs that lack an event name or are unstructured. -Also, recommending the OpenTelemetry Log API for emitting OpenTelemetry Events over emitting events via a generic logging library makes for a clearer overall -OpenTelemetry API story - with first class user facing APIs for traces, metrics, and events, -all suitable for using directly in native instrumentation. +Recommending the OpenTelemetry Log API for emitting OpenTelemetry Events, rather than using a generic logging library, contributes to a clearer overall +OpenTelemetry API story. This ensures a unified approach with first-class user-facing APIs for traces, metrics, and events, +all suitable for direct use in native instrumentation. ### Relationship to Span Events -Events are intended to replace Span Events in the long-term. +Events are intended to replace Span Events in the long term. Span Events will be deprecated to signal that users should prefer Events. -Interoperability between Events and Span Events will be defined in the short-term. +Interoperability between Events and Span Events will be defined in the short term. ### SDK -This is the (existing) OpenTelemetry Log SDK. +This refers to the existing OpenTelemetry Log SDK. ## Trade-offs and mitigations @@ -59,23 +59,17 @@ TODO ## Open questions -How to support routing logs from the Log API to a language-specific logging library, -while at the same time routing logs from the language-specific logging library to a OpenTelemetry Logging Exporter. - -How do Log bodies interop with generic logging libraries? - -How do Event bodies interop with Span Events? +* How to support routing logs from the Log API to a language-specific logging library + while simultaneously routing logs from the language-specific logging library to an OpenTelemetry Logging Exporter? +* How do log bodies interoperate with generic logging libraries? +* How do event bodies interoperate with Span Events? ## Future possibilities -The Event API will probably need an `IsEnabled` function based on severity level, scope name, and event name. - -Ergonomic improvements to make it more attractive from the perspective of being a replacement for generic logging APIs. - -Capturing raw metric events as opposed to aggregating and emitting them as OpenTelemetry Metric data -(e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). - -Capturing raw span events as opposed to aggregating and emitting them as OpenTelemetry Span data -(e.g. a [streaming SDK](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-specification+%22streaming+sdk%22&type=issues)). - -Capturing events and computing metrics from them. +* The Event API will likely need an `IsEnabled` function based on severity level, scope name, and event name. +* Ergonomic improvements to make it more attractive as a replacement for generic logging APIs. +* Capturing raw metric events as opposed to aggregating and emitting them as OpenTelemetry Metric data + (e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). +* Capturing raw span events as opposed to aggregating and emitting them as OpenTelemetry Span data + (e.g. a [streaming SDK](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-specification+%22streaming+sdk%22&type=issues)). +* Capturing events and computing metrics from them. From a36584e39d8cb691f7e35c052b36e87c5e138751 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 08:01:28 -0700 Subject: [PATCH 11/27] feedback --- text/0265-event-vision.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index f7ea16918..1a6c6f0fb 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -24,7 +24,7 @@ It should be possible to send OpenTelemetry Logs from the OpenTelemetry Log API This allows users to integrate OpenTelemetry Logs into an existing (non-OpenTelemetry) log stream. It should also be possible to bypass the OpenTelemetry Log API entirely and emit OpenTelemetry Logs (including Events) -directly via existing language-specific logging libraries. +directly via existing language-specific logging libraries, if that library has the capability to do so. OpenTelemetry will recommend that [instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library) From e203bc85a83e6f9e5fee8374ae9e489df3f94874 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 10:02:18 -0700 Subject: [PATCH 12/27] remove empty sections --- text/0265-event-vision.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 1a6c6f0fb..599a924e8 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -49,14 +49,6 @@ Interoperability between Events and Span Events will be defined in the short ter This refers to the existing OpenTelemetry Log SDK. -## Trade-offs and mitigations - -TODO - -## Prior art and alternatives - -TODO - ## Open questions * How to support routing logs from the Log API to a language-specific logging library From d30f276d915549964116fd90f6d79c6606067244 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 10:03:44 -0700 Subject: [PATCH 13/27] Add more detail --- text/0265-event-vision.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 599a924e8..7cebf84e3 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -54,6 +54,8 @@ This refers to the existing OpenTelemetry Log SDK. * How to support routing logs from the Log API to a language-specific logging library while simultaneously routing logs from the language-specific logging library to an OpenTelemetry Logging Exporter? * How do log bodies interoperate with generic logging libraries? + OpenTelemetry Logs have two places to put structure (attributes and body), while often logging libraries only have one layer of structure, + which makes it non-obvious how to do a two-way mapping between them in this case. * How do event bodies interoperate with Span Events? ## Future possibilities From bba526eccdd9189e6d6908ab5aa36f4002bd916f Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 10:20:06 -0700 Subject: [PATCH 14/27] event api -> log api --- text/0265-event-vision.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 7cebf84e3..4576e84cb 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -60,7 +60,7 @@ This refers to the existing OpenTelemetry Log SDK. ## Future possibilities -* The Event API will likely need an `IsEnabled` function based on severity level, scope name, and event name. +* The Log API may need an `IsEnabled` function based on severity level, scope name, and event name. * Ergonomic improvements to make it more attractive as a replacement for generic logging APIs. * Capturing raw metric events as opposed to aggregating and emitting them as OpenTelemetry Metric data (e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). From 99c4a25f6d1126d73d1e8a7a9acdb700a40af449 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 10:22:08 -0700 Subject: [PATCH 15/27] remove the word replacement --- text/0265-event-vision.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 4576e84cb..2008e6d27 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -61,7 +61,7 @@ This refers to the existing OpenTelemetry Log SDK. ## Future possibilities * The Log API may need an `IsEnabled` function based on severity level, scope name, and event name. -* Ergonomic improvements to make it more attractive as a replacement for generic logging APIs. +* Ergonomic improvements. * Capturing raw metric events as opposed to aggregating and emitting them as OpenTelemetry Metric data (e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). * Capturing raw span events as opposed to aggregating and emitting them as OpenTelemetry Span data From 38f15982466b82e895a8ed922625a3c0d15ed637 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 10:26:47 -0700 Subject: [PATCH 16/27] emitting --- text/0265-event-vision.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 2008e6d27..258ba52af 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -62,8 +62,8 @@ This refers to the existing OpenTelemetry Log SDK. * The Log API may need an `IsEnabled` function based on severity level, scope name, and event name. * Ergonomic improvements. -* Capturing raw metric events as opposed to aggregating and emitting them as OpenTelemetry Metric data +* Emitting raw metric events as opposed to aggregating and emitting them as OpenTelemetry Metric data (e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). -* Capturing raw span events as opposed to aggregating and emitting them as OpenTelemetry Span data +* Emitting raw span events as opposed to aggregating and emitting them as OpenTelemetry Span data (e.g. a [streaming SDK](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-specification+%22streaming+sdk%22&type=issues)). -* Capturing events and computing metrics from them. +* Capturing events and emitting metrics from them. From 7f8a03e34a7398f5d9adff3584bd036fad5d3d4d Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 10:31:12 -0700 Subject: [PATCH 17/27] change generic to other --- text/0265-event-vision.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 258ba52af..fcf53a5b0 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -18,9 +18,9 @@ Since OpenTelemetry Events are a type of OpenTelemetry Log, they share the same OpenTelemetry should provide a (user-facing) Log API that includes the capability to emit OpenTelemetry Events. -### Interoperability with Generic Logging Libraries +### Interoperability with other logging libraries -It should be possible to send OpenTelemetry Logs from the OpenTelemetry Log API to a generic logging library (e.g., Log4j). +It should be possible to send OpenTelemetry Logs from the OpenTelemetry Log API to other logging libraries (e.g., Log4j). This allows users to integrate OpenTelemetry Logs into an existing (non-OpenTelemetry) log stream. It should also be possible to bypass the OpenTelemetry Log API entirely and emit OpenTelemetry Logs (including Events) @@ -28,13 +28,13 @@ directly via existing language-specific logging libraries, if that library has t OpenTelemetry will recommend that [instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library) -use the OpenTelemetry Log API to emit OpenTelemetry Events rather than using a generic logging library. This recommendation aims to provide users with a simple and consistent +use the OpenTelemetry Log API to emit OpenTelemetry Events rather than using other logging libraries to emit OpenTelemetry Events. This recommendation aims to provide users with a simple and consistent onboarding experience that avoids mixing approaches. OpenTelemetry will also recommend that application developers use the OpenTelemetry Log API to emit OpenTelemetry Events instead of using a generic logging library, as this helps prevent accidentally emitting logs that lack an event name or are unstructured. -Recommending the OpenTelemetry Log API for emitting OpenTelemetry Events, rather than using a generic logging library, contributes to a clearer overall +Recommending the OpenTelemetry Log API for emitting OpenTelemetry Events, rather than using other logging libraries, contributes to a clearer overall OpenTelemetry API story. This ensures a unified approach with first-class user-facing APIs for traces, metrics, and events, all suitable for direct use in native instrumentation. @@ -53,7 +53,7 @@ This refers to the existing OpenTelemetry Log SDK. * How to support routing logs from the Log API to a language-specific logging library while simultaneously routing logs from the language-specific logging library to an OpenTelemetry Logging Exporter? -* How do log bodies interoperate with generic logging libraries? +* How do log bodies interoperate with other logging libraries? OpenTelemetry Logs have two places to put structure (attributes and body), while often logging libraries only have one layer of structure, which makes it non-obvious how to do a two-way mapping between them in this case. * How do event bodies interoperate with Span Events? From fb40c48beda6ef1a20902ce70cc80b12b392d74a Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 10:34:36 -0700 Subject: [PATCH 18/27] change generic to other --- text/0265-event-vision.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index fcf53a5b0..6fa0c6bf1 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -31,7 +31,7 @@ OpenTelemetry will recommend that use the OpenTelemetry Log API to emit OpenTelemetry Events rather than using other logging libraries to emit OpenTelemetry Events. This recommendation aims to provide users with a simple and consistent onboarding experience that avoids mixing approaches. -OpenTelemetry will also recommend that application developers use the OpenTelemetry Log API to emit OpenTelemetry Events instead of using a generic +OpenTelemetry will also recommend that application developers use the OpenTelemetry Log API to emit OpenTelemetry Events instead of using another logging library, as this helps prevent accidentally emitting logs that lack an event name or are unstructured. Recommending the OpenTelemetry Log API for emitting OpenTelemetry Events, rather than using other logging libraries, contributes to a clearer overall From 187697aa0a4e7861c2cfe434789b87be11eecbaf Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 10:52:39 -0700 Subject: [PATCH 19/27] move future possibilities to open questions --- text/0265-event-vision.md | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 6fa0c6bf1..6a0b9b8ff 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -57,13 +57,9 @@ This refers to the existing OpenTelemetry Log SDK. OpenTelemetry Logs have two places to put structure (attributes and body), while often logging libraries only have one layer of structure, which makes it non-obvious how to do a two-way mapping between them in this case. * How do event bodies interoperate with Span Events? - -## Future possibilities - -* The Log API may need an `IsEnabled` function based on severity level, scope name, and event name. -* Ergonomic improvements. -* Emitting raw metric events as opposed to aggregating and emitting them as OpenTelemetry Metric data +* Should the Log API have an `IsEnabled` function based on severity level, scope name, and event name? +* What kind of ergonomic improvements to the API make sense now that the OpenTelemetry Log API is user-facing? +* How do OpenTelemetry Events relate to raw metric events? (e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). -* Emitting raw span events as opposed to aggregating and emitting them as OpenTelemetry Span data +* How do OpenTelemetry Events relate to raw span events? (e.g. a [streaming SDK](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-specification+%22streaming+sdk%22&type=issues)). -* Capturing events and emitting metrics from them. From fc0381e8d9710cb7afccff2b7eb81fe921aacee3 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 14:02:27 -0700 Subject: [PATCH 20/27] Add a short section titled 'alternatives' --- text/0265-event-vision.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 6a0b9b8ff..d914c0148 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -49,6 +49,15 @@ Interoperability between Events and Span Events will be defined in the short ter This refers to the existing OpenTelemetry Log SDK. +## Alternatives + +Many alternatives were considered over the past 2+ years. + +These alternatives primarily boil down to differences in naming (e.g. whether to even use the word Event) +and organization (e.g. whether Event API should be something separate from Log API). + +The state of this OTEP represents the option that we think will be the least confusing to the most number of users across the wide range of different language ecosystems that are supported. + ## Open questions * How to support routing logs from the Log API to a language-specific logging library From 6956f82ae4ae331f7c7b0be12701e9e47cee914b Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 15:25:06 -0700 Subject: [PATCH 21/27] document another open question --- text/0265-event-vision.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index d914c0148..6f3a03fef 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -67,7 +67,8 @@ The state of this OTEP represents the option that we think will be the least con which makes it non-obvious how to do a two-way mapping between them in this case. * How do event bodies interoperate with Span Events? * Should the Log API have an `IsEnabled` function based on severity level, scope name, and event name? -* What kind of ergonomic improvements to the API make sense now that the OpenTelemetry Log API is user-facing? +* What kind of capabilities should the OpenTelemetry Log API have now that it is user-facing? +* What kind of ergonomic improvements make sense now that the OpenTelemetry Log API is user-facing? * How do OpenTelemetry Events relate to raw metric events? (e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). * How do OpenTelemetry Events relate to raw span events? From d3a2af574b50111a46ccfdc29697cc35a6b1e114 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 19:45:25 -0700 Subject: [PATCH 22/27] add another open question --- text/0265-event-vision.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 6f3a03fef..d2d23273b 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -73,3 +73,4 @@ The state of this OTEP represents the option that we think will be the least con (e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). * How do OpenTelemetry Events relate to raw span events? (e.g. a [streaming SDK](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-specification+%22streaming+sdk%22&type=issues)). +* Should event name be captured as an attribute or as a top-level field? From 3c34c009e5e1a603600fe29b41b14e3728cad383 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Thu, 12 Sep 2024 19:52:18 -0700 Subject: [PATCH 23/27] add another open question --- text/0265-event-vision.md | 1 + 1 file changed, 1 insertion(+) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index d2d23273b..ce8181bf1 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -74,3 +74,4 @@ The state of this OTEP represents the option that we think will be the least con * How do OpenTelemetry Events relate to raw span events? (e.g. a [streaming SDK](https://github.com/search?q=repo%3Aopen-telemetry%2Fopentelemetry-specification+%22streaming+sdk%22&type=issues)). * Should event name be captured as an attribute or as a top-level field? +* How will Event / Span Event interoperability work in the presence of sampling (e.g. since Span Events are sampled along with Spans)? From f418c4d391f84d95a2ed2fb6e733e322ae2fae7b Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 13 Sep 2024 07:15:10 -0700 Subject: [PATCH 24/27] Log API -> Logs API --- text/0265-event-vision.md | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index ce8181bf1..d226fb996 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -16,25 +16,25 @@ Since OpenTelemetry Events are a type of OpenTelemetry Log, they share the same ### API -OpenTelemetry should provide a (user-facing) Log API that includes the capability to emit OpenTelemetry Events. +OpenTelemetry should provide a (user-facing) Logs API that includes the capability to emit OpenTelemetry Events. ### Interoperability with other logging libraries -It should be possible to send OpenTelemetry Logs from the OpenTelemetry Log API to other logging libraries (e.g., Log4j). +It should be possible to send OpenTelemetry Logs from the OpenTelemetry Logs API to other logging libraries (e.g., Log4j). This allows users to integrate OpenTelemetry Logs into an existing (non-OpenTelemetry) log stream. -It should also be possible to bypass the OpenTelemetry Log API entirely and emit OpenTelemetry Logs (including Events) +It should also be possible to bypass the OpenTelemetry Logs API entirely and emit OpenTelemetry Logs (including Events) directly via existing language-specific logging libraries, if that library has the capability to do so. OpenTelemetry will recommend that [instrumentation libraries](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/glossary.md#instrumentation-library) -use the OpenTelemetry Log API to emit OpenTelemetry Events rather than using other logging libraries to emit OpenTelemetry Events. This recommendation aims to provide users with a simple and consistent +use the OpenTelemetry Logs API to emit OpenTelemetry Events rather than using other logging libraries to emit OpenTelemetry Events. This recommendation aims to provide users with a simple and consistent onboarding experience that avoids mixing approaches. -OpenTelemetry will also recommend that application developers use the OpenTelemetry Log API to emit OpenTelemetry Events instead of using another +OpenTelemetry will also recommend that application developers use the OpenTelemetry Logs API to emit OpenTelemetry Events instead of using another logging library, as this helps prevent accidentally emitting logs that lack an event name or are unstructured. -Recommending the OpenTelemetry Log API for emitting OpenTelemetry Events, rather than using other logging libraries, contributes to a clearer overall +Recommending the OpenTelemetry Logs API for emitting OpenTelemetry Events, rather than using other logging libraries, contributes to a clearer overall OpenTelemetry API story. This ensures a unified approach with first-class user-facing APIs for traces, metrics, and events, all suitable for direct use in native instrumentation. @@ -47,28 +47,28 @@ Interoperability between Events and Span Events will be defined in the short ter ### SDK -This refers to the existing OpenTelemetry Log SDK. +This refers to the existing OpenTelemetry Logs SDK. ## Alternatives Many alternatives were considered over the past 2+ years. These alternatives primarily boil down to differences in naming (e.g. whether to even use the word Event) -and organization (e.g. whether Event API should be something separate from Log API). +and organization (e.g. whether Event API should be something separate from Logs API). The state of this OTEP represents the option that we think will be the least confusing to the most number of users across the wide range of different language ecosystems that are supported. ## Open questions -* How to support routing logs from the Log API to a language-specific logging library +* How to support routing logs from the Logs API to a language-specific logging library while simultaneously routing logs from the language-specific logging library to an OpenTelemetry Logging Exporter? * How do log bodies interoperate with other logging libraries? OpenTelemetry Logs have two places to put structure (attributes and body), while often logging libraries only have one layer of structure, which makes it non-obvious how to do a two-way mapping between them in this case. * How do event bodies interoperate with Span Events? -* Should the Log API have an `IsEnabled` function based on severity level, scope name, and event name? -* What kind of capabilities should the OpenTelemetry Log API have now that it is user-facing? -* What kind of ergonomic improvements make sense now that the OpenTelemetry Log API is user-facing? +* Should the Logs API have an `IsEnabled` function based on severity level, scope name, and event name? +* What kind of capabilities should the OpenTelemetry Logs API have now that it is user-facing? +* What kind of ergonomic improvements make sense now that the OpenTelemetry Logs API is user-facing? * How do OpenTelemetry Events relate to raw metric events? (e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). * How do OpenTelemetry Events relate to raw span events? From 9dc13e11592b7e0aadf28773e9cc173cf9c9a743 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 13 Sep 2024 07:16:27 -0700 Subject: [PATCH 25/27] Refine one of the open questions --- text/0265-event-vision.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index d226fb996..5c85de7ed 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -66,7 +66,7 @@ The state of this OTEP represents the option that we think will be the least con OpenTelemetry Logs have two places to put structure (attributes and body), while often logging libraries only have one layer of structure, which makes it non-obvious how to do a two-way mapping between them in this case. * How do event bodies interoperate with Span Events? -* Should the Logs API have an `IsEnabled` function based on severity level, scope name, and event name? +* Should the Logs API have an `Enabled` function based on severity level and event name? * What kind of capabilities should the OpenTelemetry Logs API have now that it is user-facing? * What kind of ergonomic improvements make sense now that the OpenTelemetry Logs API is user-facing? * How do OpenTelemetry Events relate to raw metric events? From 3c8c0abaff75a46cf58ff1aacea9e0a0092dd1a2 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Fri, 13 Sep 2024 13:19:02 -0700 Subject: [PATCH 26/27] mention bundle size in open questions --- text/0265-event-vision.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 5c85de7ed..270f304c9 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -68,7 +68,9 @@ The state of this OTEP represents the option that we think will be the least con * How do event bodies interoperate with Span Events? * Should the Logs API have an `Enabled` function based on severity level and event name? * What kind of capabilities should the OpenTelemetry Logs API have now that it is user-facing? + (Keeping in mind the bundle size constraints of browsers and possibly other client environments.) * What kind of ergonomic improvements make sense now that the OpenTelemetry Logs API is user-facing? + (Keeping in mind the bundle size constraints of browsers and possibly other client environments.) * How do OpenTelemetry Events relate to raw metric events? (e.g. [opentelemetry-specification/617](https://github.com/open-telemetry/opentelemetry-specification/issues/617)). * How do OpenTelemetry Events relate to raw span events? From e46600340cdd0344dde4387f63219b2c7459f5a7 Mon Sep 17 00:00:00 2001 From: Trask Stalnaker Date: Tue, 17 Sep 2024 09:05:18 -0700 Subject: [PATCH 27/27] should -> SHOULD --- text/0265-event-vision.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0265-event-vision.md b/text/0265-event-vision.md index 270f304c9..b6050e7c9 100644 --- a/text/0265-event-vision.md +++ b/text/0265-event-vision.md @@ -16,14 +16,14 @@ Since OpenTelemetry Events are a type of OpenTelemetry Log, they share the same ### API -OpenTelemetry should provide a (user-facing) Logs API that includes the capability to emit OpenTelemetry Events. +OpenTelemetry SHOULD provide a (user-facing) Logs API that includes the capability to emit OpenTelemetry Events. ### Interoperability with other logging libraries -It should be possible to send OpenTelemetry Logs from the OpenTelemetry Logs API to other logging libraries (e.g., Log4j). +OpenTelemetry SHOULD provide a way to send OpenTelemetry Logs from the OpenTelemetry Logs API to other logging libraries (e.g., Log4j). This allows users to integrate OpenTelemetry Logs into an existing (non-OpenTelemetry) log stream. -It should also be possible to bypass the OpenTelemetry Logs API entirely and emit OpenTelemetry Logs (including Events) +OpenTelemetry SHOULD provide a way to bypass the OpenTelemetry Logs API entirely and emit OpenTelemetry Logs (including Events) directly via existing language-specific logging libraries, if that library has the capability to do so. OpenTelemetry will recommend that