| 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 |
} |