Debian Codegraph @

sdk/log/processor.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
9 "go.opentelemetry.io/otel/log"
10 "go.opentelemetry.io/otel/sdk/instrumentation"
11 )
12
13 // Processor handles the processing of log records.
14 //
15 // Any of the Processor's methods may be called concurrently with itself
16 // or with other methods. It is the responsibility of the Processor to manage
17 // this concurrency.
18 type Processor interface {
19 // Enabled reports whether the Processor will process for the given context
20 // and param.
21 //
22 // The param contains a subset of the information that will be available
23 // in the Record passed to OnEmit, as defined by EnabledParameters.
24 // A field being unset in param does not imply the corresponding field
25 // in the Record passed to OnEmit will be unset. For example, a log bridge
26 // may be unable to populate all fields in EnabledParameters even though
27 // they are present on the final Record.
28 //
29 // The returned value will be true when the Processor will process for the
30 // provided context and param, and will be false if the Processor will not
31 // process.
32 //
33 // Implementations that need additional information beyond what is provided
34 // in param should treat the decision as indeterminate and default to
35 // returning true, unless they have a specific reason to return false
36 // (for example, to meet performance or correctness constraints).
37 //
38 // Processor implementations are expected to re-evaluate the [Record] passed
39 // to OnEmit. It is not expected that the caller to OnEmit will
40 // use the result from Enabled prior to calling OnEmit.
41 //
42 // The SDK's Logger.Enabled returns false if all the registered processors
43 // return false. Otherwise, it returns true.
44 //
45 // Implementations of this method need to be safe for a user to call
46 // concurrently.
47 Enabled(ctx context.Context, param EnabledParameters) bool
48
49 // OnEmit is called when a Record is emitted.
50 //
51 // OnEmit will be called independent of Enabled. Implementations need to
52 // validate the arguments themselves before processing.
53 //
54 // Implementations should not stop processing a Record solely because the
55 // context is canceled.
56 //
57 // Any retry or recovery logic needed by the Processor must be handled
58 // inside this function. The SDK does not implement any retry logic.
59 // Errors returned by this function are treated as unrecoverable by the SDK
60 // and will be reported to a configured error Handler.
61 //
62 // The SDK invokes the processors sequentially in the same order as
63 // they were registered using WithProcessor.
64 // Implementations may synchronously modify the record so that the changes
65 // are visible in the next registered processor.
66 //
67 // Note that Record is not concurrent safe. Therefore, asynchronous
68 // processing may cause race conditions. Use Record.Clone
69 // to create a copy that shares no state with the original.
70 OnEmit(ctx context.Context, record *Record) error
71
72 // Shutdown is called when the SDK shuts down. Any cleanup or release of
73 // resources held by the Processor (and any underlying Exporter) should be
74 // done in this call.
75 //
76 // The deadline or cancellation of the passed context must be honored. An
77 // appropriate error should be returned in these situations.
78 //
79 // After Shutdown is called, calls to OnEmit, Shutdown, or ForceFlush
80 // should perform no operation and return nil error.
81 Shutdown(ctx context.Context) error
82
83 // ForceFlush exports log records to the configured Exporter that have not yet
84 // been exported.
85 //
86 // The deadline or cancellation of the passed context must be honored. An
87 // appropriate error should be returned in these situations.
88 ForceFlush(ctx context.Context) error
89 }
90
91 // EnabledParameters represents payload for [Processor]'s Enabled method.
92 type EnabledParameters struct {
93 InstrumentationScope instrumentation.Scope
94 Severity log.Severity
95 EventName string
96 }