Debian Codegraph @

sdk/log/exporter.go

raw
1 // Copyright The OpenTelemetry Authors
2 // SPDX-License-Identifier: Apache-2.0
3
4 package log // import "go.opentelemetry.io/otel/sdk/log"
5
6 import (
7 "context"
8 "errors"
9 "fmt"
10 "sync"
11 "sync/atomic"
12 "time"
13
14 "go.opentelemetry.io/otel"
15 )
16
17 // Exporter handles the delivery of log records to external receivers.
18 type Exporter interface {
19 // Export transmits log records to a receiver.
20 //
21 // The deadline or cancellation of the passed context must be honored. An
22 // appropriate error should be returned in these situations.
23 //
24 // All retry logic must be contained in this function. The SDK does not
25 // implement any retry logic. All errors returned by this function are
26 // considered unrecoverable and will be reported to a configured error
27 // Handler.
28 //
29 // Implementations must not retain the records slice.
30 //
31 // Before modifying a Record, the implementation must use Record.Clone
32 // to create a copy that shares no state with the original.
33 //
34 // Export should never be called concurrently with other Export calls.
35 // However, it may be called concurrently with other methods.
36 Export(ctx context.Context, records []Record) error
37
38 // Shutdown is called when the SDK shuts down. Any cleanup or release of
39 // resources held by the exporter should be done in this call.
40 //
41 // The deadline or cancellation of the passed context must be honored. An
42 // appropriate error should be returned in these situations.
43 //
44 // After Shutdown is called, calls to Export, Shutdown, or ForceFlush
45 // should perform no operation and return nil error.
46 //
47 // Shutdown may be called concurrently with itself or with other methods.
48 Shutdown(ctx context.Context) error
49
50 // ForceFlush exports log records to the configured Exporter that have not yet
51 // been exported.
52 //
53 // The deadline or cancellation of the passed context must be honored. An
54 // appropriate error should be returned in these situations.
55 //
56 // ForceFlush may be called concurrently with itself or with other methods.
57 ForceFlush(ctx context.Context) error
58 }
59
60 var defaultNoopExporter = &noopExporter{}
61
62 type noopExporter struct{}
63
64 func (noopExporter) Export(context.Context, []Record) error { return nil }
65
66 func (noopExporter) Shutdown(context.Context) error { return nil }
67
68 func (noopExporter) ForceFlush(context.Context) error { return nil }
69
70 // chunkExporter wraps an Exporter's Export method so it is called with
71 // appropriately sized export payloads. Any payload larger than a defined size
72 // is chunked into smaller payloads and exported sequentially.
73 type chunkExporter struct {
74 Exporter
75
76 // size is the maximum batch size exported.
77 size int
78 }
79
80 // newChunkExporter wraps exporter. Calls to the Export will have their records
81 // payload chunked so they do not exceed size. If size is less than or equal
82 // to 0, exporter is returned directly.
83 func newChunkExporter(exporter Exporter, size int) Exporter {
84 if size <= 0 {
85 return exporter
86 }
87 return &chunkExporter{Exporter: exporter, size: size}
88 }
89
90 // Export exports records in chunks no larger than c.size.
91 func (c chunkExporter) Export(ctx context.Context, records []Record) error {
92 n := len(records)
93 for i, j := 0, min(c.size, n); i < n; i, j = i+c.size, min(j+c.size, n) {
94 if err := c.Exporter.Export(ctx, records[i:j]); err != nil {
95 return err
96 }
97 }
98 return nil
99 }
100
101 // timeoutExporter wraps an Exporter and ensures any call to Export will have a
102 // timeout for the context.
103 type timeoutExporter struct {
104 Exporter
105
106 // timeout is the maximum time an export is attempted.
107 timeout time.Duration
108 }
109
110 // newTimeoutExporter wraps exporter with an Exporter that limits the context
111 // lifetime passed to Export to be timeout. If timeout is less than or equal to
112 // zero, exporter will be returned directly.
113 func newTimeoutExporter(exp Exporter, timeout time.Duration) Exporter {
114 if timeout <= 0 {
115 return exp
116 }
117 return &timeoutExporter{Exporter: exp, timeout: timeout}
118 }
119
120 // Export sets the timeout of ctx before calling the Exporter e wraps.
121 func (e *timeoutExporter) Export(ctx context.Context, records []Record) error {
122 // This only used by the batch processor, and it takes processor timeout config.
123 // Thus, the error message points to the processor. So users know they should adjust the processor timeout.
124 ctx, cancel := context.WithTimeoutCause(ctx, e.timeout, errors.New("processor export timeout"))
125 defer cancel()
126 return e.Exporter.Export(ctx, records)
127 }
128
129 // exportSync exports all data from input using exporter in a spawned
130 // goroutine. The returned chan will be closed when the spawned goroutine
131 // completes.
132 func exportSync(input <-chan exportData, exporter Exporter) (done chan struct{}) {
133 done = make(chan struct{})
134 go func() {
135 defer close(done)
136 for data := range input {
137 data.DoExport(exporter.Export)
138 }
139 }()
140 return done
141 }
142
143 // exportData is data related to an export.
144 type exportData struct {
145 ctx context.Context
146 records []Record
147
148 // respCh is the channel any error returned from the export will be sent
149 // on. If this is nil, and the export error is non-nil, the error will
150 // passed to the OTel error handler.
151 respCh chan<- error
152 }
153
154 // DoExport calls exportFn with the data contained in e. The error response
155 // will be returned on e's respCh if not nil. The error will be handled by the
156 // default OTel error handle if it is not nil and respCh is nil or full.
157 func (e exportData) DoExport(exportFn func(context.Context, []Record) error) {
158 if len(e.records) == 0 {
159 e.respond(nil)
160 return
161 }
162
163 e.respond(exportFn(e.ctx, e.records))
164 }
165
166 func (e exportData) respond(err error) {
167 select {
168 case e.respCh <- err:
169 default:
170 // e.respCh is nil or busy, default to otel.Handler.
171 if err != nil {
172 otel.Handle(err)
173 }
174 }
175 }
176
177 // bufferExporter provides asynchronous and synchronous export functionality by
178 // buffering export requests.
179 type bufferExporter struct {
180 Exporter
181
182 input chan exportData
183 inputMu sync.Mutex
184
185 done chan struct{}
186 stopped atomic.Bool
187 }
188
189 // newBufferExporter returns a new bufferExporter that wraps exporter. The
190 // returned bufferExporter will buffer at most size number of export requests.
191 // If size is less than 1, 1 will be used.
192 func newBufferExporter(exporter Exporter, size int) *bufferExporter {
193 if size < 1 {
194 size = 1
195 }
196 input := make(chan exportData, size)
197 return &bufferExporter{
198 Exporter: exporter,
199
200 input: input,
201 done: exportSync(input, exporter),
202 }
203 }
204
205 func (e *bufferExporter) Ready() bool {
206 return len(e.input) != cap(e.input)
207 }
208
209 var errStopped = errors.New("exporter stopped")
210
211 func (e *bufferExporter) enqueue(ctx context.Context, records []Record, rCh chan<- error) error {
212 data := exportData{ctx, records, rCh}
213
214 e.inputMu.Lock()
215 defer e.inputMu.Unlock()
216
217 // Check stopped before enqueueing now that e.inputMu is held. This
218 // prevents sends on a closed chan when Shutdown is called concurrently.
219 if e.stopped.Load() {
220 return errStopped
221 }
222
223 select {
224 case e.input <- data:
225 case <-ctx.Done():
226 return ctx.Err()
227 }
228 return nil
229 }
230
231 // EnqueueExport enqueues an export of records in the context of ctx to be
232 // performed asynchronously. This will return true if the records are
233 // successfully enqueued (or the bufferExporter is shut down), false otherwise.
234 //
235 // The passed records are held after this call returns.
236 func (e *bufferExporter) EnqueueExport(records []Record) bool {
237 if len(records) == 0 {
238 // Nothing to enqueue, do not waste input space.
239 return true
240 }
241
242 data := exportData{ctx: context.Background(), records: records}
243
244 e.inputMu.Lock()
245 defer e.inputMu.Unlock()
246
247 // Check stopped before enqueueing now that e.inputMu is held. This
248 // prevents sends on a closed chan when Shutdown is called concurrently.
249 if e.stopped.Load() {
250 return true
251 }
252
253 select {
254 case e.input <- data:
255 return true
256 default:
257 return false
258 }
259 }
260
261 // Export synchronously exports records in the context of ctx. This will not
262 // return until the export has been completed.
263 func (e *bufferExporter) Export(ctx context.Context, records []Record) error {
264 if len(records) == 0 {
265 return nil
266 }
267
268 resp := make(chan error, 1)
269 err := e.enqueue(ctx, records, resp)
270 if err != nil {
271 if errors.Is(err, errStopped) {
272 return nil
273 }
274 return fmt.Errorf("%w: dropping %d records", err, len(records))
275 }
276
277 select {
278 case err := <-resp:
279 return err
280 case <-ctx.Done():
281 return ctx.Err()
282 }
283 }
284
285 // ForceFlush flushes buffered exports. Any existing exports that is buffered
286 // is flushed before this returns.
287 func (e *bufferExporter) ForceFlush(ctx context.Context) error {
288 resp := make(chan error, 1)
289 err := e.enqueue(ctx, nil, resp)
290 if err != nil {
291 if errors.Is(err, errStopped) {
292 return nil
293 }
294 return err
295 }
296
297 select {
298 case <-resp:
299 case <-ctx.Done():
300 return ctx.Err()
301 }
302 return e.Exporter.ForceFlush(ctx)
303 }
304
305 // Shutdown shuts down e.
306 //
307 // Any buffered exports are flushed before this returns.
308 //
309 // All calls to EnqueueExport or Exporter will return nil without any export
310 // after this is called.
311 func (e *bufferExporter) Shutdown(ctx context.Context) error {
312 if e.stopped.Swap(true) {
313 return nil
314 }
315 e.inputMu.Lock()
316 defer e.inputMu.Unlock()
317
318 // No more sends will be made.
319 close(e.input)
320 select {
321 case <-e.done:
322 case <-ctx.Done():
323 return errors.Join(ctx.Err(), e.Exporter.Shutdown(ctx))
324 }
325 return e.Exporter.Shutdown(ctx)
326 }