From 2dfd9c77163259cc7f61eeea1afcc12fd725f4c0 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Wed, 22 Mar 2023 14:59:07 -0500 Subject: [PATCH 1/3] Add log appender / bridge to glossary --- CHANGELOG.md | 2 ++ specification/glossary.md | 9 +++++++++ specification/logs/README.md | 12 ++++++------ specification/logs/bridge-api.md | 13 +++++++------ 4 files changed, 24 insertions(+), 12 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 46e16f9e0d7..dca932b2566 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,8 @@ release. - Update log readme "request context" to "trace context". ([#3332](https://github.com/open-telemetry/opentelemetry-specification/pull/3332)) +- Add log appender / bridge to glossary. + ([#3335](https://github.com/open-telemetry/opentelemetry-specification/pull/3335)) ### Resource diff --git a/specification/glossary.md b/specification/glossary.md index f464a5efec2..8263a4658b3 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -38,6 +38,7 @@ Some other fundamental terms are documented in the [overview document](overview. * [Log Attributes](#log-attributes) * [Structured Logs](#structured-logs) * [Flat File Logs](#flat-file-logs) + * [Log Appender / Bridge](#log-appender--bridge) @@ -234,3 +235,11 @@ records are possible too). There is no common industry agreement whether logs written to text files in more structured formats (e.g. JSON files) are considered Flat File Logs or not. Where such distinction is important it is 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 +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 c510b028b00..76cf63e2470 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -145,7 +145,7 @@ Given the above state of the logging space we took the following approach: - OpenTelemetry defines a Logs Bridge API for [emitting LogRecords](./bridge-api.md#emit-logrecord). Application developers are NOT encouraged to call this API directly. It is provided for library authors - to build [Appenders](./bridge-api.md#how-to-create-log4j-style-appender), which use + to build [log appender](../glossary.md#log-appender--bridge), which use the API to bridge between existing logging libraries and the OpenTelemetry log data model. Existing logging libraries generally provide a much richer set of features than what is defined in OpenTelemetry. It is NOT a goal of @@ -298,8 +298,8 @@ collected from all applications that can be instrumented in this manner. Some logging libraries are designed to be extended in this manner relatively easily. There is no need to actually modify the libraries, instead we can -implement "appender" or "exporter" components for such libraries and implement -the additional LogRecord enrichment in these components. +implement "log appender" or "log bridge" components for such libraries and +implement the additional LogRecord enrichment in these components. There are typically 2 ways to collect logs from these applications. @@ -363,7 +363,7 @@ 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 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, [Appenders](./bridge-api.md#how-to-create-log4j-style-appender) +modifying each logging statement, [log appenders](../glossary.md#log-appender--bridge) use the API to bridge logs from existing logging libraries to the OpenTelemetry data model, where the SDK controls how the logs are processed and exported. Application developers only need to configure the Appender and SDK at @@ -374,8 +374,8 @@ application startup. These are greenfield developments. OpenTelemetry provides recommendations and best practices about how to emit logs (along with traces and metrics) from these applications. For applicable languages and frameworks the auto-instrumentation -or simple configuration of a logging library to use an OpenTelemetry appender or -extension will still be the easiest way to emit context-enriched logs. As +or simple configuration of a logging library to use an OpenTelemetry log appender +will still be the easiest way to emit context-enriched logs. As already described earlier we provide extensions to some popular logging libraries languages to support the manual instrumentation cases. The extensions will support the inclusion of the trace context in the logs and allow to send diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index dbbdaaf9791..2284f09befa 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -17,7 +17,7 @@ + [Emit LogRecord](#emit-logrecord) - [LogRecord](#logrecord) - [Usage](#usage) - * [How to Create Log4J Style Appender](#how-to-create-log4j-style-appender) + * [How to Create Log4J Log Appender](#how-to-create-log4j-log-appender) * [Implicit Context Injection](#implicit-context-injection) * [Explicit Context Injection](#explicit-context-injection) @@ -27,7 +27,7 @@ Note: this document defines a log *backend* API. The API is not intended to be called by application developers directly. It is provided for logging library authors -to build [Appenders](#how-to-create-log4j-style-appender), which use +to build [log appenders](#how-to-create-log4j-log-appender), which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. @@ -164,15 +164,16 @@ fields: ## Usage -### How to Create Log4J Style Appender +### How to Create Log4J Log Appender -An Appender implementation can be used to allow emitting logs via +A [log appender](../glossary.md#log-appender--bridge) implementation can be used +to allow emitting logs via OpenTelemetry [LogRecordExporters](sdk.md#logrecordexporter). This approach is typically used for applications which are fine with changing the log transport and is [one of the supported](README.md#direct-to-collector) log collection approaches. -The Appender implementation will typically acquire a [Logger](#logger) from the +The log appender implementation will typically acquire a [Logger](#logger) from the global [LoggerProvider](#loggerprovider) at startup time, then construct `LogRecord`s for each log received from the application, and then call [Emit LogRecord](#emit-logrecord). @@ -190,7 +191,7 @@ This same approach can be also used for example for: there is no implicit Context in Go it is not possible to get and use the active Span. -Appenders can be created in OpenTelemetry language libraries by OpenTelemetry +Log appenders can be created in OpenTelemetry language libraries by OpenTelemetry maintainers, or by 3rd parties for any logging library that supports a similar extension mechanism. This specification recommends each OpenTelemetry language library to include out-of-the-box Appender implementation for at least one From 3dc0e77c042a3550340dc69e30f27a4b2165553d Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Mon, 27 Mar 2023 14:12:36 -0500 Subject: [PATCH 2/3] PR feedback --- specification/logs/bridge-api.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 2284f09befa..39cdf35c12d 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -17,7 +17,7 @@ + [Emit LogRecord](#emit-logrecord) - [LogRecord](#logrecord) - [Usage](#usage) - * [How to Create Log4J Log Appender](#how-to-create-log4j-log-appender) + * [How to Create Log4J Log Appender](#how-to-create-a-log4j-log-appender) * [Implicit Context Injection](#implicit-context-injection) * [Explicit Context Injection](#explicit-context-injection) @@ -27,7 +27,7 @@ Note: this document defines a log *backend* API. The API is not intended to be called by application developers directly. It is provided for logging library authors -to build [log appenders](#how-to-create-log4j-log-appender), which use +to build [log appenders](#how-to-create-a-log4j-log-appender), which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. @@ -164,7 +164,7 @@ fields: ## Usage -### How to Create Log4J Log Appender +### How to Create a Log4J Log Appender A [log appender](../glossary.md#log-appender--bridge) implementation can be used to allow emitting logs via From b4e7399d67746c1adc4c1ad2c7a882d85d45d963 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Mon, 27 Mar 2023 17:07:58 -0500 Subject: [PATCH 3/3] Markdown toc --- specification/logs/bridge-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index f22bf6f2be8..a72fa0cf8f9 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -19,7 +19,7 @@ - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [Usage](#usage) - * [How to Create Log4J Log Appender](#how-to-create-a-log4j-log-appender) + * [How to Create a Log4J Log Appender](#how-to-create-a-log4j-log-appender) * [Implicit Context Injection](#implicit-context-injection) * [Explicit Context Injection](#explicit-context-injection) @@ -170,7 +170,7 @@ and is [one of the supported](README.md#direct-to-collector) log collection approaches. The log appender implementation will typically acquire a [Logger](#logger) from the -global [LoggerProvider](#loggerprovider) at startup time, then +global [LoggerProvider](#loggerprovider) at startup time, then call [Emit LogRecord](#emit-logrecord) for `LogRecord`s received from the application.