Safe Haskell	None
Language	GHC2024

Arbiter.Otel

Contents

Setup
Instrumenting a pool
Running pools
Gauges
Metric names

Description

OpenTelemetry for arbiter: traces, metrics and logs.

Spans and trace-context propagation are built in. This module is the SDK side. runWorkerPools installs the exporters and instruments the pools. The With variants take a handle the caller installed itself.

import Arbiter.Hasql qualified as ArbH
import Arbiter.Otel qualified as Otel
import Arbiter.Worker qualified as Worker

env <- ArbH.createHasqlEnv ...
ArbH.runHasqlDb env $ Otel.runWorkerPools [Worker.namedWorkerPool emailCfg]

Synopsis

data Telemetry = Telemetry {
- meters :: Maybe ArbiterMeters
- provider :: MeterProvider
- telemetryLogDestination :: Maybe LogDestination
- gaugeRefresh :: NominalDiffTime
- telemetrySummary :: Text
}
data ArbiterMeters
withTelemetry :: (Telemetry -> IO a) -> IO a
withTelemetryIf :: Bool -> (Telemetry -> IO a) -> IO a
withTelemetryFromEnv :: (Telemetry -> IO a) -> IO a
withExternalTelemetry :: Maybe MeterProvider -> Maybe LoggerProvider -> (Telemetry -> IO a) -> IO a
telemetryLogConfig :: Telemetry -> LogConfig -> LogConfig
instrumentPool :: forall (m :: Type -> Type). MonadUnliftIO m => Telemetry -> NamedWorkerPool m -> NamedWorkerPool m
instrumentPools :: forall (m :: Type -> Type). MonadUnliftIO m => Telemetry -> [NamedWorkerPool m] -> [NamedWorkerPool m]
instrumentConfig :: forall (m :: Type -> Type) payload. (HasKind payload, KnownSymbol (TableForPayload payload (RegistryOf m)), MonadUnliftIO m) => Telemetry -> WorkerConfig m payload -> WorkerConfig m payload
runWorkerPools :: (MonadArbiter m, RegistryTables (RegistryOf m)) => [NamedWorkerPool m] -> m ()
runWorkerPoolsWith :: (MonadArbiter m, RegistryTables (RegistryOf m)) => Telemetry -> LogConfig -> [NamedWorkerPool m] -> m ()
runSelectedWorkerPools :: (MonadArbiter m, RegistryTables (RegistryOf m)) => [Text] -> [NamedWorkerPool m] -> m ()
runSelectedWorkerPoolsWith :: (MonadArbiter m, RegistryTables (RegistryOf m)) => Telemetry -> LogConfig -> [Text] -> [NamedWorkerPool m] -> m ()
withGauges :: (MonadArbiter m, RegistryTables (RegistryOf m)) => Telemetry -> LogConfig -> m b -> m b
startGauges :: MonadArbiter m => Telemetry -> LogConfig -> (forall a. m a -> IO a) -> Text -> [(Text, [Text])] -> NominalDiffTime -> IO (IO ())
data MetricName
- = JobsClaimed
- | JobsProcessed
- | JobsRetried
- | AdmissionAdmitted
- | MaintenanceRows
- | HandlerDuration
- | QueueDepth
- | QueueDepthByKind
- | QueueOldestReadyAge
- | QueueOldestInFlightAge
- | Workers
- | AdmissionKeys
- | AdmissionLimit
- | AdmissionInFlight
- | AdmissionBusiestKey
- | AdmissionTokens
- | PgTableDeadTuples
- | PgTableLiveTuples
- | PgTableVacuumAge
- | PgTableSize
- | PgTableScans
- | PgTableBlocks
- | PgTableXidAge
- | PgDbConnections
- | PgDbBackends
- | PgDbOldestTransactionAge
- | PgDbOldestQueryAge
- | DbReachable
- | GaugesAge
metricName :: MetricName -> Text
arbiterMetricNames :: [Text]

Setup

data TelemetrySource #

A running telemetry handle: instruments, provider, and resolved settings.

Constructors

Telemetry

Fields

