Clarify parameters for emtting a log record (#3354)

Supersedes #3350

Clarifies the parameters for emitting a log record.

Context was particularly confusing. Context is not a property of the
`LogRecord` data model. Cleans up section of bridge API spec that seems
to suggest that Context is a field of `LogRecord`. Also, clarifies that
Context can be associated with an emitted LogRecord. We have similar
language in the trace API that leaves room for languages to achieve this
in an idiomatic way. See


https://github.com/open-telemetry/opentelemetry-specification/blob/d25734a47e6534a1bc8a52cb2bd51d42e987024b/specification/trace/api.md?plain=1#L365-L370

---------

Co-authored-by: Reiley Yang <[email protected]>

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

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

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.</b>
 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)

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:
 

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).

specification/logs/sdk.md

@@ -121,21 +121,21 @@ 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
 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.
 

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).
 
 <!-- toc -->
@@ -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.
 
 <!-- semconv log-exception -->
 | Attribute  | Type | Description  | Examples  | Requirement Level |

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.
 
 <!-- semconv log-feature_flag -->
 The event name MUST be `feature_flag`.

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):