Safe Haskell	Safe-Inferred
Language	Haskell2010

Freckle.App.OpenTelemetry

Contents

Effects
Querying
Setup
- Tracer
- Utilities

Description

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.

Synopsis

class HasTracer s where
- tracerL :: Lens' s Tracer
data Tracer
class Monad m => MonadTracer (m :: Type -> Type) where
- getTracer :: m Tracer
inSpan :: (MonadUnliftIO m, MonadTracer m, HasCallStack) => Text -> SpanArguments -> m a -> m a
defaultSpanArguments :: SpanArguments
serverSpanArguments :: SpanArguments
clientSpanArguments :: SpanArguments
producerSpanArguments :: SpanArguments
consumerSpanArguments :: SpanArguments
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)
withTracerProvider :: MonadUnliftIO m => (TracerProvider -> m a) -> m a
makeTracer :: TracerProvider -> InstrumentationLibrary -> TracerOptions -> Tracer
tracerOptions :: TracerOptions
byteStringToAttribute :: ByteString -> Attribute
attributeValueLimit :: Int

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

Instances details

Show Tracer
Instance details 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

Instances details

HasTracer app => MonadTracer (AppExample app) Source #
Instance details Defined in Freckle.App.Test Methods getTracer :: AppExample app Tracer #
(Monad m, HasTracer app) => MonadTracer (AppT app m) Source #
Instance details Defined in Freckle.App Methods getTracer :: AppT app m Tracer #
MonadTracer m => MonadTracer (IdentityT m)
Instance details Defined in OpenTelemetry.Trace.Monad Methods getTracer :: IdentityT m Tracer #
MonadTracer m => MonadTracer (ReaderT r m)
Instance details 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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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

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

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

Setup

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

`Tracer`

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

tracerOptions :: TracerOptions #

Default Tracer options

Utilities

byteStringToAttribute :: ByteString -> Attribute Source #

Convert a ByteString to an Attribute safely

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

attributeValueLimit :: Int Source #

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/