Tracers can be created from a TracerProvider.

Create a new TracerProvider and set it as the global tracer provider. This pulls all configuration from environment variables. The full list of environment variables supported is specified in the configuration section of this module's documentation.

Note however, that 3rd-party span processors, exporters, sampling strategies, etc. may have their own set of environment-based configuration values that they utilize.

Detect options for initializing a tracer provider from the app environment, taking additional supported resources as well.

Since: 0.0.3.1

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

This will also trigger shutdowns on all internal processors.

Since: hs-opentelemetry-api-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: hs-opentelemetry-api-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: hs-opentelemetry-api-0.0.1.0

The Tracer is responsible for creating Spans.

Each Tracer should be associated with the library or application that it instruments.

Get the name of the Tracer

Since: hs-opentelemetry-api-0.0.10

Tracer configuration options.

Default Tracer options

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: hs-opentelemetry-api-0.0.1.0

An identifier for the library that provides the instrumentation for a given Instrumented Library. Instrumented Library and Instrumentation Library may be the same library if it has built-in OpenTelemetry instrumentation.

The inspiration of the OpenTelemetry project is to make every library and application observable out of the box by having them call OpenTelemetry API directly. However, many libraries will not have such integration, and as such there is a need for a separate library which would inject such calls, using mechanisms such as wrapping interfaces, subscribing to library-specific callbacks, or translating existing telemetry into the OpenTelemetry model.

A library that enables OpenTelemetry observability for another library is called an Instrumentation Library.

An instrumentation library should be named to follow any naming conventions of the instrumented library (e.g. middleware for a web framework).

If there is no established name, the recommendation is to prefix packages with "hs-opentelemetry-instrumentation", followed by the instrumented library name itself.

In general, you can initialize the instrumentation library like so:

import qualified Data.Text as T
import Data.Version (showVersion)
import Paths_your_package_name

instrumentationLibrary :: InstrumentationLibrary
instrumentationLibrary = InstrumentationLibrary
  { libraryName = "your_package_name"
  , libraryVersion = T.pack $ showVersion version
  }

A Span is the fundamental type you'll work with to trace your systems.

A span is a single piece of instrumentation from a single location in your code or infrastructure. A span represents a single "unit of work" done by a service. Each span contains several key pieces of data:

• A service name identifying the service the span is from
• A name identifying the role of the span (like function or method name)
• A timestamp that corresponds to the start of the span
• A duration that describes how long that unit of work took to complete
• An ID that uniquely identifies the span
• A trace ID identifying which trace the span belongs to
• A parent ID representing the parent span that called this span. (There is no parent ID for the root span of a given trace, which denotes that it's the start of the trace.)
• Any additional metadata that might be helpful.
• Zero or more links to related spans. Links can be useful for connecting causal relationships between things like web requests that enqueue asynchronous tasks to be processed.
• Events, which denote a point in time occurrence. These can be useful for recording data about a span such as when an exception was thrown, or to emit structured logs into the span tree.

A trace is made up of multiple spans. Tracing vendors such as Zipkin, Jaeger, Honeycomb, Datadog, Lightstep, etc. use the metadata from each span to reconstruct the relationships between them and generate a trace diagram.

The simplest function for annotating code with trace information.

Since: hs-opentelemetry-api-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)

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

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

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.

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: hs-opentelemetry-api-0.0.1.0

Add an attribute to a span. Only has a useful effect on recording spans.

As an application developer when you need to record an attribute first consult existing semantic conventions for Resources, Spans, and Metrics. If an appropriate name does not exists you will need to come up with a new name. To do that consider a few options:

The name is specific to your company and may be possibly used outside the company as well. To avoid clashes with names introduced by other companies (in a distributed system that uses applications from multiple vendors) it is recommended to prefix the new name by your company’s reverse domain name, e.g. 'com.acme.shopname'.

The name is specific to your application that will be used internally only. If you already have an internal company process that helps you to ensure no name clashes happen then feel free to follow it. Otherwise it is recommended to prefix the attribute name by your application name, provided that the application name is reasonably unique within your organization (e.g. 'myuniquemapapp.longitude' is likely fine). Make sure the application name does not clash with an existing semantic convention namespace.

The name may be generally applicable to applications in the industry. In that case consider submitting a proposal to this specification to add a new name to the semantic conventions, and if necessary also to add a new namespace.

It is recommended to limit names to printable Basic Latin characters (more precisely to 'U+0021' .. 'U+007E' subset of Unicode code points), although the Haskell OpenTelemetry specification DOES provide full Unicode support.

Attribute names that start with 'otel.' are reserved to be defined by OpenTelemetry specification. These are typically used to express OpenTelemetry concepts in formats that don’t have a corresponding concept.

For example, the 'otel.library.name' attribute is used to record the instrumentation library name, which is an OpenTelemetry concept that is natively represented in OTLP, but does not have an equivalent in other telemetry formats and protocols.

Any additions to the 'otel.*' namespace MUST be approved as part of OpenTelemetry specification.

Since: hs-opentelemetry-api-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: hs-opentelemetry-api-0.0.1.0

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

Since: hs-opentelemetry-api-0.0.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: hs-opentelemetry-api-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

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.

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: hs-opentelemetry-api-0.0.1.0

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

Since: hs-opentelemetry-api-0.0.1.0

Initialize a new tracer provider

You should generally use getGlobalTracerProvider for most applications.

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: hs-opentelemetry-api-0.0.1.0

Use all built-in resource detectors to populate resource information.

Currently used detectors include:

• detectService
• detectProcess
• detectOperatingSystem
• detectHost
• detectTelemetry
• detectProcessRuntime

This list will grow in the future as more detectors are implemented.

Since: 0.0.1.0

Detect a sampler from the app environment. If no sampler is specified, the parentbased sampler is used.

Since: 0.0.3.3

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: hs-opentelemetry-api-0.0.1.0

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

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: hs-opentelemetry-api-0.0.1.0

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

Convert a Haskell value to an Attribute value.

For most values, you can define an instance of ToPrimitiveAttribute and use the default toAttribute implementation:

data Foo = Foo

instance ToPrimitiveAttribute Foo where
  toPrimitiveAttribute Foo = TextAttribute Foo
instance ToAttribute foo

Convert a Haskell value to a PrimitiveAttribute value.

An attribute represents user-provided metadata about a span, link, or event.

Telemetry tools may use this data to support high-cardinality querying, visualization in waterfall diagrams, trace sampling decisions, and more.

This is an immutable link for an existing span.

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 scattergather (also called forkjoin) 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.

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.

A SpanContext represents the portion of a Span which must be serialized and propagated along side of a distributed context. SpanContexts are immutable.

The frozen representation of a Span that originates from the currently running process.

Only Processors and Exporters should use rely on this interface.