-
Notifications
You must be signed in to change notification settings - Fork 894
/
bridge-api.md
186 lines (130 loc) · 7.05 KB
/
bridge-api.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
# Logs Bridge API
**Status**: [Stable](../document-status.md), except where otherwise specified
<details>
<summary>Table of Contents</summary>
<!-- Re-generate TOC with `markdown-toc --no-first-h1 -i` -->
<!-- toc -->
- [LoggerProvider](#loggerprovider)
* [LoggerProvider operations](#loggerprovider-operations)
+ [Get a Logger](#get-a-logger)
- [Logger](#logger)
* [Logger operations](#logger-operations)
+ [Emit a LogRecord](#emit-a-logrecord)
+ [Enabled](#enabled)
- [Optional and required parameters](#optional-and-required-parameters)
- [Concurrency requirements](#concurrency-requirements)
- [Artifact Naming](#artifact-naming)
- [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),
which use this API to bridge between existing logging libraries and the
OpenTelemetry log data model.</b>
The Logs Bridge API consist 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
[LogRecords](./data-model.md#log-and-event-record-definition).
```mermaid
graph TD
A[LoggerProvider] -->|Get| B(Logger)
B -->|Emit| C(LogRecord)
```
## LoggerProvider
`Logger`s can be accessed with a `LoggerProvider`.
Normally, the `LoggerProvider` is expected to be accessed from a central place.
Thus, the API SHOULD provide a way to set/register and access a global default
`LoggerProvider`.
### LoggerProvider operations
The `LoggerProvider` MUST provide the following functions:
* Get a `Logger`
#### Get a Logger
This API MUST accept the following [instrumentation scope](data-model.md#field-instrumentationscope)
parameters:
* `name`: This name uniquely identifies the [instrumentation scope](../glossary.md#instrumentation-scope),
such as the [instrumentation library](../glossary.md#instrumentation-library)
(e.g. `io.opentelemetry.contrib.mongodb`), package, module or class name.
If an application or library has built-in OpenTelemetry instrumentation, both
[Instrumented library](../glossary.md#instrumented-library) and
[Instrumentation library](../glossary.md#instrumentation-library) may refer to
the same library. In that scenario, the `name` denotes a module name or component
name within that library or application.
For log sources which define a logger name (e.g. Java
[Logger Name](https://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)))
the Logger Name should be recorded as the instrumentation scope name.
* `version` (optional): Specifies the version of the instrumentation scope if
the scope has a version (e.g. a library version). Example value: 1.0.0.
* `schema_url` (optional): Specifies the Schema URL that should be recorded in
the emitted telemetry.
* `attributes` (optional): Specifies the instrumentation scope attributes to
associate with emitted telemetry. This API MUST be structured to accept a
variable number of attributes, including none.
`Logger`s are identified by `name`, `version`, and `schema_url` fields. When more
than one `Logger` of the same `name`, `version`, and `schema_url` is created, it
is unspecified whether or under which conditions the same or different `Logger`
instances are returned. It is a user error to create Loggers with different
`attributes` but the same identity.
The term *identical* applied to `Logger`s describes instances where all
identifying fields are equal. The term *distinct* applied to `Logger`s describes
instances where at least one identifying field has a different value.
The effect of associating a Schema URL with a `Logger` MUST be that the telemetry
emitted using the `Logger` will be associated with the Schema URL, provided that
the emitted data format is capable of representing such association.
## Logger
The `Logger` is responsible for emitting `LogRecord`s.
### Logger operations
The `Logger` MUST provide functions to:
- [Emit a `LogRecord`](#emit-a-logrecord)
The `Logger` SHOULD provide functions to:
- [Report if `Logger` is `Enabled`](#enabled)
#### Emit a LogRecord
The effect of calling this API is to emit a `LogRecord` to the processing pipeline.
The API MUST accept the following parameters:
- [Timestamp](./data-model.md#field-timestamp)
- [Observed Timestamp](./data-model.md#field-observedtimestamp). If unspecified the
implementation SHOULD set it equal to the current time.
- The [Context](../context/README.md) associated with the `LogRecord`. The API
MAY implicitly use the current Context as a default
behavior.
- [Severity Number](./data-model.md#field-severitynumber)
- [Severity Text](./data-model.md#field-severitytext)
- [Body](./data-model.md#field-body)
- [Attributes](./data-model.md#field-attributes)
All parameters are optional.
#### Enabled
**Status**: [Development](../document-status.md)
To help users avoid performing computationally expensive operations when
generating a `LogRecord`, a `Logger` SHOULD provide this `Enabled` API.
There are currently no required parameters for this API. Parameters can be
added in the future, therefore, the API MUST be structured in a way for
parameters to be added.
This API MUST return a language idiomatic boolean type. A returned value of
`true` means the `Logger` is enabled for the provided arguments, and a returned
value of `false` means the `Logger` is disabled for the provided arguments.
The returned value is not always static, it can change over time. The API
SHOULD be documented that instrumentation authors needs to call this API each
time they [emit a LogRecord](#emit-a-logrecord) to ensure they have the most
up-to-date response.
## Optional and required parameters
The operations defined include various parameters, some of which are marked
optional. Parameters not marked optional are required.
For each optional parameter, the API MUST be structured to accept it, but MUST
NOT obligate a user to provide it.
For each required parameter, the API MUST be structured to obligate a user to
provide it.
## Concurrency requirements
For languages which support concurrent execution the Logs Bridge 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
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.
## References
- [OTEP0150 Logging Library SDK Prototype Specification](https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md)