Metrics and tracing

Wrap an effect in a span to see where its time goes and how it failed. Spans nest, follow forked fibers, and cross Fx.rpc calls: a client's call and the server handler it reaches share one trace, in Lua and in JS.

local Deposits = Fx.metrics.counter('bank_deposits_total', { help = 'Deposits made' })
local Latency = Fx.metrics.histogram('bank_deposit_ms', { buckets = { 5, 25, 100, 500 } })

local function deposit(src, amount)
  return Bank.credit(src, amount)
    :tap(function() Deposits:inc(1, { account = 'main' }) end)
    :trackDuration(Latency)
    :withSpan('bank.deposit', { attributes = { amount = amount } })
end


Spans	`eff:withSpan(name, { attributes, kind, parent, root })`, `Fx.span(name, fn)`, `Fx.currentSpan`, `Fx.annotateCurrentSpan(k, v)`; finished spans in `Fx.trace.on(fn)`, `Fx.trace.stream()`, `Fx.trace.recent()`
Metrics	`Fx.metrics.counter / gauge / histogram(name, { help, buckets })` with `inc`, `set`, `add`, `observe` and optional labels; `eff:trackDuration(histogram)`, `eff:trackErrors(counter)`; `Fx.metrics.snapshot()`, `Fx.metrics.prometheus()`
Built in	a span per `Fx.rpc` call and handler, and per `Fx.net.handle` effect; `rivo_fx_rpc_handler_ms`, `rivo_fx_rpc_call_ms`, `rivo_fx_net_events_total`, `rivo_fx_security_events_total`, `rivo_fx_fibers`, `rivo_fx_timers`

Effect logs (Fx.logInfo, ...) carry traceId and spanId, so a log line leads to its trace. A label set that grows past 1000 series per metric (a player id as a label, say) stops adding series instead of eating memory. set rivo_fx:tracing off stops recording spans.

Scraping

The rivo_fx resource serves every resource's metrics, merged and labelled by resource, at http://<server>:30120/rivo_fx/metrics, and the latest spans as JSON at /rivo_fx/spans?limit=100. Both are off until you set a token, and each request must send it:

set rivo_fx:metricsToken "a-long-random-string"   # set, not setr: keep it off clients

# prometheus.yml
scrape_configs:
  - job_name: fivem
    metrics_path: /rivo_fx/metrics
    authorization: { credentials: a-long-random-string }
    static_configs: [{ targets: ['your-server:30120'] }]