Monitor.Tracing.Zipkin

This module implements a Zipkin-powered trace publisher. You will almost certainly want to import it qualified.

Zipkin does not support all OpenTracing functionality. To guarantee that everything works as expected, you should only use the functions defined in this module or exported by Monitor.Tracing.

Configuration

General settings

data Settings

Zipkin creation settings.

Constructors

Settings

Fields

• settingsHostname :: !(Maybe HostName)

  The Zipkin server's hostname, defaults to localhost if unset.

• settingsPort :: !(Maybe PortNumber)

  The port the Zipkin server is listening on, defaults to 9411 if unset.

• settingsEndpoint :: !(Maybe Endpoint)

  Local endpoint included in all published spans.

• settingsManager :: !(Maybe Manager)

  An optional HTTP manager to use for publishing spans on the Zipkin server.

• settingsPublishPeriod :: !(Maybe NominalDiffTime)

  If set to a positive value, traces will be flushed in the background every such period.

Instances

IsString Settings

Generates settings with the given string as hostname.

Defined in Monitor.Tracing.Zipkin

Methods

fromString :: String -> Settings

defaultSettings :: Settings

Creates empty Settings. You will typically use this (or the IsString instance) as starting point to only fill in the fields you care about:

let settings = defaultSettings { settingsPort = Just 2222 }

Endpoint

data Endpoint

Information about a hosted service, included in spans and visible in the Zipkin UI.

Constructors

Endpoint

Fields

• endpointService :: !(Maybe Text)

  The endpoint's service name.

• endpointPort :: !(Maybe Int)

  The endpoint's port, if applicable and known.

• endpointIPv4 :: !(Maybe Text)

  The endpoint's IPv4 address.

• endpointIPv6 :: !(Maybe Text)

  The endpoint's IPv6 address.

Instances

Eq Endpoint

Defined in Monitor.Tracing.Zipkin

Methods

(==) :: Endpoint -> Endpoint -> Bool

(/=) :: Endpoint -> Endpoint -> Bool

Ord Endpoint

Defined in Monitor.Tracing.Zipkin

Methods

compare :: Endpoint -> Endpoint -> Ordering

(<) :: Endpoint -> Endpoint -> Bool

(<=) :: Endpoint -> Endpoint -> Bool

(>) :: Endpoint -> Endpoint -> Bool

(>=) :: Endpoint -> Endpoint -> Bool

max :: Endpoint -> Endpoint -> Endpoint

min :: Endpoint -> Endpoint -> Endpoint

Show Endpoint

Defined in Monitor.Tracing.Zipkin

Methods

showsPrec :: Int -> Endpoint -> ShowS

show :: Endpoint -> String

showList :: [Endpoint] -> ShowS

IsString Endpoint

Generates an endpoint with the given string as service.

Defined in Monitor.Tracing.Zipkin

Methods

fromString :: String -> Endpoint

ToJSON Endpoint

Defined in Monitor.Tracing.Zipkin

Methods

toJSON :: Endpoint -> Value

toEncoding :: Endpoint -> Encoding

toJSONList :: [Endpoint] -> Value

toEncodingList :: [Endpoint] -> Encoding

defaultEndpoint :: Endpoint

An empty endpoint.

Publishing traces

data Zipkin

A Zipkin trace publisher.

All publisher functionality is thread-safe. In particular it is safe to publish concurrently with run, and/or run multiple actions concurrently. Note also that all sampled spans are retained in memory until they are published.

new :: MonadIO m => Settings -> m Zipkin

Creates a Zipkin publisher for the input Settings.

run :: TraceT m a -> Zipkin -> m a

Runs a TraceT action, sampling spans appropriately. Note that this method does not publish spans on its own; to do so, either call publish manually or specify a positive settingsPublishPeriod to publish in the background.

publish :: MonadIO m => Zipkin -> m ()

Flushes all complete spans to the Zipkin server.

with :: (MonadIO m, MonadBaseControl IO m) => Settings -> (Zipkin -> m a) -> m a

Convenience method to start a Zipkin, run an action, and publish all spans before returning.

Cross-process spans

Communication

data B3

Exportable trace information, used for cross-process traces.

Constructors

B3

Fields

• b3TraceID :: !TraceID

  The span's trace ID.

• b3SpanID :: !SpanID

  The span's ID.

• b3IsSampled :: !Bool

  Whether the span was sampled.

• b3IsDebug :: !Bool

  Whether the span has debug enabled (which implies that the span is sampled).

• b3ParentSpanID :: !(Maybe SpanID)

  The span's parent's ID, or Nothing for root spans.

Instances

Eq B3

Defined in Monitor.Tracing.Zipkin

Methods

(==) :: B3 -> B3 -> Bool

(/=) :: B3 -> B3 -> Bool

