Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify that ReadableLogRecord and ReadWriteLogRecord can be represented using a single type #3898

Merged
merged 14 commits into from
Mar 21, 2024
68 changes: 32 additions & 36 deletions specification/logs/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,16 @@

<!-- toc -->

- [Definitions Used in this Document](#definitions-used-in-this-document)
* [ReadableLogRecord](#readablelogrecord)
* [ReadWriteLogRecord](#readwritelogrecord)
- [LoggerProvider](#loggerprovider)
* [LoggerProvider Creation](#loggerprovider-creation)
* [Logger Creation](#logger-creation)
* [Configuration](#configuration)
* [Shutdown](#shutdown)
* [ForceFlush](#forceflush)
- [Logger](#logger)
- [Additional LogRecord interfaces](#additional-logrecord-interfaces)
* [ReadableLogRecord](#readablelogrecord)
* [ReadWriteLogRecord](#readwritelogrecord)
- [LogRecord Limits](#logrecord-limits)
- [LogRecordProcessor](#logrecordprocessor)
* [LogRecordProcessor operations](#logrecordprocessor-operations)
Expand All @@ -43,6 +43,35 @@ API that provides users with this functionally.

All language implementations of OpenTelemetry MUST provide an SDK.

## Definitions Used in this Document

In this document we refer to `ReadableLogRecord` and `ReadWriteLogRecord` defined as follows.

### ReadableLogRecord

A function receiving this as an argument MUST be able to access all the
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`.

The [trace context fields](./data-model.md#trace-context-fields) MUST be populated from
the resolved `Context` (either the explicitly passed `Context` or the
current `Context`) when [emitted](./bridge-api.md#emit-a-logrecord).

Counts for attributes due to collection limits MUST be available for exporters
to report as described in
the [transformation to non-OTLP formats](../common/mapping-to-non-otlp.md#dropped-attributes-count)
specification.

### ReadWriteLogRecord

A function receiving this as an argument MUST be able to write to the
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)).

## LoggerProvider

A `LoggerProvider` MUST provide a way to allow a [Resource](../resource/sdk.md)
Expand Down Expand Up @@ -127,39 +156,6 @@ registered [LogRecordProcessors](#logrecordprocessor).
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 [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](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`.

The [trace context fields](./data-model.md#trace-context-fields) MUST be populated from
the resolved `Context` (either the explicitly passed `Context` or the
current `Context`) when [emitted](./bridge-api.md#emit-a-logrecord).

Counts for attributes due to collection limits MUST be available for exporters
to report as described in
the [transformation to non-OTLP formats](../common/mapping-to-non-otlp.md#dropped-attributes-count)
specification.

Note: Typically this will be implemented with a new interface or (immutable)
value type.
pellared marked this conversation as resolved.
Show resolved Hide resolved

### ReadWriteLogRecord

A function receiving this as an argument MUST be able to write to the
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)).

## LogRecord Limits

`LogRecord` attributes MUST adhere to
Expand Down
Loading