meters :: Maybe ArbiterMeters
Nothing when metrics are off. Then no job instruments and no gauge scan.
provider :: MeterProvider
The meter provider the gauge instruments register on.
telemetryLogDestination :: Maybe LogDestination
An extra destination the logs are copied to. Nothing adds none.
gaugeRefresh :: NominalDiffTime
The metric export interval this handle resolved.
telemetrySummary :: Text
A startup line for the caller to log, with a note for each signal that failed to start.

data ArbiterMetersSource #

The job, admission and maintenance instruments.

withTelemetry :: (Telemetry -> IO a) -> IO aSource #

Bracketed OpenTelemetry init and shutdown. Every signal is the SDK's, resolved from its own OTEL_ variables. withTelemetryFromEnv is the gated form.

withTelemetryIf :: Bool -> (Telemetry -> IO a) -> IO aSource #

withTelemetry when the flag is set. An inert handle when the flag is off.

withTelemetryFromEnv :: (Telemetry -> IO a) -> IO aSource #

withTelemetry, or an inert handle when OTEL_SDK_DISABLED is true.

withExternalTelemetry :: Maybe MeterProvider -> Maybe LoggerProvider -> (Telemetry -> IO a) -> IO aSource #

Run an action with application-owned providers. Missing providers disable their applicable signals.

telemetryLogConfig :: Telemetry -> LogConfig -> LogConfigSource #

Also send the config's logs to this handle's destination. A config that discards its logs still exports them.

Instrumenting a pool

instrumentPool :: forall (m :: Type -> Type). MonadUnliftIO m => Telemetry -> NamedWorkerPool m -> NamedWorkerPool mSource #

Give a pool lifecycle metrics, maintenance metrics, and the telemetry log destination. The pool's registry queue name labels its metrics. Apply it once per pool.

instrumentPools :: forall (m :: Type -> Type). MonadUnliftIO m => Telemetry -> [NamedWorkerPool m] -> [NamedWorkerPool m]Source #

instrumentPool over a pool list.

instrumentConfig :: forall (m :: Type -> Type) payload. (HasKind payload, KnownSymbol (TableForPayload payload (RegistryOf m)), MonadUnliftIO m) => Telemetry -> WorkerConfig m payload -> WorkerConfig m payloadSource #

instrumentPool over a bare config, labelled by the payload's registry queue.

Running pools

runWorkerPools :: (MonadArbiter m, RegistryTables (RegistryOf m)) => [NamedWorkerPool m] -> m ()Source #

runWorkerPools with the SDK installed from the environment, the pools instrumented and the gauges running. Take the handle yourself with runWorkerPoolsWith when something else needs it.

runWorkerPoolsWith :: (MonadArbiter m, RegistryTables (RegistryOf m)) => Telemetry -> LogConfig -> [NamedWorkerPool m] -> m ()Source #

runWorkerPools over a handle the caller installed itself, with the gauge loop's base log config.

runSelectedWorkerPools :: (MonadArbiter m, RegistryTables (RegistryOf m)) => [Text] -> [NamedWorkerPool m] -> m ()Source #

runWorkerPools over an explicit queue list.

runSelectedWorkerPoolsWith :: (MonadArbiter m, RegistryTables (RegistryOf m)) => Telemetry -> LogConfig -> [Text] -> [NamedWorkerPool m] -> m ()Source #

runSelectedWorkerPools over a handle the caller installed itself.

Gauges

withGauges :: (MonadArbiter m, RegistryTables (RegistryOf m)) => Telemetry -> LogConfig -> m b -> m bSource #

Run the registry's depth and health gauges alongside action. Nothing is scanned when the handle has metrics off.

startGauges :: MonadArbiter m => Telemetry -> LogConfig -> (forall a. m a -> IO a) -> Text -> [(Text, [Text])] -> NominalDiffTime -> IO (IO ())Source #

Arguments

:: MonadArbiter m
=> Telemetry
-> LogConfig	Base log config for the loop.
-> (forall a. m a -> IO a)	Runs a database action.
-> Text
-> [(Text, [Text])]	Each queue table and its payload kind labels.
-> NominalDiffTime	Refresh interval. The minimum is one second.
-> IO (IO ())

Register gauge instruments and return their refresh loop. Run the loop on its own thread. It runs until it is stopped. A stopped loop leaves the last readings in place. With metrics off, the loop returns at once.

