Copyright | (c) Ian Duncan 2021 |
---|---|
License | BSD-3 |
Maintainer | Ian Duncan |
Stability | experimental |
Portability | non-portable (GHC extensions) |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
Traces track the progression of a single request, called a trace, as it is handled by services that make up an application. The request may be initiated by a user or an application. Distributed tracing is a form of tracing that traverses process, network and security boundaries. Each unit of work in a trace is called a span; a trace is a tree of spans. Spans are objects that represent the work being done by individual services or components involved in a request as it flows through a system. A span contains a span context, which is a set of globally unique identifiers that represent the unique request that each span is a part of. A span provides Request, Error and Duration (RED) metrics that can be used to debug availability as well as performance issues.
Here is a visualization of the relationship between traces and spans:
A trace contains a single root span which encapsulates the end-to-end latency for the entire request. You can think of this as a single logical operation, such as clicking a button in a web application to add a product to a shopping cart. The root span would measure the time it took from an end-user clicking that button to the operation being completed or failing (so, the item is added to the cart or some error occurs) and the result being displayed to the user. A trace is comprised of the single root span and any number of child spans, which represent operations taking place as part of the request. Each span contains metadata about the operation, such as its name, start and end timestamps, attributes (which represent additonal user-defined metadata about a span), events, and status.
To create and manage spans in OpenTelemetry, the OpenTelemetry API provides the tracer interface. This object is responsible for tracking the active span in your process, and allows you to access the current span in order to perform operations on it such as adding attributes, events, and finishing it when the work it tracks is complete. One or more tracer objects can be created in a process through the tracer provider, a factory interface that allows for multiple tracers to be instantiated in a single process with different options.
Generally, the lifecycle of a span resembles the following:
- A request is received by a service. The span context is extracted from the request headers, if it exists.
- A new span is created as a child of the extracted span context; if none exists, a new root span is created.
- The service handles the request. Additional attributes and events are added to the span that are useful for understanding the context of the request, such as the hostname of the machine handling the request, or customer identifiers.
- New spans may be created to represent work being done by sub-components of the service.
- When the service makes a remote call to another service, the current span context is serialized and forwarded to the next service by injecting the span context into the headers or message envelope.
- The work being done by the service completes, successfully or not. The span status is appropriately set, and the span is marked finished.
- For more information, see the traces specification, which covers concepts including: trace, span, parent/child relationship, span context, attributes, events and links.
This module implements eveything required to conform to the trace & span public interface described by the OpenTelemetry specification.
See OpenTelemetry.Trace.Monad for an implementation of inSpan
variants that are
slightly easier to use in idiomatic Haskell monadic code.
Synopsis
- data TracerProvider
- initializeGlobalTracerProvider :: IO TracerProvider
- initializeTracerProvider :: IO TracerProvider
- getTracerProviderInitializationOptions :: IO ([Processor], TracerProviderOptions)
- getTracerProviderInitializationOptions' :: ResourceMerge 'Nothing any ~ 'Nothing => Resource any -> IO ([Processor], TracerProviderOptions)
- shutdownTracerProvider :: MonadIO m => TracerProvider -> m ()
- getGlobalTracerProvider :: MonadIO m => m TracerProvider
- setGlobalTracerProvider :: MonadIO m => TracerProvider -> m ()
- data Tracer
- tracerName :: Tracer -> InstrumentationLibrary
- getTracer :: MonadIO m => TracerProvider -> InstrumentationLibrary -> TracerOptions -> m Tracer
- makeTracer :: TracerProvider -> InstrumentationLibrary -> TracerOptions -> Tracer
- newtype TracerOptions = TracerOptions {}
- tracerOptions :: TracerOptions
- class HasTracer s where
- data InstrumentationLibrary = InstrumentationLibrary {
- libraryName :: !Text
- libraryVersion :: !Text
- data Span
- inSpan :: (MonadUnliftIO m, HasCallStack) => Tracer -> Text -> SpanArguments -> m a -> m a
- defaultSpanArguments :: SpanArguments
- data SpanArguments = SpanArguments {}
- data SpanKind
- data NewLink = NewLink {}
- inSpan' :: (MonadUnliftIO m, HasCallStack) => Tracer -> Text -> SpanArguments -> (Span -> m a) -> m a
- updateName :: MonadIO m => Span -> Text -> m ()
- addAttribute :: (MonadIO m, ToAttribute a) => Span -> Text -> a -> m ()
- addAttributes :: MonadIO m => Span -> HashMap Text Attribute -> m ()
- recordException :: (MonadIO m, Exception e) => Span -> HashMap Text Attribute -> Maybe Timestamp -> e -> m ()
- setStatus :: MonadIO m => Span -> SpanStatus -> m ()
- data SpanStatus
- data NewEvent = NewEvent {}
- addEvent :: MonadIO m => Span -> NewEvent -> m ()
- inSpan'' :: (MonadUnliftIO m, HasCallStack) => Tracer -> Text -> SpanArguments -> (Span -> m a) -> m a
- createTracerProvider :: MonadIO m => [Processor] -> TracerProviderOptions -> m TracerProvider
- data TracerProviderOptions = TracerProviderOptions {
- tracerProviderOptionsIdGenerator :: IdGenerator
- tracerProviderOptionsSampler :: Sampler
- tracerProviderOptionsResources :: MaterializedResources
- tracerProviderOptionsAttributeLimits :: AttributeLimits
- tracerProviderOptionsSpanLimits :: SpanLimits
- tracerProviderOptionsPropagators :: Propagator Context RequestHeaders ResponseHeaders
- tracerProviderOptionsLogger :: Log Text -> IO ()
- emptyTracerProviderOptions :: TracerProviderOptions
- detectBuiltInResources :: IO (Resource 'Nothing)
- detectSampler :: IO Sampler
- createSpan :: (MonadIO m, HasCallStack) => Tracer -> Context -> Text -> SpanArguments -> m Span
- createSpanWithoutCallStack :: MonadIO m => Tracer -> Context -> Text -> SpanArguments -> m Span
- endSpan :: MonadIO m => Span -> Maybe Timestamp -> m ()
- spanGetAttributes :: MonadIO m => Span -> m Attributes
- class ToAttribute a where
- toAttribute :: a -> Attribute
- class ToPrimitiveAttribute a where
- data Attribute
- data PrimitiveAttribute
- data Link
- data Event
- data SpanContext = SpanContext {
- traceFlags :: TraceFlags
- isRemote :: Bool
- traceId :: TraceId
- spanId :: SpanId
- traceState :: TraceState
- data ImmutableSpan = ImmutableSpan {}
How to use this library
Quick start
- Initialize a
TracerProvider
. - Create a
Tracer
for your system. - Add relevant pre-made instrumentation
- Annotate your internal functions using the
inSpan
function or one of its variants.
Configuration
General configuration variables
Name | Description | Default | Notes |
---|---|---|---|
OTEL_RESOURCE_ATTRIBUTES | Key-value pairs to be used as resource attributes | See Resource semantic conventions for details. | See Resource SDK for more details. |
OTEL_SERVICE_NAME | Sets the value of the `service.name` resource attribute | If `service.name` is also provided in OTEL_RESOURCE_ATTRIBUTES , then OTEL_SERVICE_NAME takes precedence. | |
OTEL_LOG_LEVEL | Log level used by the SDK logger | "info" | |
OTEL_PROPAGATORS | Propagators to be used as a comma-separated list | "tracecontext,baggage" | Values MUST be deduplicated in order to register a Propagator only once. |
OTEL_TRACES_SAMPLER | Sampler to be used for traces | "parentbased_always_on" | See Sampling |
OTEL_TRACES_SAMPLER_ARG | String value to be used as the sampler argument | The specified value will only be used if OTEL_TRACES_SAMPLER is set. Each Sampler type defines its own expected input, if any. Invalid or unrecognized input MUST be logged and MUST be otherwise ignored, i.e. the SDK MUST behave as if OTEL_TRACES_SAMPLER_ARG is not set. |
Batch span processor configuration variables
Name | Description | Default | Notes |
---|---|---|---|
OTEL_BSP_SCHEDULE_DELAY | Delay interval between two consecutive exports | 5000 | |
OTEL_BSP_EXPORT_TIMEOUT | Maximum allowed time to export data | 30000 | |
OTEL_BSP_MAX_QUEUE_SIZE | Maximum queue size | 2048 | |
OTEL_BSP_MAX_EXPORT_BATCH_SIZE | Maximum batch size | 512 | Must be less than or equal to OTEL_BSP_MAX_QUEUE_SIZE |
Attribute limits
Name | Description | Default | Notes |
---|---|---|---|
OTEL_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | Empty value is treated as infinity. Non-integer and negative values are invalid. | |
OTEL_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 |
Span limits
Name | Description | Default | Notes |
---|---|---|---|
OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT | Maximum allowed attribute value size | Empty value is treated as infinity. Non-integer and negative values are invalid. | |
OTEL_SPAN_ATTRIBUTE_COUNT_LIMIT | Maximum allowed span attribute count | 128 | |
OTEL_SPAN_EVENT_COUNT_LIMIT | Maximum allowed span event count | 128 | |
OTEL_SPAN_LINK_COUNT_LIMIT | Maximum allowed span link count | 128 | |
OTEL_EVENT_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span event count | 128 | |
OTEL_LINK_ATTRIBUTE_COUNT_LIMIT | Maximum allowed attribute per span link count | 128 |
Exporting data
TracerProvider
operations
A TracerProvider
is key to using OpenTelemetry tracing. It is the data structure responsible for designating how spans are processed and exported
You will generally only need to call initializeGlobalTracerProvider
on initialization,
and shutdownTracerProvider
when your application exits.
main :: IO () main = withTracer $ tracer -> do -- your existing code here... pure () where withTracer f = bracket -- Install the SDK, pulling configuration from the environment initializeGlobalTracerProvider -- Ensure that any spans that haven't been exported yet are flushed shutdownTracerProvider (tracerProvider -> do -- Get a tracer so you can create spans tracer <- getTracer tracerProvider "your-app-name-or-subsystem" f tracer )
data TracerProvider #
Tracer
s can be created from a TracerProvider
.
initializeGlobalTracerProvider :: IO TracerProvider Source #
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.
getTracerProviderInitializationOptions' :: ResourceMerge 'Nothing any ~ 'Nothing => Resource any -> IO ([Processor], TracerProviderOptions) Source #
Detect options for initializing a tracer provider from the app environment, taking additional supported resources as well.
Since: 0.0.3.1
shutdownTracerProvider :: MonadIO m => TracerProvider -> m () #
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
Getting / setting the global TracerProvider
getGlobalTracerProvider :: MonadIO m => m TracerProvider #
Access the globally configured TracerProvider
. Once the
the global tracer provider is initialized via the OpenTelemetry SDK,
Tracer
s created from this TracerProvider
will export spans to their
configured exporters. Prior to that, any Tracer
s acquired from the
uninitialized TracerProvider
will create no-op spans.
Since: hs-opentelemetry-api-0.0.1.0
setGlobalTracerProvider :: MonadIO m => TracerProvider -> m () #
Overwrite the globally configured TracerProvider
.
Tracer
s acquired from the previously installed TracerProvider
will continue to use that TracerProvider
s configured span processors,
exporters, and other settings.
Since: hs-opentelemetry-api-0.0.1.0
Tracer
operations
tracerName :: Tracer -> InstrumentationLibrary #
Get the name of the Tracer
Since: hs-opentelemetry-api-0.0.10
getTracer :: MonadIO m => TracerProvider -> InstrumentationLibrary -> TracerOptions -> m Tracer #
makeTracer :: TracerProvider -> InstrumentationLibrary -> TracerOptions -> Tracer #
newtype TracerOptions #
Tracer configuration options.
TracerOptions | |
|
tracerOptions :: TracerOptions #
Default Tracer options
data InstrumentationLibrary #
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 }
InstrumentationLibrary | |
|
Instances
Span
operations
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.
:: (MonadUnliftIO m, HasCallStack) | |
=> Tracer | |
-> Text | The name of the span. This may be updated later via |
-> SpanArguments | Additional options for creating the span, such as |
-> m a | The action to perform. |
-> m a |
The simplest function for annotating code with trace information.
Since: hs-opentelemetry-api-0.0.1.0
defaultSpanArguments :: SpanArguments #
Smart constructor for SpanArguments
providing reasonable values for most Span
s created
that are internal to an application.
Defaults:
kind
:Internal
attributes
:[]
links
:[]
startTime
:Nothing
(getTimestamp
will be called uponSpan
creation)
data SpanArguments #
Non-name fields that may be set on initial creation of a Span
.
SpanArguments | |
|
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. Span
s 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 Span
s 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
SpanKind | Synchronous | Asynchronous | Remote Incoming | Remote Outgoing |
---|---|---|---|---|
Client | yes | yes | ||
Server | yes | yes | ||
Producer | yes | maybe | ||
Consumer | yes | maybe | ||
Internal |
Server | Indicates that the span covers server-side handling of a synchronous RPC or other remote request.
This span is the child of a remote |
Client | Indicates that the span describes a synchronous request to some remote service.
This span is the parent of a remote |
Producer | Indicates that the span describes the parent of an asynchronous request.
This parent span is expected to end before the corresponding child |
Consumer | Indicates that the span describes the child of an asynchronous |
Internal | Default value. Indicates that the span represents an internal operation within an application, as opposed to an operations with remote parents or children. |
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.
Link
s can point to Spans inside a single Trace or across different Traces. Link
s 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.
NewLink | |
|
:: (MonadUnliftIO m, HasCallStack) | |
=> Tracer | |
-> Text | The name of the span. This may be updated later via |
-> SpanArguments | |
-> (Span -> m a) | |
-> m a |
:: MonadIO m | |
=> Span | |
-> Text | The new span name, which supersedes whatever was passed in when the Span was started |
-> m () |
Updates the Span name. Upon this update, any sampling behavior based on Span name will depend on the implementation.
Note that Sampler
s 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
:: (MonadIO m, ToAttribute a) | |
=> Span | Span to add the attribute to |
-> Text | Attribute name |
-> a | Attribute value |
-> m () |
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
addAttributes :: MonadIO m => Span -> HashMap Text Attribute -> m () #
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
recordException :: (MonadIO m, Exception e) => Span -> HashMap Text Attribute -> Maybe Timestamp -> e -> m () #
A specialized variant of addEvent
that records attributes conforming to
the OpenTelemetry specification's
semantic conventions
Since: hs-opentelemetry-api-0.0.1.0
setStatus :: MonadIO m => Span -> SpanStatus -> m () #
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
data SpanStatus #
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.
Unset | The default status. |
Error Text | The operation contains an error. The text field may be empty, or else provide a description of the error. |
Ok | The operation has been validated by an Application developer or Operator to have completed successfully. |
Instances
Show SpanStatus | |
Defined in OpenTelemetry.Internal.Trace.Types showsPrec :: Int -> SpanStatus -> ShowS # show :: SpanStatus -> String # showList :: [SpanStatus] -> ShowS # | |
Eq SpanStatus | |
Defined in OpenTelemetry.Internal.Trace.Types (==) :: SpanStatus -> SpanStatus -> Bool # (/=) :: SpanStatus -> SpanStatus -> Bool # | |
Ord SpanStatus | |
Defined in OpenTelemetry.Internal.Trace.Types compare :: SpanStatus -> SpanStatus -> Ordering # (<) :: SpanStatus -> SpanStatus -> Bool # (<=) :: SpanStatus -> SpanStatus -> Bool # (>) :: SpanStatus -> SpanStatus -> Bool # (>=) :: SpanStatus -> SpanStatus -> Bool # max :: SpanStatus -> SpanStatus -> SpanStatus # min :: SpanStatus -> SpanStatus -> SpanStatus # |
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
NewEvent | |
|
addEvent :: MonadIO m => Span -> NewEvent -> m () #
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
:: (MonadUnliftIO m, HasCallStack) | |
=> Tracer | |
-> Text | The name of the span. This may be updated later via |
-> SpanArguments | |
-> (Span -> m a) | |
-> m a |
Primitive span and tracing operations
Alternative TracerProvider
initialization
createTracerProvider :: MonadIO m => [Processor] -> TracerProviderOptions -> m TracerProvider #
Initialize a new tracer provider
You should generally use getGlobalTracerProvider
for most applications.
data TracerProviderOptions #
emptyTracerProviderOptions :: TracerProviderOptions #
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
detectBuiltInResources :: IO (Resource 'Nothing) Source #
Use all built-in resource detectors to populate resource information.
Currently used detectors include:
This list will grow in the future as more detectors are implemented.
Since: 0.0.1.0
detectSampler :: IO Sampler Source #
Detect a sampler from the app environment. If no sampler is specified, the parentbased sampler is used.
Since: 0.0.3.3
:: (MonadIO m, HasCallStack) | |
=> Tracer |
|
-> Context | Context, potentially containing a parent span. If no existing parent (or context) exists,
you can use |
-> Text | Span name |
-> SpanArguments | Additional span information |
-> m Span | The created span. |
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
Span
s produced will be no-ops.
Since: hs-opentelemetry-api-0.0.1.0
:: MonadIO m | |
=> Tracer |
|
-> Context | Context, potentially containing a parent span. If no existing parent (or context) exists,
you can use |
-> Text | Span name |
-> SpanArguments | Additional span information |
-> m Span | The created span. |
The same thing as createSpan
, except that it does not have a HasCallStack
constraint.
:: MonadIO m | |
=> Span | |
-> Maybe Timestamp | Optional |
-> m () |
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
spanGetAttributes :: MonadIO m => Span -> m Attributes #
This can be useful for pulling data for attributes and using it to copy / otherwise use the data to further enrich instrumentation.
class ToAttribute a where #
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
Nothing
toAttribute :: a -> Attribute #
Instances
ToAttribute Int64 | |
Defined in OpenTelemetry.Attributes toAttribute :: Int64 -> Attribute # | |
ToAttribute Attribute | |
Defined in OpenTelemetry.Attributes toAttribute :: Attribute -> Attribute # | |
ToAttribute PrimitiveAttribute | |
Defined in OpenTelemetry.Attributes | |
ToAttribute Text | |
Defined in OpenTelemetry.Attributes toAttribute :: Text -> Attribute # | |
ToAttribute Bool | |
Defined in OpenTelemetry.Attributes toAttribute :: Bool -> Attribute # | |
ToAttribute Double | |
Defined in OpenTelemetry.Attributes toAttribute :: Double -> Attribute # | |
ToAttribute Int | |
Defined in OpenTelemetry.Attributes toAttribute :: Int -> Attribute # | |
ToPrimitiveAttribute a => ToAttribute [a] | |
Defined in OpenTelemetry.Attributes toAttribute :: [a] -> Attribute # |
class ToPrimitiveAttribute a where #
Convert a Haskell value to a PrimitiveAttribute
value.
toPrimitiveAttribute :: a -> PrimitiveAttribute #
Instances
ToPrimitiveAttribute Int64 | |
Defined in OpenTelemetry.Attributes | |
ToPrimitiveAttribute PrimitiveAttribute | |
Defined in OpenTelemetry.Attributes | |
ToPrimitiveAttribute Text | |
Defined in OpenTelemetry.Attributes | |
ToPrimitiveAttribute Bool | |
Defined in OpenTelemetry.Attributes | |
ToPrimitiveAttribute Double | |
Defined in OpenTelemetry.Attributes | |
ToPrimitiveAttribute Int | |
Defined in OpenTelemetry.Attributes |
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.
AttributeValue PrimitiveAttribute | An attribute representing a single primitive value |
AttributeArray [PrimitiveAttribute] | An attribute representing an array of primitive values. All values in the array MUST be of the same primitive attribute type. |
Instances
Data Attribute | |
Defined in OpenTelemetry.Attributes gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Attribute -> c Attribute # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Attribute # toConstr :: Attribute -> Constr # dataTypeOf :: Attribute -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Attribute) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Attribute) # gmapT :: (forall b. Data b => b -> b) -> Attribute -> Attribute # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Attribute -> r # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Attribute -> r # gmapQ :: (forall d. Data d => d -> u) -> Attribute -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Attribute -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Attribute -> m Attribute # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Attribute -> m Attribute # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Attribute -> m Attribute # | |
IsString Attribute | Create a Since: hs-opentelemetry-api-0.0.2.1 |
Defined in OpenTelemetry.Attributes fromString :: String -> Attribute # | |
Generic Attribute | |
Read Attribute | |
Show Attribute | |
Eq Attribute | |
Ord Attribute | |
Defined in OpenTelemetry.Attributes | |
Hashable Attribute | |
Defined in OpenTelemetry.Attributes | |
ToAttribute Attribute | |
Defined in OpenTelemetry.Attributes toAttribute :: Attribute -> Attribute # | |
type Rep Attribute | |
Defined in OpenTelemetry.Attributes type Rep Attribute = D1 ('MetaData "Attribute" "OpenTelemetry.Attributes" "hs-opentelemetry-api-0.1.0.0-LmqUqstYJOqI8TtFBOKz6W" 'False) (C1 ('MetaCons "AttributeValue" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 PrimitiveAttribute)) :+: C1 ('MetaCons "AttributeArray" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedStrict) (Rec0 [PrimitiveAttribute]))) |
data PrimitiveAttribute #
Instances
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.
Link
s can point to Spans inside a single Trace or across different Traces. Link
s 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.
data SpanContext #
A SpanContext
represents the portion of a Span
which must be serialized and
propagated along side of a distributed context. SpanContext
s are immutable.
SpanContext | |
|
Instances
Show SpanContext | |
Defined in OpenTelemetry.Internal.Trace.Types showsPrec :: Int -> SpanContext -> ShowS # show :: SpanContext -> String # showList :: [SpanContext] -> ShowS # | |
Eq SpanContext | |
Defined in OpenTelemetry.Internal.Trace.Types (==) :: SpanContext -> SpanContext -> Bool # (/=) :: SpanContext -> SpanContext -> Bool # |
data ImmutableSpan #
The frozen representation of a Span
that originates from the currently running process.
Only Processor
s and Exporter
s should use rely on this interface.
ImmutableSpan | |
|
Instances
Show ImmutableSpan | |
Defined in OpenTelemetry.Internal.Trace.Types showsPrec :: Int -> ImmutableSpan -> ShowS # show :: ImmutableSpan -> String # showList :: [ImmutableSpan] -> ShowS # |