Factory for creating Tracer instances. Holds configuration shared across all tracers: processors, sampler, resource, limits, and propagators.

Spec: https://opentelemetry.io/docs/specs/otel/trace/api/#tracerprovider

Since: 0.0.1.0

Initialize a new tracer provider

You should generally use getGlobalTracerProvider for most applications.

Since: 0.0.1.0

This method provides a way for provider to do any cleanup required.

This will also trigger shutdowns on all internal processors.

Since: 0.0.1.0

Since: 0.0.1.0

Combine two shutdown results, preferring the "worst" outcome. Failure > Timeout > Success.

Since: 0.4.0.0

This method provides a way for provider to immediately export all spans that have not yet been exported for all the internal processors.

Since: 0.0.1.0

The outcome of a call to OpenTelemetry.Trace.forceFlush or OpenTelemetry.Log.forceFlush

Since: 0.0.1.0

Since: 0.0.1.0

Since: 0.0.1.0

Access the globally configured TracerProvider. Once the the global tracer provider is initialized via the OpenTelemetry SDK, Tracers created from this TracerProvider will export spans to their configured exporters. Prior to that, any Tracers acquired from the uninitialized TracerProvider will create no-op spans.

Since: 0.0.1.0

Overwrite the globally configured TracerProvider.

Tracers acquired from the previously installed TracerProvider will continue to use that TracerProviders configured span processors, exporters, and other settings.

Since: 0.0.1.0

Options for creating a TracerProvider with invalid ids, no resources, default limits, and no propagators.

In effect, tracing is a no-op when using this configuration.

Since: 0.0.1.0

Options used when creating a TracerProvider.

Since: 0.0.1.0

Creates and manages Spans for a specific instrumentation scope.

Spec: https://opentelemetry.io/docs/specs/otel/trace/api/#tracer

Since: 0.0.1.0

Get the name of the Tracer

Since: 0.0.10

Check if the Tracer is enabled.

This function helps users avoid performing computationally expensive operations when creating Spans if the tracer is not enabled.

A Tracer is considered enabled if it has at least one configured processor. If the TracerProvider has no processors, all spans will be dropped, so the tracer is disabled.

Callers SHOULD invoke this before each span creation to get the most up-to-date response, as the result may change over time.

Since: 0.3.1.0

A small utility lens for extracting a Tracer from a larger data type

This will generally be most useful as a means of implementing getTracer

Since: 0.0.1.0

Construct a Tracer from a provider, library, and options.

Prefer a non-empty libraryName per the OpenTelemetry specification; use getTracer if you want a warning when the name is empty.

Since: 0.0.1.0

Like makeTracer but caches by InstrumentationLibrary, so repeated calls with the same scope return the same Tracer instance. Spec: implementations SHOULD return a single Tracer per InstrumentationScope.

Since: 0.0.1.0

Since: 0.0.1.0

Since: 0.0.1.0

An instrumentation scope identifies the library or component providing instrumentation. The OpenTelemetry specification renamed this concept from "Instrumentation Library" to "Instrumentation Scope"; this type retains the old constructor name for backwards compatibility but InstrumentationScope is the preferred type alias.

Spec: https://opentelemetry.io/docs/specs/otel/common/instrumentation-scope/

Since: 0.0.1.0

Create an InstrumentationLibrary with a name and version. Schema URL and attributes default to empty.

Prefer instrumentationScope for new code.

Since: 0.4.0.0

Set the schema URL on an InstrumentationLibrary.

Since: 0.4.0.0

Set attributes on an InstrumentationLibrary.

Since: 0.4.0.0

Works out the instrumentation library for your package.

Since: 0.0.1.0

Tracer configuration options.

Since: 0.0.1.0

Default Tracer options

Since: 0.0.1.0

A single unit of work in a distributed trace.

A span carries a name, timestamps, attributes, events, links, and a SpanContext (trace ID + span ID). The three constructors represent:

• Span: a live, recording span created by this process.
• FrozenSpan: a non-recording wrapper around a remote SpanContext, used as a parent when continuing a trace from another process.
• Dropped: a span that was not sampled. Carries enough context (trace ID, span ID) for propagation but records nothing.

Spec: https://opentelemetry.io/docs/specs/otel/trace/api/#span

Since: 0.0.1.0

Extracts the values from a Span if it is still mutable. Returns a Left with FrozenOrDropped if the Span is frozen or dropped.

Since: 0.0.1.0

Since: 0.0.1.0

The representation of a Span for processors and exporters.

Cold (immutable) fields live directly in the record and are never copied. Hot (mutable) fields sit behind an IORef so that CAS operations only allocate a fresh SpanHot instead of the entire span.

Since: 0.0.1.0

Mutable fields of a span, stored behind an IORef and updated via CAS. Only ~48 bytes, so each CAS allocates much less than copying the full span.

