From 84d02c0f39cb93219508fd8c2c7792f2ec032aa5 Mon Sep 17 00:00:00 2001 From: Yevhenii Solomchenko Date: Tue, 22 Apr 2025 11:00:19 +0200 Subject: [PATCH] Do not discourage direct usage of Logs API (#6675) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #6572 ## What - Update documentation in `log/doc.go`. - Fix naming of the Logs API in several documentation files `(Logs Bridge API -> Logs API)`. --------- Co-authored-by: Robert Pająk Co-authored-by: Damien Mathieu <42@dmathieu.com> --- log/doc.go | 17 +++++++++++++---- log/embedded/embedded.go | 18 +++++++++--------- log/global/log.go | 2 +- log/noop/noop.go | 6 +++--- sdk/log/doc.go | 2 +- 5 files changed, 27 insertions(+), 18 deletions(-) diff --git a/log/doc.go b/log/doc.go index 18cbd1cb2..b7a085c63 100644 --- a/log/doc.go +++ b/log/doc.go @@ -4,10 +4,19 @@ /* Package log provides the OpenTelemetry Logs API. -This package is intended to be used by bridges between existing logging -libraries and OpenTelemetry. Users should not directly use this package as a -logging library. Instead, install one of the bridges listed in the -[registry], and use the associated logging library. +This API is separate from its implementation so the instrumentation built from +it is reusable. See [go.opentelemetry.io/otel/sdk/log] for the official +OpenTelemetry implementation of this API. + +The log package provides the OpenTelemetry Logs API, which serves as a standard +interface for generating and managing log records within the OpenTelemetry ecosystem. +This package allows users to emit LogRecords, enabling structured, context-rich logging +that can be easily integrated with observability tools. It ensures that log data is captured +in a way that is consistent with OpenTelemetry's data model. + +This package can be used to create bridges between existing logging libraries and OpenTelemetry. +Log bridges allow integrating the existing logging setups with OpenTelemetry. +Log bridges can be found in the [registry]. # API Implementations diff --git a/log/embedded/embedded.go b/log/embedded/embedded.go index a3714c4c6..9b401b2b1 100644 --- a/log/embedded/embedded.go +++ b/log/embedded/embedded.go @@ -4,33 +4,33 @@ // Package embedded provides interfaces embedded within the [OpenTelemetry Logs // Bridge API]. // -// Implementers of the [OpenTelemetry Logs Bridge API] can embed the relevant +// Implementers of the [OpenTelemetry Logs API] can embed the relevant // type from this package into their implementation directly. Doing so will // result in a compilation error for users when the [OpenTelemetry Logs Bridge // API] is extended (which is something that can happen without a major version // bump of the API package). // -// [OpenTelemetry Logs Bridge API]: https://pkg.go.dev/go.opentelemetry.io/otel/log +// [OpenTelemetry Logs API]: https://pkg.go.dev/go.opentelemetry.io/otel/log package embedded // import "go.opentelemetry.io/otel/log/embedded" -// LoggerProvider is embedded in the [Logs Bridge API LoggerProvider]. +// LoggerProvider is embedded in the [Logs API LoggerProvider]. // -// Embed this interface in your implementation of the [Logs Bridge API +// Embed this interface in your implementation of the [Logs API // LoggerProvider] if you want users to experience a compilation error, // signaling they need to update to your latest implementation, when the [Logs // Bridge API LoggerProvider] interface is extended (which is something that // can happen without a major version bump of the API package). // -// [Logs Bridge API LoggerProvider]: https://pkg.go.dev/go.opentelemetry.io/otel/log#LoggerProvider +// [Logs API LoggerProvider]: https://pkg.go.dev/go.opentelemetry.io/otel/log#LoggerProvider type LoggerProvider interface{ loggerProvider() } -// Logger is embedded in [Logs Bridge API Logger]. +// Logger is embedded in [Logs API Logger]. // -// Embed this interface in your implementation of the [Logs Bridge API Logger] +// Embed this interface in your implementation of the [Logs API Logger] // if you want users to experience a compilation error, signaling they need to -// update to your latest implementation, when the [Logs Bridge API Logger] +// update to your latest implementation, when the [Logs API Logger] // interface is extended (which is something that can happen without a major // version bump of the API package). // -// [Logs Bridge API Logger]: https://pkg.go.dev/go.opentelemetry.io/otel/log#Logger +// [Logs API Logger]: https://pkg.go.dev/go.opentelemetry.io/otel/log#Logger type Logger interface{ logger() } diff --git a/log/global/log.go b/log/global/log.go index 71ec57798..bfdb18479 100644 --- a/log/global/log.go +++ b/log/global/log.go @@ -3,7 +3,7 @@ /* Package global provides access to a global implementation of the OpenTelemetry -Logs Bridge API. +Logs API. This package is experimental. It will be deprecated and removed when the [log] package becomes stable. Its functionality will be migrated to diff --git a/log/noop/noop.go b/log/noop/noop.go index f45a7c7e0..d779e5d80 100644 --- a/log/noop/noop.go +++ b/log/noop/noop.go @@ -4,14 +4,14 @@ // Package noop provides an implementation of the [OpenTelemetry Logs Bridge // API] that produces no telemetry and minimizes used computation resources. // -// Using this package to implement the [OpenTelemetry Logs Bridge API] will +// Using this package to implement the [OpenTelemetry Logs API] will // effectively disable OpenTelemetry. // // This implementation can be embedded in other implementations of the -// [OpenTelemetry Logs Bridge API]. Doing so will mean the implementation +// [OpenTelemetry Logs API]. Doing so will mean the implementation // defaults to no operation for methods it does not implement. // -// [OpenTelemetry Logs Bridge API]: https://pkg.go.dev/go.opentelemetry.io/otel/log +// [OpenTelemetry Logs API]: https://pkg.go.dev/go.opentelemetry.io/otel/log package noop // import "go.opentelemetry.io/otel/log/noop" import ( diff --git a/sdk/log/doc.go b/sdk/log/doc.go index 6a1f1b0e9..78935de63 100644 --- a/sdk/log/doc.go +++ b/sdk/log/doc.go @@ -31,6 +31,6 @@ is being run on. That way when multiple instances of the code are collected at a single endpoint their origin is decipherable. See [go.opentelemetry.io/otel/log] for more information about -the OpenTelemetry Logs Bridge API. +the OpenTelemetry Logs API. */ package log // import "go.opentelemetry.io/otel/sdk/log"