Merge branch 'main' into cn-deployment-semconv

CHANGELOG.md

@@ -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

specification/logs/README.md

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

specification/logs/api.md → specification/logs/bridge-api.md

@@ -1,4 +1,4 @@
-# Logs API Interface
+# Logs Bridge API
 
 **Status**: [Experimental](../document-status.md)
 
@@ -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

specification/logs/event-api.md

@@ -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
@@ -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.
@@ -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:
 

specification/logs/sdk.md

@@ -1,4 +1,4 @@
-# Logging SDK
+# Logs SDK
 
 **Status**: [Experimental](../document-status.md)
 
@@ -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`.
@@ -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`.
@@ -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)).
@@ -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.
 
@@ -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`

specification/logs/semantic_conventions/events.md

@@ -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 |

specification/logs/semantic_conventions/exceptions.md

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

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](../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,
@@ -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`.

specification/trace/semantic_conventions/exceptions.md

@@ -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

specification/trace/semantic_conventions/rpc.md

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