Since: 0.0.1.0

The serializable portion of a Span: trace ID, span ID, trace flags, and trace state. Immutable once created.

Spec: https://opentelemetry.io/docs/specs/otel/trace/api/#spancontext W3C: https://www.w3.org/TR/trace-context/

Since: 0.0.1.0

Contain details about the trace. Unlike TraceState values, TraceFlags are present in all traces. The current version of the specification only supports a single flag called sampled.

Since: 0.0.1.0

Get the current bitmask for the TraceFlags, useful for serialization purposes.

Since: 0.0.1.0

Create a TraceFlags, from an arbitrary Word8. Note that for backwards-compatibility reasons, no checking is performed to determine whether the TraceFlags bitmask provided is valid.

Since: 0.0.1.0

TraceFlags with the sampled flag not set. This means that it is up to the sampling configuration to decide whether or not to sample the trace.

Since: 0.0.1.0

Will the trace associated with this TraceFlags value be sampled?

Since: 0.0.1.0

Set the sampled flag on the TraceFlags

Since: 0.0.1.0

Unset the sampled flag on the TraceFlags. This means that the application may choose whether or not to emit this Trace.

Since: 0.0.1.0

Test the W3C Level 2 random flag (bit 1). When set, the trace-id has sufficient randomness for probabilistic sampling decisions.

See https://www.w3.org/TR/trace-context-2/#random-trace-id-flag.

Since: 0.4.0.0

Set the W3C Level 2 random flag (bit 1) on the TraceFlags. Indicates that the trace-id was generated with a CSPRNG or equivalent and has sufficient randomness for probabilistic sampling.

Since: 0.4.0.0

Unset the W3C Level 2 random flag (bit 1).

Since: 0.4.0.0

The simplest function for annotating code with trace information.

Since: 0.0.1.0

Like inSpan, but passes the created Span to the action.

Since: 0.0.1.0

Like inSpan′ (the Haskell name has one ASCII prime), but does not add automatic caller source location attributes.

Since: 0.4.0.0

Create a Span.

If the provided Context has a span in it (inserted via insertSpan), that Span will be used as the parent of the Span created via this API.

Note: if the hs-opentelemetry-sdk or another SDK is not installed, all actions that use the created Spans produced will be no-ops.

Since: 0.0.1.0

The same thing as createSpan, except that it does not have a HasCallStack constraint.

Since: 0.0.1.0

Wrap a SpanContext as a non-recording Span (FrozenSpan).

Since: 0.0.1.0

Construct a non-recording parent span representing a dropped (not sampled) trace, e.g. for tests or when continuing a trace whose parent was not recorded.

Since: 0.4.0.0

SpanKind describes the relationship between the Span, its parents, and its children in a Trace. SpanKind describes two independent properties that benefit tracing systems during analysis.

The first property described by SpanKind reflects whether the Span is a remote child or parent. Spans with a remote parent are interesting because they are sources of external load. Spans with a remote child are interesting because they reflect a non-local system dependency.

The second property described by SpanKind reflects whether a child Span represents a synchronous call. When a child span is synchronous, the parent is expected to wait for it to complete under ordinary circumstances. It can be useful for tracing systems to know this property, since synchronous Spans may contribute to the overall trace latency. Asynchronous scenarios can be remote or local.

In order for SpanKind to be meaningful, callers SHOULD arrange that a single Span does not serve more than one purpose. For example, a server-side span SHOULD NOT be used directly as the parent of another remote span. As a simple guideline, instrumentation should create a new Span prior to extracting and serializing the SpanContext for a remote call.

To summarize the interpretation of these kinds

Since: 0.0.1.0

Smart constructor for SpanArguments providing reasonable values for most Spans created that are internal to an application.

Defaults:

• kind: Internal
• attributes: []
• links: []
• startTime: Nothing (getTimestamp will be called upon Span creation)

Since: 0.0.1.0

Non-name fields that may be set on initial creation of a Span.

Since: 0.0.1.0

A “log” that happens as part of a span. An operation that is too fast for its own span, but too unique to roll up into its parent span.

Events contain a name, a timestamp, and an optional set of Attributes, along with a timestamp. Events represent an event that occurred at a specific time within a span’s workload.

Since: 0.0.1.0

A “log” that happens as part of a span. An operation that is too fast for its own span, but too unique to roll up into its parent span.

Events contain a name, a timestamp, and an optional set of Attributes, along with a timestamp. Events represent an event that occurred at a specific time within a span’s workload.

When creating an event, this is the version that you will use. Attributes added that exceed the configured attribute limits will be dropped, which is accounted for in the Event structure.

Since: 0.0.1.0

Add an event to a recording span. Events will not be recorded for remote spans and dropped spans.

Since: 0.0.1.0