Metric names

data MetricNameSource #

Every instrument the library registers. A job's kind attribute is absent when its label is not declared.

Constructors

JobsClaimed	Counter, no unit. Attributes: `queue`, `kind`.
JobsProcessed	Counter, no unit. Attributes: `queue`, `outcome` (success, dlq, cancelled, unavailable), `kind`.
JobsRetried	Counter, no unit. Attributes: `queue`, `kind`.
AdmissionAdmitted	Counter, no unit. Attributes: `queue`, `policy_kind`, `policy`.
MaintenanceRows	Counter, no unit. Attributes: `op`.
HandlerDuration	Histogram, `s`. Attributes: `queue`, `outcome` (success, failure), `kind`.
QueueDepth	Gauge, `{job}`. Attributes: `queue`, `status` (ready, blocked, in_flight, scheduled, backoff, throttled, suspended, cancelled, exhausted).
QueueDepthByKind	Gauge, `{job}`. Attributes: `queue`, `kind`.
QueueOldestReadyAge	Gauge, `s`. Attributes: `queue`.
QueueOldestInFlightAge	Gauge, `s`. Attributes: `queue`.
Workers	Gauge, `{worker}`. Attributes: `queue`, `state` (active, paused).
AdmissionKeys	Gauge, `{key}`. Attributes: `policy_kind`, `policy`.
AdmissionLimit	Gauge, `{admission}`, in concurrency slots or rate-limit tokens. Attributes: `policy_kind`, `policy`.
AdmissionInFlight	Gauge, `{job}`. Attributes: `policy`.
AdmissionBusiestKey	Gauge, `{job}`. Attributes: `policy`.
AdmissionTokens	Gauge, `{token}`. Attributes: `policy`, `stat` (min, avg).
PgTableDeadTuples	Gauge, `{tuple}`. Attributes: `table`.
PgTableLiveTuples	Gauge, `{tuple}`. Attributes: `table`.
PgTableVacuumAge	Gauge, `s`. Attributes: `table`.
PgTableSize	Gauge, `By`. Attributes: `table`.
PgTableScans	Counter, `{scan}`. Attributes: `table`, `path` (seq, index).
PgTableBlocks	Counter, `{block}`. Attributes: `table`, `source` (hit, disk).
PgTableXidAge	Gauge, `{transaction}`. Attributes: `table`.
PgDbConnections	Gauge, `{connection}`. Attributes: `state` (active, idle, idle_in_transaction, idle_in_transaction_aborted, blocked, other).
PgDbBackends	Gauge, `{backend}`. No attributes.
PgDbOldestTransactionAge	Gauge, `s`. No attributes.
PgDbOldestQueryAge	Gauge, `s`. No attributes.
DbReachable	Gauge, `1`, 1 when reachable and 0 when not. No attributes.
GaugesAge	Gauge, `s`. No attributes.

Instances

Instances details

Eq MetricName Source #
Instance details Defined in Arbiter.Otel.MetricNames Methods (==) :: MetricName -> MetricName -> Bool# (/=) :: MetricName -> MetricName -> Bool#
Bounded MetricName Source #
Instance details Defined in Arbiter.Otel.MetricNames Methods minBound :: MetricName# maxBound :: MetricName#
Enum MetricName Source #
Instance details Defined in Arbiter.Otel.MetricNames Methods succ :: MetricName -> MetricName# pred :: MetricName -> MetricName# toEnum :: Int -> MetricName# fromEnum :: MetricName -> Int# enumFrom :: MetricName -> [MetricName]# enumFromThen :: MetricName -> MetricName -> [MetricName]# enumFromTo :: MetricName -> MetricName -> [MetricName]# enumFromThenTo :: MetricName -> MetricName -> MetricName -> [MetricName]#
Show MetricName Source #
Instance details Defined in Arbiter.Otel.MetricNames Methods showsPrec :: Int -> MetricName -> ShowS# show :: MetricName -> String# showList :: [MetricName] -> ShowS#

metricName :: MetricName -> TextSource #

The exported name of a metric.

arbiterMetricNames :: [Text]Source #

Every metric name arbiter exports.