Skip to content

Commit

Permalink
Merge branch 'main' into cn-deployment-semconv
Browse files Browse the repository at this point in the history
  • Loading branch information
thisthat authored Feb 18, 2023
2 parents b40d9ad + 8946dfc commit 24a637e
Show file tree
Hide file tree
Showing 11 changed files with 38 additions and 35 deletions.
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,9 @@ release.

### Logs

- Rename Logs API to Logs Bridge API to prevent confusion.
([#3197](https://github.com/open-telemetry/opentelemetry-specification/pull/3197))

### Resource

### Semantic Conventions
Expand Down
18 changes: 9 additions & 9 deletions specification/logs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,21 +148,21 @@ Given the above state of the logging space we took the following approach:
OpenTelemetry log data model. OpenTelemetry Collector can read such logs and
translate them to OpenTelemetry log data model.

- OpenTelemetry defines an API
for [emitting LogRecords](./api.md#emit-logrecord). Application developers are
- 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](./api.md#how-to-create-log4j-style-appender), which use
to build [Appenders](./bridge-api.md#how-to-create-log4j-style-appender), 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
OpenTelemetry to ship a feature-rich logging library.

- OpenTelemetry defines an API for [emitting Events](./event-api.md). The API
consists of convenience methods which delegate to the API
for [emitting LogRecords](./api.md#emit-logrecord). Application developers are
- 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 [API](./api.md),
- 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.

Expand Down Expand Up @@ -388,10 +388,10 @@ as parsers, log tailing and rotation. It also enables the possibility to send
logs directly to the logging backend without using a log collection agent.

To facilitate both approaches described above OpenTelemetry provides
an [API](./api.md) and [SDK](./sdk.md), which can be used together with existing
a [Bridge API](./bridge-api.md) and [SDK](./sdk.md), which can be used together with existing
logging libraries to automatically inject the request context in the emitted logs,
and provide an easy way to send the logs via OTLP. Instead of
modifying each logging statement, [Appenders](./api.md#how-to-create-log4j-style-appender)
modifying each logging statement, [Appenders](./bridge-api.md#how-to-create-log4j-style-appender)
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
Expand Down
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Logs API Interface
# Logs Bridge API

**Status**: [Experimental](../document-status.md)

Expand Down Expand Up @@ -31,7 +31,7 @@ to build [Appenders](#how-to-create-log4j-style-appender), which use
this API to bridge between existing logging libraries and the OpenTelemetry log
data model.</b>

The Logs API consist of these main classes:
The Logs Bridge API consist of these main classes:

* LoggerProvider is the entry point of the API. It provides access to Loggers.
* Logger is the class responsible for
Expand Down
8 changes: 4 additions & 4 deletions specification/logs/event-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
</details>

The Event API offers convenience methods
for [emitting LogRecords](./api.md#emit-logrecord) that conform
for [emitting LogRecords](./bridge-api.md#emit-logrecord) that conform
to the [semantic conventions for Events](./semantic_conventions/events.md).

## EventLogger
Expand All @@ -38,7 +38,7 @@ on `EventLogger`.

**Parameters:**

* `logger` - the delegate [Logger](./api.md#logger) used to emit `Events`
* `logger` - the delegate [Logger](./bridge-api.md#logger) used to emit `Events`
as `LogRecords`.
* `event_domain` - the domain of emitted events, used to set the `event.domain`
attribute.
Expand All @@ -55,11 +55,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](./api.md#logrecord) representing the Event.
* `logRecord` - the [LogRecord](./bridge-api.md#logrecord) representing the Event.

**Implementation Requirements:**

The implementation MUST [emit](./api.md#emit-logrecord) the `logRecord` to
The implementation MUST [emit](./bridge-api.md#emit-logrecord) the `logRecord` to
the `logger` specified when [creating the EventLogger](#create-eventlogger)
after making the following changes:

Expand Down
Binary file modified specification/logs/img/application-api-sdk.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
14 changes: 7 additions & 7 deletions specification/logs/sdk.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Logging SDK
# Logs SDK

**Status**: [Experimental](../document-status.md)

Expand Down Expand Up @@ -42,7 +42,7 @@ the `LogRecords` produced by any `Logger` from the `LoggerProvider`.
### Logger Creation

New `Logger` instances are always created through a `LoggerProvider`
(see [API](api.md)). The `name`, `version` (optional), and `attributes` (optional)
(see [Bridge API](bridge-api.md)). The `name`, `version` (optional), and `attributes` (optional)
supplied to the `LoggerProvider` must be used to create
an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which
is stored on the created `Logger`.
Expand Down Expand Up @@ -101,13 +101,13 @@ registered [LogRecordProcessors](#logrecordprocessor).

## Additional LogRecord interfaces

In addition to the [API-level definition for LogRecord](api.md#logrecord), the
In addition to the [API-level definition for LogRecord](bridge-api.md#logrecord), 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](api.md#logrecord). It MUST also be able to
information added to the [LogRecord](bridge-api.md#logrecord). 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`.
Expand All @@ -123,7 +123,7 @@ value type.
### ReadWriteLogRecord

A function receiving this as an argument MUST be able to write to the
full [LogRecord](api.md#logrecord) and additionally MUST be able to retrieve all
full [LogRecord](bridge-api.md#logrecord) and additionally MUST be able to retrieve all
information
that was added to the `LogRecord` (as with
[ReadableLogRecord](#readablelogrecord)).
Expand Down Expand Up @@ -197,7 +197,7 @@ components in the SDK:

#### OnEmit

`OnEmit` is called when a `LogRecord` is [emitted](api.md#emit-logrecord). This
`OnEmit` is called when a `LogRecord` is [emitted](bridge-api.md#emit-logrecord). This
method is called synchronously on the thread that emitted the `LogRecord`,
therefore it SHOULD NOT block or throw exceptions.

Expand All @@ -207,7 +207,7 @@ therefore it SHOULD NOT block or throw exceptions.
emitted `LogRecord`.
* `context` - the `Context` that the SDK determined (the explicitly
passed `Context`, the current `Context`, or an empty `Context` if
the [Logger](./api.md#get-a-logger) was obtained
the [Logger](./bridge-api.md#get-a-logger) was obtained
with `include_trace_context=false`)

**Returns:** `Void`
Expand Down
4 changes: 2 additions & 2 deletions specification/logs/semantic_conventions/events.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,8 @@ possible that the existing system does not have the equivalent of a name or
requires multiple fields to identify the structure of the events. In such cases,
OpenTelemetry recommends using a combination of one or more fields as the name
such that the name identifies the event structurally. It is also recommended that
the event names have low-cardinality, so care must be taken to not use fields
that identify the instance of the Event and not the class of Events.
the event names have low-cardinality, so care must be taken to use fields
that identify the class of Events but not the instance of the Event.

<!-- semconv event -->
| Attribute | Type | Description | Examples | Requirement Level |
Expand Down
8 changes: 4 additions & 4 deletions specification/logs/semantic_conventions/exceptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
**Status**: [Experimental](../../document-status.md)

This document defines semantic conventions for recording exceptions on
[logs](../api.md#emit-logrecord) and [events](../event-api.md#emit-event)
emitted through the [Logger API](../api.md#logger).
[logs](../bridge-api.md#emit-logrecord) and [events](../event-api.md#emit-event)
emitted through the [Logger API](../bridge-api.md#logger).

<!-- toc -->

Expand All @@ -17,7 +17,7 @@ emitted through the [Logger API](../api.md#logger).
## Recording an Exception

Exceptions SHOULD be recorded as attributes on the
[LogRecord](../api.md#logrecord) passed to the [Logger](../api.md#logger) emit
[LogRecord](../bridge-api.md#logrecord) passed to the [Logger](../bridge-api.md#logger) emit
operations. Exceptions MAY be recorded on "logs" or "events" depending on the
context.

Expand All @@ -29,7 +29,7 @@ the language runtime.
## Attributes

The table below indicates which attributes should be added to the
[LogRecord](../api.md#logrecord) and their types.
[LogRecord](../bridge-api.md#logrecord) and their types.

<!-- semconv log-exception -->
| Attribute | Type | Description | Examples | Requirement Level |
Expand Down
8 changes: 4 additions & 4 deletions specification/logs/semantic_conventions/feature-flags.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
**Status**: [Experimental](../../document-status.md)

This document defines semantic conventions for recording feature flag evaluations as
a [log record](../api.md#logrecord) emitted through the
[Logger API](../api.md#emit-logrecord).
a [log record](../bridge-api.md#logrecord) emitted through the
[Logger API](../bridge-api.md#emit-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,
Expand All @@ -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](../api.md#logrecord) passed to the [Logger](../api.md#logger) emit
[LogRecord](../bridge-api.md#logrecord) 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](../api.md#logrecord) and their types.
[LogRecord](../bridge-api.md#logrecord) and their types.

<!-- semconv log-feature_flag -->
The event name MUST be `feature_flag`.
Expand Down
2 changes: 1 addition & 1 deletion specification/trace/semantic_conventions/exceptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,5 +99,5 @@ grained information from a stacktrace, if necessary.
[js-stacktrace]: https://v8.dev/docs/stack-trace-api
[ruby-full-message]: https://ruby-doc.org/core-2.7.1/Exception.html#method-i-full_message
[csharp-stacktrace]: https://docs.microsoft.com/en-us/dotnet/api/system.exception.tostring
[go-stacktrace]: https://golang.org/pkg/runtime/debug/#Stack
[go-stacktrace]: https://pkg.go.dev/runtime/debug#Stack
[telemetry-sdk-resource]: ../../resource/semantic_conventions/README.md#telemetry-sdk
4 changes: 2 additions & 2 deletions specification/trace/semantic_conventions/rpc.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,8 +207,8 @@ The [Span Status](../api.md#set-status) MUST be left unset for an `OK` gRPC stat

| Attribute | Type | Description | Examples | Requirement Level |
|-------------------------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|-------------------|
| `rpc.grpc.request.metadata.<key>` | string[] | gRPC request metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Optional |
| `rpc.grpc.response.metadata.<key>` | string[] | gRPC response metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Optional |
| `rpc.grpc.request.metadata.<key>` | string[] | gRPC request metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.request.metadata.my_custom_metadata_attribute=["1.2.3.4", "1.2.3.5"]` | Optional |
| `rpc.grpc.response.metadata.<key>` | string[] | gRPC response metadata, `<key>` being the normalized gRPC Metadata key (lowercase, with `-` characters replaced by `_`), the value being the metadata values. [1] | `rpc.grpc.response.metadata.my_custom_metadata_attribute=["attribute_value"]` | Optional |

**[1]:** Instrumentations SHOULD require an explicit configuration of which metadata values are to be captured.
Including all request/response metadata values can be a security risk - explicit configuration helps avoid leaking sensitive information.
Expand Down

0 comments on commit 24a637e

Please sign in to comment.