diff --git a/CHANGELOG.md b/CHANGELOG.md index 16a02de32b0..2b9053c0b6c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,6 +20,8 @@ release. - Rename Logs API to Logs Bridge API to prevent confusion. ([#3197](https://github.com/open-telemetry/opentelemetry-specification/pull/3197)) +- Move event language from log README to event-api. + ([#3252](https://github.com/open-telemetry/opentelemetry-specification/pull/3252)) ### Resource diff --git a/specification/logs/README.md b/specification/logs/README.md index 6d3bab311b2..8f3124d22da 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -16,7 +16,6 @@ aliases: [/docs/reference/specification/logs/overview] - [Limitations of non-OpenTelemetry Solutions](#limitations-of-non-opentelemetry-solutions) - [OpenTelemetry Solution](#opentelemetry-solution) - [Log Correlation](#log-correlation) -- [Events and Logs](#events-and-logs) - [Legacy and Modern Log Sources](#legacy-and-modern-log-sources) * [System Logs](#system-logs) * [Infrastructure Logs](#infrastructure-logs) @@ -124,11 +123,6 @@ languages have established standards for using particular logging libraries. For example in Java world there are several highly popular and widely used logging libraries, such as Log4j or Logback. -OpenTelemetry defines [events](#events-and-logs) as a type of LogRecord with -specific characteristics. This definition is not ubiquitous across existing -libraries and languages. In some logging libraries, producing events aligned -with the OpenTelemetry event definition is clunky or error-prone. - There are also countless existing prebuilt applications or systems that emit logs in certain formats. Operators of such applications have no or limited control on how the logs are emitted. OpenTelemetry needs to support these logs. @@ -157,11 +151,6 @@ Given the above state of the logging space we took the following approach: features than what is defined in OpenTelemetry. It is NOT a goal of OpenTelemetry to ship a feature-rich logging library. -- OpenTelemetry defines an Events API for [emitting Events](./event-api.md). The Events API - consists of convenience methods which delegate to the Bridge API - for [emitting LogRecords](./bridge-api.md#emit-logrecord). Application developers are - encouraged to call this API directly. - - OpenTelemetry defines an [SDK](./sdk.md) implementation of the [Bridge API](./bridge-api.md), which enables configuration of [processing](./sdk.md#logrecordprocessor) and [exporting](./sdk.md#logrecordexporter) LogRecords. @@ -203,23 +192,6 @@ These 3 correlations can be the foundation of powerful navigational, filtering, querying and analytical capabilities. OpenTelemetry aims to record and collects logs in a manner that enables such correlations. -## Events and Logs - -Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file): - ->In computing, a log file is a file that records either events that occur in an ->operating system or other software runs. - -From OpenTelemetry's perspective LogRecords and Events are both represented -using the same [data model](./data-model.md). - -However, OpenTelemetry does recognize a subtle semantic difference between -LogRecords and Events: Events are LogRecords which have a `name` and `domain`. -Within a particular `domain`, the `name` uniquely defines a particular class or -type of event. Events with the same `domain` / `name` follow the same schema -which assists in analysis in observability platforms. Events are described in -more detail in the [semantic conventions](./semantic_conventions/events.md). - ## Legacy and Modern Log Sources It is important to distinguish several sorts of legacy and modern log sources. @@ -261,7 +233,7 @@ processor. These are logs generated by various infrastructure components, such as Kubernetes events (if you are wondering why events are discussed in the context -of logs see [Events and Logs](#events-and-logs)). Like system logs, the +of logs see [Event API Overview](./event-api.md#overview)). Like system logs, the infrastructure logs lack a request context and can be enriched by the resource context - information about the node, pod, container, etc. diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 5cbc463a135..320eb3ac458 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -146,10 +146,6 @@ Emit a `LogRecord` to the processing pipeline. This function MAY be named `logRecord`. -This API is intended for use -by [Log Appenders](#how-to-create-log4j-style-appender), and SHOULD not be used -by end users or other instrumentation. - **Parameters:** * `logRecord` - the [LogRecord](#logrecord). diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 7d61de2b0fe..972aae938b4 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -9,6 +9,7 @@ +- [Overview](#overview) - [EventLogger](#eventlogger) * [EventLogger Operations](#eventlogger-operations) + [Create EventLogger](#create-eventlogger) @@ -18,9 +19,33 @@ +## Overview + +Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file): + +>In computing, a log file is a file that records either events that occur in an +>operating system or other software runs. + +From OpenTelemetry's perspective LogRecords and Events are both represented +using the same [data model](./data-model.md). + +However, OpenTelemetry does recognize a subtle semantic difference between +LogRecords and Events: Events are LogRecords which have a `name` and `domain`. +Within a particular `domain`, the `name` uniquely defines a particular class or +type of event. Events with the same `domain` / `name` follow the same schema +which assists in analysis in observability platforms. Events are described in +more detail in the [semantic conventions](./semantic_conventions/events.md). + +While the logging space has a diverse legacy with many existing logging +libraries in different languages, there is not ubiquitous alignment with +OpenTelemetry events. In some logging libraries, producing records shaped as +OpenTelemetry events is clunky or error-prone. + The Event API offers convenience methods for [emitting LogRecords](./bridge-api.md#emit-logrecord) that conform to the [semantic conventions for Events](./semantic_conventions/events.md). +Unlike the [Logs Brdige API](./bridge-api.md), application developers and +instrumentation authors are encouraged to call this API directly. ## EventLogger