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