Updates the Span name. Upon this update, any sampling behavior based on Span name will depend on the implementation.

Note that Samplers can only consider information already present during span creation. Any changes done later, including updated span name, cannot change their decisions.

Alternatives for the name update may be late Span creation, when Span is started with the explicit timestamp from the past at the moment where the final Span name is known, or reporting a Span with the desired name as a child Span.

Since: 0.0.1.0

Add an attribute to a span. Only affects recording spans.

See the OTel attribute naming conventions for guidance on choosing attribute names.

Since: 0.0.1.0

A convenience function related to addAttribute that adds multiple attributes to a span at the same time.

This function may be slightly more performant than repeatedly calling addAttribute.

Since: 0.0.1.0

Like addAttributes, but takes an AttrsBuilder instead of a HashMap. More efficient when setting many attributes at once.

With typed AttributeKeys from semantic conventions:

addAttributes' span $
    SC.http_request_method .@ method
 <> SC.url_full .@ url
 <> SC.server_port .@? mPort

With plain Text keys:

addAttributes' span $
    attr "custom.key" value
 <> optAttr "custom.optional" mValue

Since: 0.4.1.0

This can be useful for pulling data for attributes and using it to copy / otherwise use the data to further enrich instrumentation.

Since: 0.0.1.0

Church-encoded left fold over attribute key-value pairs. Avoids allocating intermediate tuples, list spines, or HashMaps when adding multiple attributes to a span.

Construct individual entries with attr / .@ and combine with <>. GHC can inline and fuse static builder expressions, eliminating all intermediate allocation.

addAttributes' span $
    SC.http_request_method .@ method
 <> SC.url_full .@ url
 <> SC.server_port .@? mPort

Since: 0.4.0.0

Build an attribute entry from a Text key. The value is converted to Attribute lazily; actual conversion is deferred until the exporter thread reads the attribute, keeping the instrumented thread fast.

Since: 0.4.0.0

Build an optional attribute entry. Nothing contributes nothing to the builder (zero cost).

Since: 0.4.0.0

Build an attribute entry from a typed AttributeKey. Type-safe: the value type must match the key's phantom type.

SC.http_request_method .@ (GET :: Text)

Since: 0.4.0.0

Build an optional attribute entry from a typed AttributeKey. Nothing contributes nothing to the builder.

Since: 0.4.0.0

Materialize a builder into an AttributeMap. Useful when a raw HashMap is needed (e.g. for NewEvent attributes or SpanArguments).

Since: 0.4.0.0

Frozen (immutable) version of NewLink, stored on completed spans. Created internally by freezing a NewLink; attributes are truncated per the configured limits. See NewLink for full documentation on link semantics.

Since: 0.0.1.0

This is a link that is being added to a span which is going to be created.

A Span may be linked to zero or more other Spans (defined by SpanContext) that are causally related. Links can point to Spans inside a single Trace or across different Traces. Links can be used to represent batched operations where a Span was initiated by multiple initiating Spans, each representing a single incoming item being processed in the batch.

Another example of using a Link is to declare the relationship between the originating and following trace. This can be used when a Trace enters trusted boundaries of a service and service policy requires the generation of a new Trace rather than trusting the incoming Trace context. The new linked Trace may also represent a long running asynchronous data processing operation that was initiated by one of many fast incoming requests.

When using the scatter/gather (also called fork/join) pattern, the root operation starts multiple downstream processing operations and all of them are aggregated back in a single Span. This last Span is linked to many operations it aggregates. All of them are the Spans from the same Trace. And similar to the Parent field of a Span. It is recommended, however, to not set parent of the Span in this scenario as semantically the parent field represents a single parent scenario, in many cases the parent Span fully encloses the child Span. This is not the case in scatter/gather and batch scenarios.

Since: 0.0.1.0

Add a link to a recording span.

Since: 0.0.1.0

A specialized variant of addEvent that records attributes conforming to the OpenTelemetry specification's semantic conventions

Since: 0.0.1.0

Record an error and set the span status in one call.

Combines setStatus with Error and recordException. This is a common pattern when handling errors outside of inSpan (which does this automatically for uncaught exceptions).

case result of
  Left err -> recordError span err
  Right _  -> setStatus span Ok

Since: 0.4.1.0

Sets the Status of the Span. If used, this will override the default Span status, which is Unset.

These values form a total order: Ok > Error > Unset. This means that setting Status with StatusCode=Ok will override any prior or future attempts to set span Status with StatusCode=Error or StatusCode=Unset.

Since: 0.0.1.0

The status of a Span. This may be used to indicate the successful completion of a span.

The default is Unset.

Ok is final: once a span's status is Ok, subsequent setStatus calls are ignored. Error can be set from Unset, and Ok can override Error (or Unset). Transitions: Unset -> Error, Unset -> Ok, Error -> Ok.