Ord B3

Defined in Monitor.Tracing.Zipkin

Methods

compare :: B3 -> B3 -> Ordering

(<) :: B3 -> B3 -> Bool

(<=) :: B3 -> B3 -> Bool

(>) :: B3 -> B3 -> Bool

(>=) :: B3 -> B3 -> Bool

max :: B3 -> B3 -> B3

min :: B3 -> B3 -> B3

Show B3

Defined in Monitor.Tracing.Zipkin

Methods

showsPrec :: Int -> B3 -> ShowS

show :: B3 -> String

showList :: [B3] -> ShowS

b3ToHeaders :: B3 -> Map (CI ByteString) ByteString

Serializes the B3 to multiple headers, suitable for HTTP requests. All byte-strings are UTF-8 encoded.

b3FromHeaders :: Map (CI ByteString) ByteString -> Maybe B3

Deserializes the B3 from multiple headers.

b3ToHeaderValue :: B3 -> ByteString

Serializes the B3 to a single UTF-8 encoded header value. It will typically be set as b3 header.

b3FromHeaderValue :: ByteString -> Maybe B3

Deserializes a single header value into a B3.

b3FromSpan :: Span -> B3

Span generation

clientSpan :: MonadTrace m => Name -> (Maybe B3 -> m a) -> m a

Generates a child span with CLIENT kind. This function also provides the corresponding B3 (or Nothing if tracing is inactive) so that it can be forwarded to the server. For example, to emit an HTTP request and forward the trace information in the headers:

import Network.HTTP.Simple

clientSpan "api-call" $ \(Just b3) -> $ do
  res <- httpBS "http://host/api" & addRequestHeader "b3" (b3ToHeaderValue b3)
  process res -- Do something with the response.

clientSpanWith :: MonadTrace m => (Builder -> Builder) -> Name -> (Maybe B3 -> m a) -> m a

Generates a client span, optionally modifying the span's builder. This can be useful in combination with addEndpoint if the remote server does not have tracing enabled.

serverSpan :: MonadTrace m => B3 -> m a -> m a

Generates a child span with SERVER kind. The client's B3 should be provided as input, for example parsed using b3FromHeaders.

serverSpanWith :: MonadTrace m => (Builder -> Builder) -> B3 -> m a -> m a

Generates a child span with SERVER kind, optionally modifying the span's builder. This can be useful in combination with addEndpoint if the remote client does not have tracing enabled. The clients's B3 should be provided as input. Client and server annotations go on the same span - it means that they share their span ID.

producerSpanWith :: MonadTrace m => (Builder -> Builder) -> Name -> (Maybe B3 -> m a) -> m a

Generates a child span with PRODUCER kind. This function also provides the corresponding B3 so that it can be forwarded to the consumer.

consumerSpanWith :: MonadTrace m => (Builder -> Builder) -> B3 -> m a -> m a

Generates a child span with CONSUMER kind, optionally modifying the span's builder. The producer's B3 should be provided as input. The generated span will have its parent ID set to the input B3's span ID.

Custom metadata

Tags

tag :: MonadTrace m => Text -> Text -> m ()

Adds a tag to the active span.

addTag :: Text -> Text -> Builder -> Builder

Adds a tag to a builder. This is a convenience method to use with childSpanWith, for example:

childSpanWith (addTag "key" "value") "run" $ action

Note that there is no difference with adding the tag after the span. So the above code is equivalent to:

childSpan "run" $ tag "key" "value" >> action

addInheritedTag :: Text -> Text -> Builder -> Builder

Adds an inherited tag to a builder. Unlike a tag added via addTag, this tag:

• will be inherited by all the span's local children.
• can only be added at span construction time.

For example, to add an ID tag to all spans inside a trace:

rootSpanWith (addInheritedTag "id" "abcd-efg") alwaysSampled "run" $ action

addProducerKind :: Builder -> Builder

Adds a producer kind tag to a builder. This is a convenience method to use with rootSpanWith, for example:

rootSpanWith addProducerKind alwaysSampled "root" $ action

Use this method if you want to create a root producer span. Otherwise use producerSpanWith to create a sub span with producer kind.

Annotations

Annotations are similar to tags, but timestamped.

annotate :: MonadTrace m => Text -> m ()

Annotates the active span using the current time.

annotateAt :: MonadTrace m => POSIXTime -> Text -> m ()

Annotates the active span at the given time.

Endpoints

addEndpoint :: Endpoint -> Builder -> Builder

Adds a remote endpoint to a builder. This is mostly useful when generating cross-process spans where the remote endpoint is not already traced (otherwise Zipkin will associate the spans correctly automatically). For example when emitting a request to an outside server:

clientSpanWith (addEndpoint "outside-api") -- ...