hs-opentelemetry-api-0.0.3.8: OpenTelemetry API for use by libraries for direct instrumentation or wrapper packages.
Copyright(c) Ian Duncan 2021
LicenseBSD-3
MaintainerIan Duncan
Stabilityexperimental
Portabilitynon-portable (GHC extensions)
Safe HaskellSafe-Inferred
LanguageHaskell2010

OpenTelemetry.Processor

Description

Span processor is an interface which allows hooks for span start and end method invocations. The span processors are invoked only when IsRecording is true.

Built-in span processors are responsible for batching and conversion of spans to exportable representation and passing batches to exporters.

Span processors can be registered directly on SDK TracerProvider and they are invoked in the same order as they were registered.

Each processor registered on TracerProvider is a start of pipeline that consist of span processor and optional exporter. SDK MUST allow to end each pipeline with individual exporter.

SDK MUST allow users to implement and configure custom processors and decorate built-in processors for advanced scenarios such as tagging or filtering.

Documentation

data Processor Source #

Constructors

Processor 

Fields

  • processorOnStart :: IORef ImmutableSpan -> Context -> IO ()

    Called when a span is started. This method is called synchronously on the thread that started the span, therefore it should not block or throw exceptions.

  • processorOnEnd :: IORef ImmutableSpan -> IO ()

    Called after a span is ended (i.e., the end timestamp is already set). This method is called synchronously within the endSpan API, therefore it should not block or throw an exception.

  • processorShutdown :: IO (Async ShutdownResult)

    Shuts down the processor. Called when SDK is shut down. This is an opportunity for processor to do any cleanup required.

    Shutdown SHOULD be called only once for each SpanProcessor instance. After the call to Shutdown, subsequent calls to OnStart, OnEnd, or ForceFlush are not allowed. SDKs SHOULD ignore these calls gracefully, if possible.

    Shutdown SHOULD let the caller know whether it succeeded, failed or timed out.

    Shutdown MUST include the effects of ForceFlush.

    Shutdown SHOULD complete or abort within some timeout. Shutdown can be implemented as a blocking API or an asynchronous API which notifies the caller via a callback or an event. OpenTelemetry client authors can decide if they want to make the shutdown timeout configurable.

  • processorForceFlush :: IO ()

    This is a hint to ensure that any tasks associated with Spans for which the SpanProcessor had already received events prior to the call to ForceFlush SHOULD be completed as soon as possible, preferably before returning from this method.

    In particular, if any Processor has any associated exporter, it SHOULD try to call the exporter's Export with all spans for which this was not already done and then invoke ForceFlush on it. The built-in SpanProcessors MUST do so. If a timeout is specified (see below), the SpanProcessor MUST prioritize honoring the timeout over finishing all calls. It MAY skip or abort some or all Export or ForceFlush calls it has made to achieve this goal.

    ForceFlush SHOULD provide a way to let the caller know whether it succeeded, failed or timed out.

    ForceFlush SHOULD only be called in cases where it is absolutely necessary, such as when using some FaaS providers that may suspend the process after an invocation, but before the SpanProcessor exports the completed spans.

    ForceFlush SHOULD complete or abort within some timeout. ForceFlush can be implemented as a blocking API or an asynchronous API which notifies the caller via a callback or an event. OpenTelemetry client authors can decide if they want to make the flush timeout configurable.