Logs API to be user-facing

CHANGELOG.md

@@ -33,6 +33,8 @@ release.
   ([#4203](https://github.com/open-telemetry/opentelemetry-specification/pull/4203))
 - Make all fields as identifying for Logger. Previously attributes were omitted from being identifying.
   ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161))
+- Make Logs Bridge API as the Logs API and do not discourage from direct usage.
+  ([#4225](https://github.com/open-telemetry/opentelemetry-specification/pull/4225))
 
 ### Events
 

specification/README.md

@@ -28,13 +28,13 @@ path_base_for_github_subdir:
   - [Baggage](baggage/api.md)
   - [Tracing](trace/api.md)
   - [Metrics](metrics/api.md)
-  - [Logs](logs/README.md)
-    - [Bridge API](logs/bridge-api.md)
-    - [Event API](logs/event-api.md)
+  - [Logs](logs/api.md)
+    - [Events](logs/event-api.md)
 - SDK Specification
   - [Tracing](trace/sdk.md)
   - [Metrics](metrics/sdk.md)
   - [Logs](logs/sdk.md)
+    - [Events](logs/event-sdk.md)
   - [Resource](resource/sdk.md)
   - [Configuration](configuration/README.md)
 - Data Specification

specification/glossary.md

@@ -192,7 +192,7 @@ concept the attributes of the scope cannot change at runtime.
 
 This refers to the `name` and (optional) `version` arguments specified when
 creating a new `Tracer` or `Meter` (see
-[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider))/[Obtaining a Logger](logs/bridge-api.md#loggerprovider).
+[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider))/[Obtaining a Logger](logs/api.md#loggerprovider).
 The name/version pair identifies the
 [Instrumentation Scope](#instrumentation-scope), for example the
 [Instrumentation Library](#instrumentation-library) or another unit of
@@ -250,7 +250,7 @@ recommended to call it out specifically.
 ### Log Appender / Bridge
 
 A log appender or bridge is a component which bridges logs from an existing log
-API into OpenTelemetry using the [Log Bridge API](./logs/bridge-api.md). The
+API into OpenTelemetry using the [Logs (Bridge) API](./logs/api.md). The
 terms "log bridge" and "log appender" are used interchangeably, reflecting that
 these components bridge data into OpenTelemetry, but are often called appenders
 in the logging domain.

specification/logs/README.md

@@ -140,16 +140,18 @@ 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 a Logs Bridge API
-  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
-  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 [SDK](./sdk.md) implementation of the [Bridge API](./bridge-api.md),
+- OpenTelemetry defines a Logs API for [emitting LogRecords](./api.md#emit-a-logrecord).
+  It is provided for library authors to build [log appenders](../glossary.md#log-appender--bridge),
+  which use the API to bridge between existing logging libraries and the
+  OpenTelemetry log data model.
+  The [API](./api.md) is also provided for instrumentation libraries to emit log
+  records following semantic conventions (also known as OpenTelemetry Events).
+  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. However, nothing prevents application
+  developers to use it directly.
+
+- OpenTelemetry defines an [SDK](./sdk.md) implementation of the [API](./api.md),
   which enables configuration of [processing](./sdk.md#logrecordprocessor)
   and [exporting](./sdk.md#logrecordexporter) LogRecords.
 
@@ -230,10 +232,9 @@ processor.
 ### Infrastructure Logs
 
 These are logs generated by various infrastructure components, such as
-Kubernetes events (if you are wondering why events are discussed in the context
-of logs see [Event API Data model](./event-api.md#event-data-model)). Like system logs, the
-infrastructure logs lack a trace context and can be enriched by the resource
-context - information about the node, pod, container, etc.
+Kubernetes events. Like system logs, the infrastructure logs lack a trace
+context and can be enriched by the resource context - information about
+the node, pod, container, etc.
 
 OpenTelemetry Collector or other agents can be used to query logs from most
 common infrastructure controllers.
@@ -359,7 +360,7 @@ 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
-a [Bridge API](./bridge-api.md) and [SDK](./sdk.md), which can be used together with existing
+a [API](./api.md) and [SDK](./sdk.md), which can be used together with existing
 logging libraries to automatically inject the trace context in the emitted logs,
 and provide an easy way to send the logs via OTLP. Instead of
 modifying each logging statement, [log appenders](../glossary.md#log-appender--bridge)
@@ -444,10 +445,9 @@ standard output.
 
 ## Specifications
 
-* [Logs Bridge API](./bridge-api.md)
+* [Logs API](./api.md)
 * [Logs SDK](./sdk.md)
 * [Logs Data Model](./data-model.md)
-* [Event API](./event-api.md)
 * [Trace Context in non-OTLP Log Formats](../compatibility/logging_trace_context.md)
 
 ## References

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

@@ -1,4 +1,4 @@
-# Logs Bridge API
+# Logs API
 
 **Status**: [Stable](../document-status.md), except where otherwise specified
 
@@ -9,6 +9,7 @@
 
 <!-- toc -->
 
+- [Overview](#overview)
 - [LoggerProvider](#loggerprovider)
   * [LoggerProvider operations](#loggerprovider-operations)
     + [Get a Logger](#get-a-logger)
@@ -18,21 +19,32 @@
     + [Enabled](#enabled)
 - [Optional and required parameters](#optional-and-required-parameters)
 - [Concurrency requirements](#concurrency-requirements)
-- [Artifact Naming](#artifact-naming)
+- [Convenience](#convenience)
+- [Logs Bridge API](#logs-bridge-api)
 - [References](#references)
 
 <!-- tocstop -->
 
 </details>
 
-<b>Note: this document defines a log *backend* API. The API is not intended
-to be called by application developers directly. It is provided for logging
-library authors to build
-[log appenders](./supplementary-guidelines.md#how-to-create-a-log4j-log-appender),
+## Overview
+
+This document defines a log API.
+
+The API serves following use cases.
+
+It is provided for logging library authors to build
+[log appenders/bridges](./supplementary-guidelines.md#how-to-create-a-log4j-log-appender),
 which use this API to bridge between existing logging libraries and the
-OpenTelemetry log data model.</b>
+OpenTelemetry log data model. See also: [Logs Bridge API](#logs-bridge-api)
+
+It is provided for OpenTelemetry (instrumentation) libraries to emit
+[OpenTelemetry Events](data-model.md#events).
 
-The Logs Bridge API consist of these main components:
+It is provided for application developers to emit structured log records
+(including OpenTelemetry Events).
+
+The Logs API consists of these main components:
 
 * [LoggerProvider](#loggerprovider) is the entry point of the API. It provides access to `Logger`s.
 * [Logger](#logger) is responsible for emitting logs as
@@ -167,21 +179,23 @@ provide it.
 
 ## Concurrency requirements
 
-For languages which support concurrent execution the Logs Bridge APIs provide
+For languages which support concurrent execution the Logs APIs provide
 specific guarantees and safeties.
 
 **LoggerProvider** - all methods are safe to be called concurrently.
 
 **Logger** - all methods are safe to be called concurrently.
 
-## Artifact Naming
+## Convenience
+
+Languages MAY provide additional ergonomics and convinence APIs. For instance,
+a language may provide an `Info` method for `Logger` which emits a log record
+with `SeverityNumber` equal to `9`.
+
+## Logs Bridge API
 
-The Logs Bridge API is not intended to be called by application developers
-directly, and SHOULD include documentation that discourages direct use. However,
-in the event OpenTelemetry were to add a user facing API, the Logs Bridge API would
-be a natural starting point. Therefore, Log Bridge API artifact, package, and class
-names MUST NOT include the terms "bridge", "appender", or any other qualifier
-that would prevent evolution into a user facing API.
+Languages MAY provide a separate Logs Bridge API if they need different
+ergonomics for consumers that are building log appenders/bridges.
 
 ## References
 

specification/logs/data-model.md

@@ -33,6 +33,7 @@
   * [Field: `InstrumentationScope`](#field-instrumentationscope)
   * [Field: `Attributes`](#field-attributes)
     + [Errors and Exceptions](#errors-and-exceptions)
+  * [Events](#events)
 - [Example Log Records](#example-log-records)
 - [Example Mappings](#example-mappings)
 - [References](#references)
@@ -466,6 +467,28 @@ of the record.
 If included, they MUST follow the OpenTelemetry
 [semantic conventions for exception-related attributes](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/exceptions/exceptions-logs.md).
 
+### Events
+
+Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file):
+
+>In computing, a log file is a file that records either events that occur in an
+>operating system or other software runs.
+
+From OpenTelemetry's perspective LogRecords and Events are both represented
+using the same [data model](./data-model.md). An Event is a specialized type
+of LogRecord, not a separate concept.
+
+Events are OpenTelemetry's standardized semantic formatting for LogRecords.
+Beyond the structure provided by the LogRecord data model, it is helpful for
+logs to have a common format within that structure. When OpenTelemetry
+instrumentation emits logs, those logs SHOULD be formatted as Events. All
+semantic conventions defined for logs MUST be formatted as Events.
+
+The Event format is as follows. All Events have a
+[`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md),
+and all Events with the same `event.name` MUST conform to the same schema for
+both their `Attributes` and their `Body`.
+
 ## Example Log Records
 
 For example log records see

specification/logs/event-api.md

@@ -9,7 +9,6 @@
 
 <!-- toc -->
 
-- [Event Data model](#event-data-model)
 - [Event API use cases](#event-api-use-cases)
 - [EventLoggerProvider](#eventloggerprovider)
   * [EventLoggerProvider operations](#eventloggerprovider-operations)
@@ -30,35 +29,13 @@ The Event API consists of these main components:
   provides access to `EventLogger`s.
 * [EventLogger](#eventlogger) is the component responsible for emitting events.
 
-## Event Data model
-
-Wikipedia’s [definition of log file](https://en.wikipedia.org/wiki/Log_file):
-
->In computing, a log file is a file that records either events that occur in an
->operating system or other software runs.
-
-From OpenTelemetry's perspective LogRecords and Events are both represented
-using the same [data model](./data-model.md). An Event is a specialized type
-of LogRecord, not a separate concept.
-
-Events are OpenTelemetry's standardized semantic formatting for LogRecords.
-Beyond the structure provided by the LogRecord data model, it is helpful for
-logs to have a common format within that structure. When OpenTelemetry
-instrumentation emits logs, those logs SHOULD be formatted as Events. All
-semantic conventions defined for logs MUST be formatted as Events.
-
-The Event format is as follows. All Events have a
-[`event.name` attribute](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/events.md),
-and all Events with the same `event.name` MUST conform to the same schema for
-both their `Attributes` and their `Body`.
-
 ## Event API use cases
 
-The Events API was designed to allow shared libraries to emit high quality
-logs without needing to depend on a third party logger. Unlike the
-[Logs Bridge API](./bridge-api.md), instrumentation authors and application
-developers are encouraged to call this API directly. It is appropriate to
-use the Event API when these properties fit your requirements:
+The Events API was designed to allow shared libraries to emit
+[events](data-model.md#events) without needing to depend on a third party logger.
+Instrumentation authors and application developers are encouraged can call this
+API directly. It is appropriate to use the Event API when these properties fit
+your requirements:
 
 * Logging from a shared library that must run in many applications.
 * A semantic convention needs to be defined. We do not define semantic
@@ -80,6 +57,8 @@ If a logging library is capable of creating logs which correctly map
 to the Event data model, logging in this manner is also an acceptable way to
 create Events.
 
+Emitting events via [Logs API](api.md) is also acceptable.
+
 ## EventLoggerProvider
 
 `EventLogger`s can be accessed with a `EventLoggerProvider`.

specification/logs/event-sdk.md

@@ -27,8 +27,6 @@ OpenTelemetry API to actually produce telemetry. The OpenTelemetry SDK
 (henceforth referred to as the SDK) is an implementation of the OpenTelemetry
 API that provides users with this functionally.
 
-All implementations of the OpenTelemetry API MUST provide an SDK.
-
 ## Overview
 
 From OpenTelemetry's perspective LogRecords and Events are both represented
@@ -81,7 +79,7 @@ Emit a `LogRecord` representing an `Event`.
 **Implementation Requirements:**
 
 The implementation MUST use the parameters
-to [emit a logRecord](./bridge-api.md#emit-a-logrecord) as follows:
+to [emit a logRecord](./api.md#emit-a-logrecord) as follows:
 
 * The `Name` MUST be used to set
   the `event.name` [Attribute](./data-model.md#field-attributes). If
@@ -94,10 +92,10 @@ to [emit a logRecord](./bridge-api.md#emit-a-logrecord) as follows:
   the [Timestamp](./data-model.md#field-timestamp). If not provided, `Timestamp`
   MUST be set to the current time when [emit](#emit-event) was called.
 * The [Observed Timestamp](./data-model.md#field-observedtimestamp) MUST not be
-  set. (NOTE: [emit a logRecord](./bridge-api.md#emit-a-logrecord) will
+  set. (NOTE: [emit a logRecord](./api.md#emit-a-logrecord) will
   set `ObservedTimestamp` to the current time when unset.)
 * If provided by the user, the `Context` MUST be used to set
-  the [Context](./bridge-api.md#emit-a-logrecord). If not provided, `Context`
+  the [Context](./api.md#emit-a-logrecord). If not provided, `Context`
   MUST be set to the current Context.
 * If provided by the user, the `SeverityNumber` MUST be used to set
   the [Severity Number](./data-model.md#field-severitynumber) when emitting the

specification/logs/noop.md

@@ -2,7 +2,7 @@
 linkTitle: No-Op
 --->
 
-# Logs Bridge API No-Op Implementation
+# Logs API No-Op Implementation
 
 **Status**: [Stable](../document-status.md)
 
@@ -23,12 +23,12 @@ linkTitle: No-Op
 Users of OpenTelemetry need a way to disable the API from actually
 performing any operations. The No-Op OpenTelemetry API implementation
 (henceforth referred to as the No-Op) provides users with this
-functionally. It implements the [OpenTelemetry Logs Bridge API](./bridge-api.md)
+functionally. It implements the [OpenTelemetry Logs API](./api.md)
 so that no telemetry is produced and computation resources are minimized.
 
 All language implementations of OpenTelemetry MUST provide a No-Op.
 
-The [Logs Bridge API](./bridge-api.md) defines components with various operations.
+The [Logs API](./api.md) defines components with various operations.
 All No-Op components MUST NOT hold configuration or operational state. All No-op
 operations MUST accept all defined parameters, MUST NOT validate any arguments
 received, and MUST NOT return any non-empty error or log any message.
@@ -42,7 +42,7 @@ provide the same `LoggerProvider` instances to all creation requests.
 
 ### Logger Creation
 
-New `Logger` instances are always created with a [LoggerProvider](./bridge-api.md#loggerprovider).
+New `Logger` instances are always created with a [LoggerProvider](./api.md#loggerprovider).
 Therefore, `LoggerProvider` MUST allow for the creation of `Logger`s.
 All `Logger`s created MUST be an instance of the [No-Op Logger](#logger).
 
@@ -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-a-logrecord).
+for [emitting LogRecords](./api.md#emit-a-logrecord).