Freckle.App.OpenTelemetry

Application tracing via https://opentelemetry.io/

data App = App
  { -- ...
  , appTracer :: Tracer
  }

instance HasTracer App where
  tracerL = lens appTracer $ x y -> x { appTracer = y }

loadApp f = do
  -- ...
  withTracerProvider $ tracerProvider -> do
    let appTracer = makeTracer tracerProvider "my-app" tracerOptions
    f App {..}

You may need to do this even if you don't plan to manually trace things, in order to satisfy the MonadTracer constraint required by functions like runDB. If you don't need this feature, and don't plan on running an otel-collector, set OTEL_TRACES_EXPORTER=none in the environment, which makes all tracing a no-op.

In the future, it should be possible to use OTEL_SDK_DISABLED for the same purpose. See https://github.com/iand675/hs-opentelemetry/issues/60.

Documentation

class HasTracer s where

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

Methods

tracerL :: Lens' s Tracer

data Tracer

The Tracer is responsible for creating Spans.

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

Instances

Show Tracer

Defined in OpenTelemetry.Internal.Trace.Types

Methods

showsPrec :: Int -> Tracer -> ShowS

show :: Tracer -> String

showList :: [Tracer] -> ShowS

Effects

class Monad m => MonadTracer (m :: Type -> Type) where

This is generally scoped by Monad stack to do different things

Methods

getTracer :: m Tracer

Instances

HasTracer app => MonadTracer (AppExample app)

Defined in Freckle.App.Test

Methods

getTracer :: AppExample app Tracer

(Monad m, HasTracer app) => MonadTracer (AppT app m)

Defined in Freckle.App

Methods

getTracer :: AppT app m Tracer

MonadTracer m => MonadTracer (IdentityT m)

Defined in OpenTelemetry.Trace.Monad

Methods

getTracer :: IdentityT m Tracer

MonadTracer m => MonadTracer (ReaderT r m)

Defined in OpenTelemetry.Trace.Monad

Methods

getTracer :: ReaderT r m Tracer

inSpan :: (MonadUnliftIO m, MonadTracer m, HasCallStack) => Text -> SpanArguments -> m a -> m a

defaultSpanArguments :: SpanArguments

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)

serverSpanArguments :: SpanArguments

defaultSpanArguments with kind set to 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 span that was expected to wait for a response.

clientSpanArguments :: SpanArguments

defaultSpanArguments with kind set to Kind

Indicates that the span describes a synchronous request to some remote service. This span is the parent of a remote Server span and waits for its response.

producerSpanArguments :: SpanArguments

defaultSpanArguments with kind set to Producer

Indicates that the span describes the parent of an asynchronous request. This parent span is expected to end before the corresponding child Producer span, possibly even before the child span starts. In messaging scenarios with batching, tracing individual messages requires a new Producer span per message to be created.

consumerSpanArguments :: SpanArguments

defaultSpanArguments with kind set to Consumer

Indicates that the span describes the child of an asynchronous Producer request.

Querying

withTraceIdContext :: (MonadIO m, MonadMask m) => m a -> m a

getCurrentTraceId :: MonadIO m => m (Maybe TraceId)

getCurrentTraceIdAsDatadog :: MonadIO m => m (Maybe Word64)

getCurrentSpanContext :: MonadIO m => m (Maybe SpanContext)

Attributes

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

Minimal complete definition

Nothing

Methods

toAttribute :: a -> Attribute

Instances

ToAttribute Int64

Defined in OpenTelemetry.Attributes

Methods

toAttribute :: Int64 -> Attribute

ToAttribute CacheKey

Defined in Freckle.App.Memcached.CacheKey

Methods

toAttribute :: CacheKey -> Attribute

ToAttribute CacheTTL

Defined in Freckle.App.Memcached.CacheTTL

Methods

toAttribute :: CacheTTL -> Attribute

ToAttribute Attribute

Defined in OpenTelemetry.Attributes

Methods

toAttribute :: Attribute -> Attribute

ToAttribute PrimitiveAttribute

Defined in OpenTelemetry.Attributes

Methods

toAttribute :: PrimitiveAttribute -> Attribute

ToAttribute Text

Defined in OpenTelemetry.Attributes

Methods

toAttribute :: Text -> Attribute

ToAttribute Bool

Defined in OpenTelemetry.Attributes

Methods

toAttribute :: Bool -> Attribute

ToAttribute Double

Defined in OpenTelemetry.Attributes

Methods

toAttribute :: Double -> Attribute

ToAttribute Int

Defined in OpenTelemetry.Attributes

Methods

toAttribute :: Int -> Attribute

ToPrimitiveAttribute a => ToAttribute [a]

Defined in OpenTelemetry.Attributes

Methods

toAttribute :: [a] -> Attribute

addCurrentSpanAttributes :: MonadIO m => HashMap Text Attribute -> m ()

Setup

withTracerProvider :: MonadUnliftIO m => (TracerProvider -> m a) -> m a

Tracer

makeTracer :: TracerProvider -> InstrumentationLibrary -> TracerOptions -> Tracer

tracerOptions :: TracerOptions

Default Tracer options

Utilities

byteStringToAttribute :: ByteString -> Attribute

Convert a ByteString to an Attribute safely

• Decodes it as UTF-8 leniently,
• Truncates to fit within attributeValueLimit

attributeValueLimit :: Int

Character limit for Attribute values

OTel the spec doesn't specify a limit, but says that SDKs should decide some limit. It's not clear what the Haskell SDK does, if anything. New Relic applies a limit of 4095 characters on all metrics it handles, including those coming from OTel. Seems reasonable enough.

https://docs.newrelic.com/docs/more-integrations/open-source-telemetry-integrations/opentelemetry/best-practices/opentelemetry-best-practices-attributes/