diff --git a/CHANGELOG.md b/CHANGELOG.md index a1d6b71d4af..a6590c00b68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,6 +15,9 @@ release. ### Logs +- Clarify parameters for emitting a log record. + ([#3345](https://github.com/open-telemetry/opentelemetry-specification/pull/3354)) + ### Resource ### Semantic Conventions diff --git a/specification/logs/README.md b/specification/logs/README.md index bbab7393330..e2afcfdd159 100644 --- a/specification/logs/README.md +++ b/specification/logs/README.md @@ -137,7 +137,7 @@ Given the above state of the logging space we took the following approach: translate them to OpenTelemetry log data model. - OpenTelemetry defines a Logs Bridge API - for [emitting LogRecords](./bridge-api.md#emit-logrecord). Application developers are + for [emitting LogRecords](./bridge-api.md#emit-a-logrecord). Application developers are NOT encouraged to call this API directly. It is provided for library authors to build [log appender](../glossary.md#log-appender--bridge), which use the API to bridge between existing logging libraries and the OpenTelemetry log diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 25c3a210e07..2a51cedf69b 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -14,8 +14,7 @@ + [Get a Logger](#get-a-logger) - [Logger](#logger) * [Logger operations](#logger-operations) - + [Emit LogRecord](#emit-logrecord) -- [LogRecord](#logrecord) + + [Emit a LogRecord](#emit-a-logrecord) - [Optional and required parameters](#optional-and-required-parameters) - [Concurrency requirements](#concurrency-requirements) - [Artifact Naming](#artifact-naming) @@ -37,7 +36,8 @@ data model. The Logs Bridge API consist of these main classes: * [LoggerProvider](#loggerprovider) is the entry point of the API. It provides access to `Logger`s. -* [Logger](#logger) is the class responsible for emitting logs as [LogRecords](#logrecord). +* [Logger](#logger) is the class responsible for emitting logs as + [LogRecords](./data-model.md#log-and-event-record-definition). ```mermaid graph TD @@ -111,27 +111,21 @@ The `Logger` is responsible for emitting `LogRecord`s. The `Logger` MUST provide functions to: -#### Emit LogRecord +- Emit a `LogRecord` -Emit a `LogRecord` to the processing pipeline. +#### Emit a LogRecord -This function MAY be named `logRecord`. +`LogRecord`s encapsulate the fields identified in the [`LogRecord` +data model](data-model.md#log-and-event-record-definition) and are emitted to the processing pipeline using +this API. -**Parameters:** - -* `logRecord` - the [LogRecord](#logrecord) to emit. - -## LogRecord - -The API emits [LogRecords](#emit-logrecord) using the `LogRecord` [data model](data-model.md). - -A function receiving this as an argument MUST be able to set the following -parameters: +The API MUST accept the following parameters: - [Timestamp](./data-model.md#field-timestamp) - [Observed Timestamp](./data-model.md#field-observedtimestamp) -- [Context](../context/README.md) that contains the - [TraceContext](./data-model.md#trace-context-fields) +- The [Context](../context/README.md) associated with the `LogRecord`. The API + MAY implicitly use the current Context as a default + behavior. - [Severity Number](./data-model.md#field-severitynumber) - [Severity Text](./data-model.md#field-severitytext) - [Body](./data-model.md#field-body) @@ -181,7 +175,7 @@ approaches. The log appender implementation will typically acquire a [Logger](#logger) from the global [LoggerProvider](#loggerprovider) at startup time, then -call [Emit LogRecord](#emit-logrecord) for `LogRecord`s received from the +call [Emit LogRecord](#emit-a-logrecord) for `LogRecord`s received from the application. [Implicit Context Injection](#implicit-context-injection) diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index f9075d16104..78facadb2a3 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -42,7 +42,7 @@ 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 +for [emitting LogRecords](./bridge-api.md#emit-a-logrecord) that conform to the [semantic conventions for Events](./semantic_conventions/events.md). Unlike the [Logs Bridge API](./bridge-api.md), application developers and instrumentation authors are encouraged to call this API directly. @@ -80,11 +80,11 @@ This function MAY be named `logEvent`. attribute with the key `event.name`. Care MUST be taken by the implementation to not override or delete this attribute while the Event is emitted to preserve its identity. -* `logRecord` - the [LogRecord](./bridge-api.md#logrecord) representing the Event. +* `logRecord` - the [LogRecord](./data-model.md#log-and-event-record-definition) representing the Event. **Implementation Requirements:** -The implementation MUST [emit](./bridge-api.md#emit-logrecord) the `logRecord` to +The implementation MUST [emit](./bridge-api.md#emit-a-logrecord) the `logRecord` to the `logger` specified when [creating the EventLogger](#create-eventlogger) after making the following changes: diff --git a/specification/logs/noop.md b/specification/logs/noop.md index 896e11721f3..34c538c628e 100644 --- a/specification/logs/noop.md +++ b/specification/logs/noop.md @@ -54,4 +54,4 @@ return the same `Logger` instances to all creation requests. ### Emit LogRecord The No-Op `Logger` MUST allow -for [emitting LogRecords](./bridge-api.md#emit-logrecord). +for [emitting LogRecords](./bridge-api.md#emit-a-logrecord). diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 05d82d68e47..08300accdd3 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -121,7 +121,7 @@ registered [LogRecordProcessors](#logrecordprocessor). ## Logger If a `Logger` was obtained with `include_trace_context=true`, the `LogRecord`s -it [emits](./bridge-api.md#emit-logrecord) MUST automatically include the Trace +it [emits](./bridge-api.md#emit-a-logrecord) MUST automatically include the Trace Context from the active Context, if Context has not been explicitly set. Note that `Logger`s should not be responsible for configuration. This should be @@ -129,13 +129,13 @@ the responsibility of the `LoggerProvider` instead. ## Additional LogRecord interfaces -In addition to the [API-level definition for LogRecord](bridge-api.md#logrecord), the +In addition to the [definition for LogRecord](data-model.md#log-and-event-record-definition), the following `LogRecord`-like interfaces are defined in the SDK: ### ReadableLogRecord A function receiving this as an argument MUST be able to access all the -information added to the [LogRecord](bridge-api.md#logrecord). It MUST also be able to +information added to the [LogRecord](data-model.md#log-and-event-record-definition). It MUST also be able to access the [Instrumentation Scope](./data-model.md#field-instrumentationscope) and [Resource](./data-model.md#field-resource) information (implicitly) associated with the `LogRecord`. @@ -151,7 +151,7 @@ value type. ### ReadWriteLogRecord A function receiving this as an argument MUST be able to write to the -full [LogRecord](bridge-api.md#logrecord) and additionally MUST be able to retrieve all +full [LogRecord](data-model.md#log-and-event-record-definition) and additionally MUST be able to retrieve all information that was added to the `LogRecord` (as with [ReadableLogRecord](#readablelogrecord)). @@ -226,7 +226,7 @@ components in the SDK: #### OnEmit -`OnEmit` is called when a `LogRecord` is [emitted](bridge-api.md#emit-logrecord). This +`OnEmit` is called when a `LogRecord` is [emitted](bridge-api.md#emit-a-logrecord). This method is called synchronously on the thread that emitted the `LogRecord`, therefore it SHOULD NOT block or throw exceptions. diff --git a/specification/logs/semantic_conventions/exceptions.md b/specification/logs/semantic_conventions/exceptions.md index 63890971010..f40d44cb89d 100644 --- a/specification/logs/semantic_conventions/exceptions.md +++ b/specification/logs/semantic_conventions/exceptions.md @@ -3,7 +3,7 @@ **Status**: [Experimental](../../document-status.md) This document defines semantic conventions for recording exceptions on -[logs](../bridge-api.md#emit-logrecord) and [events](../event-api.md#emit-event) +[logs](../bridge-api.md#emit-a-logrecord) and [events](../event-api.md#emit-event) emitted through the [Logger API](../bridge-api.md#logger). @@ -17,7 +17,7 @@ emitted through the [Logger API](../bridge-api.md#logger). ## Recording an Exception Exceptions SHOULD be recorded as attributes on the -[LogRecord](../bridge-api.md#logrecord) passed to the [Logger](../bridge-api.md#logger) emit +[LogRecord](../data-model.md#log-and-event-record-definition) passed to the [Logger](../bridge-api.md#logger) emit operations. Exceptions MAY be recorded on "logs" or "events" depending on the context. @@ -29,7 +29,7 @@ the language runtime. ## Attributes The table below indicates which attributes should be added to the -[LogRecord](../bridge-api.md#logrecord) and their types. +[LogRecord](../data-model.md#log-and-event-record-definition) and their types. | Attribute | Type | Description | Examples | Requirement Level | diff --git a/specification/logs/semantic_conventions/feature-flags.md b/specification/logs/semantic_conventions/feature-flags.md index 763821ada99..25c62b58e9c 100644 --- a/specification/logs/semantic_conventions/feature-flags.md +++ b/specification/logs/semantic_conventions/feature-flags.md @@ -3,8 +3,8 @@ **Status**: [Experimental](../../document-status.md) This document defines semantic conventions for recording feature flag evaluations as -a [log record](../bridge-api.md#logrecord) emitted through the -[Logger API](../bridge-api.md#emit-logrecord). +a [log record](../data-model.md#log-and-event-record-definition) emitted through the +[Logger API](../bridge-api.md#emit-a-logrecord). This is useful when a flag is evaluated outside of a transaction context such as when the application loads or on a timer. To record a flag evaluation as a part of a transaction context, @@ -24,14 +24,14 @@ section of the trace semantic convention for feature flag evaluations. ## Recording an Evaluation Feature flag evaluations SHOULD be recorded as attributes on the -[LogRecord](../bridge-api.md#logrecord) passed to the [Logger](../bridge-api.md#logger) emit +[LogRecord](../data-model.md#log-and-event-record-definition) passed to the [Logger](../bridge-api.md#logger) emit operations. Evaluations MAY be recorded on "logs" or "events" depending on the context. ## Attributes The table below indicates which attributes should be added to the -[LogRecord](../bridge-api.md#logrecord) and their types. +[LogRecord](../data-model.md#log-and-event-record-definition) and their types. The event name MUST be `feature_flag`. diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index a0a5b8da7b1..f56162543e5 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -204,7 +204,7 @@ Semantic Conventions defines the set of fields in the OTLP data model: both synchronous and asynchronous instruments. - These exist on `NumberDataPoint`, `HistogramDataPoint`, `ExponentialHistogramDataPoint` and `SummaryDataPoint`. -- [Log Records](logs/bridge-api.md#logrecord) +- [Log Records](logs/data-model.md#log-and-event-record-definition) - The attribute keys provided on the LogRecord - For log records that are [Log Events](logs/event-api.md) - The following data provided to [emit event](logs/event-api.md#emit-event):