diff --git a/log/doc.go b/log/doc.go index 18cbd1cb2e5..b7a085c63d7 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 a3714c4c69a..9b401b2b17f 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 71ec577986d..bfdb1847908 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 f45a7c7e0b3..d779e5d80d3 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 6a1f1b0e915..78935de6368 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"