Debian Codegraph @

log/doc.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 /*
5 Package log provides the OpenTelemetry Logs API.
6
7 This API is separate from its implementation so the instrumentation built from
8 it is reusable. See [go.opentelemetry.io/otel/sdk/log] for the official
9 OpenTelemetry implementation of this API.
10
11 The log package provides the OpenTelemetry Logs API, which serves as a standard
12 interface for generating and managing log records within the OpenTelemetry ecosystem.
13 This package allows users to emit LogRecords, enabling structured, context-rich logging
14 that can be easily integrated with observability tools. It ensures that log data is captured
15 in a way that is consistent with OpenTelemetry's data model.
16
17 This package can be used to create bridges between existing logging libraries and OpenTelemetry.
18 Log bridges allow integrating the existing logging setups with OpenTelemetry.
19 Log bridges can be found in the [registry].
20
21 # API Implementations
22
23 This package does not conform to the standard Go versioning policy, all of its
24 interfaces may have methods added to them without a package major version bump.
25 This non-standard API evolution could surprise an uninformed implementation
26 author. They could unknowingly build their implementation in a way that would
27 result in a runtime panic for their users that update to the new API.
28
29 The API is designed to help inform an instrumentation author about this
30 non-standard API evolution. It requires them to choose a default behavior for
31 unimplemented interface methods. There are three behavior choices they can
32 make:
33
34 - Compilation failure
35 - Panic
36 - Default to another implementation
37
38 All interfaces in this API embed a corresponding interface from
39 [go.opentelemetry.io/otel/log/embedded]. If an author wants the default
40 behavior of their implementations to be a compilation failure, signaling to
41 their users they need to update to the latest version of that implementation,
42 they need to embed the corresponding interface from
43 [go.opentelemetry.io/otel/log/embedded] in their implementation. For example,
44
45 import "go.opentelemetry.io/otel/log/embedded"
46
47 type LoggerProvider struct {
48 embedded.LoggerProvider
49 // ...
50 }
51
52 If an author wants the default behavior of their implementations to a panic,
53 they need to embed the API interface directly.
54
55 import "go.opentelemetry.io/otel/log"
56
57 type LoggerProvider struct {
58 log.LoggerProvider
59 // ...
60 }
61
62 This is not a recommended behavior as it could lead to publishing packages that
63 contain runtime panics when users update other package that use newer versions
64 of [go.opentelemetry.io/otel/log].
65
66 Finally, an author can embed another implementation in theirs. The embedded
67 implementation will be used for methods not defined by the author. For example,
68 an author who wants to default to silently dropping the call can use
69 [go.opentelemetry.io/otel/log/noop]:
70
71 import "go.opentelemetry.io/otel/log/noop"
72
73 type LoggerProvider struct {
74 noop.LoggerProvider
75 // ...
76 }
77
78 It is strongly recommended that authors only embed
79 go.opentelemetry.io/otel/log/noop if they choose this default behavior. That
80 implementation is the only one OpenTelemetry authors can guarantee will fully
81 implement all the API interfaces when a user updates their API.
82
83 [registry]: https://opentelemetry.io/ecosystem/registry/?language=go&component=log-bridge
84 */
85 package log // import "go.opentelemetry.io/otel/log"