An Ord instance is provided (Ok > Error > Unset) for convenience but does not govern status-setting precedence.

Since: 0.0.1.0

How an exception should be treated by the tracing system when caught by inSpan and similar bracket-style functions.

Since: 0.4.0.0

The result of classifying an exception via an ExceptionHandler.

Since: 0.4.0.0

A function that inspects a SomeException and optionally classifies it.

Returns Nothing to indicate this handler does not recognize the exception, deferring to the next handler in the chain. Returns Just ExceptionResponse to provide a classification and optional extra attributes.

Multiple handlers are chained: tracer-level handlers are consulted first, then provider-level handlers. The first Just result wins. If all handlers return Nothing, the default behavior (ErrorException with no extra attributes) applies.

Since: 0.4.0.0

The default response when no handler matches: classify as ErrorException with no additional attributes.

Since: 0.4.0.0

Resolve exception classification by consulting tracer-level handlers first, then provider-level handlers. Returns defaultExceptionResponse if no handler matches.

Since: 0.4.0.0

Signals that the operation described by this span has now (or at the time optionally specified) ended.

This does have any effects on child spans. Those may still be running and can be ended later.

This also does not inactivate the Span in any Context it is active in. It is still possible to use an ended span as parent via a Context it is contained in. Also, putting the Span into a Context will still work after the Span was ended.

Since: 0.0.1.0

When sending tracing information across process boundaries, the SpanContext is used to serialize the relevant information.

Since: 0.0.1.0

Returns whether the Span is currently recording.

A live Span created by this process returns True until endSpan is called. A FrozenSpan (non-recording context-only wrapper, e.g. from wrapSpanContext) and a Dropped span always return False.

Since: 0.0.1.0

Returns True if the SpanContext has a non-zero TraceID and a non-zero SpanID. Spec: "true if the SpanContext has a non-zero TraceID and a non-zero SpanID".

Since: 0.0.1.0

Returns True if the SpanContext was propagated from a remote parent,

When extracting a SpanContext through the Propagators API, isRemote MUST return True, whereas for the SpanContext of any child spans it MUST return False.

Since: 0.0.1.0

Retrieve the active Span from the current thread's context.

Returns Nothing if there is no span in the current context (e.g. at the top level, before any tracing has started).

This is the Haskell equivalent of Go's trace.SpanFromContext(ctx) and Rust's get_active_span.

Since: 0.4.1.0

Run an action on the active span. If there is no active span in the current context, the action is silently skipped.

withActiveSpan $ \span -> do
  addAttribute span "user.id" (toAttribute userId)
  addEvent span (newEvent "cache-miss")

Since: 0.4.1.0

Retrieve the SpanContext of the active span, useful for log correlation (extracting trace/span IDs) without needing the full Span handle.

Since: 0.4.1.0

Construct a NewEvent with just a name (no attributes, current timestamp).

addEvent span (newEvent "cache-miss")

Since: 0.4.1.0

Construct a NewEvent with a name and attributes (current timestamp).

addEvent span (newEventWith "retry" [("attempt", toAttribute retryCount)])

Since: 0.4.1.0

Wall-clock timestamp stored as nanoseconds since Unix epoch. Matches the OTLP wire format directly (fixed64 nanoseconds).

Since: 0.0.1.0

Sometimes, you may have a more accurate notion of when a traced operation has ended. In this case you may call getTimestamp, and then supply endSpan with the more accurate timestamp you have acquired.

When using the monadic interface, (such as inSpan, you may call endSpan early to record the information, and the first call to endSpan will be honored.

Since: 0.0.1.0

Nanoseconds since the Unix epoch.

Since: 0.0.1.0

Really only intended for tests, this function does not conform to semantic versioning .

Since: 0.0.1.0

Run an action only when the span is recording. Use this to guard expensive attribute computation that would be wasted on non-recording spans.

Since: 0.0.1.0

Creates source code attributes describing the caller of the current function. You should use this if you are getting source code attributes from inside a function that is creating a span.

Respects OTEL_SEMCONV_STABILITY_OPT_IN=code to select stable vs legacy attribute names.

Note: this will return nothing if the call stack is frozen.

Creates source code attributes describing where the current function is called. You should use this if you are getting source code attributes from inside a "span creation" function.

Respects OTEL_SEMCONV_STABILITY_OPT_IN=code to select stable vs legacy attribute names.

Note: this will return nothing if the call stack is frozen.

Attributes are added to the end of the span argument list, so will be discarded if the number of attributes in the span exceeds the limit.

Configurable limits on span attributes, events, and links.

Spec: https://opentelemetry.io/docs/specs/otel/trace/sdk/#span-limits

Since: 0.0.1.0

Since: 0.0.1.0

Like bracket, but provides the after function with information about uncaught exceptions.

Since: 0.1.0.0