You're viewing the docs for Flags 0.x. The latest is 1.x (rc). Go to the 1.x (rc) docs
Events and Analytics
Where exposures and conversions go — transports, sinks, and the Postgres, Parquet/DuckDB and ClickHouse analytics backends.
Exposures and tracked events are buffered in the process, written to a transport (a log), and a relay delivers them to every sink at its own pace. The defaults need nothing but your database:
import { defineConfig, sinks, transports, analytics } from '@adonis-agora/flags'
export default defineConfig({
flags: { /* … */ },
transport: transports.db(), // the default with Lucid
sinks: { warehouse: sinks.lucid() }, // the default with Lucid
analytics: analytics.lucid(), // the default when the lucid sink exists
})Transports
| Transport | Notes |
|---|---|
transports.db() | A table in your database. The only one that writes inside your transaction (track(…, { client: trx })). Default |
transports.redis({ connection }) | Redis Streams, one consumer group per sink. Needs @adonisjs/redis |
transports.queue({ queue, adapter }) | Jobs on @adonisjs/queue, run by node ace queue:work. No relay, no replay. Needs @adonisjs/queue |
transports.memory() | Tests and development |
Delivery is at-least-once; every sink ignores duplicates. Events older than retentionDays (default 30) are pruned once every sink has them. On Postgres, partitionEvents: true partitions the log by month so pruning drops partitions — decide before the first boot.
The queue transport
Pick it when your app already runs @adonisjs/queue workers and you don't want to run anything else for flags. Each batch becomes one job per sink, so a sink that is down retries on its own while the others keep receiving events.
import { exponentialBackoff } from '@adonisjs/queue'
transport: transports.queue({
queue: 'flags', // default: the `default` queue
adapter: 'redis', // default: the queue's default adapter
maxRetries: 10, // default 10
backoff: exponentialBackoff({ baseDelay: '1s', maxDelay: '5m' }), // the default
}),node ace queue:work --queue=default,flagsWhat you give up compared to db and redis:
- No replay. A job is gone once it ran, so
node ace flags:replayis not available, and a sink you add later only receives new events. - Not transactional.
track(…, { client: trx })sends the event after the commit, and it is lost if the process dies in between. - No per-sink lag in the console. Pending, retried and failed batches are in your queue; batches that run out of attempts stay in its storage (
keepFailed: falseremoves them) and are logged. - Durable as your queue adapter is. Redis or database: yes.
sync: events are delivered inline, in the request.
Don't run node ace flags:work --sink: there is no relay. flags:work still runs scheduled changes and experiment results.
Sinks
sinks: {
warehouse: sinks.lucid(),
archive: sinks.parquet({ path: 'storage/flags' }),
clickhouse: sinks.clickhouse({ url: env.get('CLICKHOUSE_URL'), username: 'flags', password: env.get('CLICKHOUSE_PASSWORD') }),
posthog: sinks.posthog({ apiKey: env.get('POSTHOG_KEY') }),
webhook: sinks.callback(async (events) => { /* … */ }),
}Adding a sink later delivers the retained log to it from the beginning. node ace flags:replay <sink> sends it again.
Choosing an analytics backend
| Level | Backend | When |
|---|---|---|
| 1 | analytics.lucid() | Up to tens of millions of events a month |
| 2 | analytics.duckdb({ path }) + sinks.parquet({ path }) | Long retention, no server. Parquet on disk or S3 |
| 3 | analytics.clickhouse({ … }) + sinks.clickhouse({ … }) | High volume, fast queries |
All three return the same numbers for the same data: the database only aggregates, the statistics are computed in one place.
@duckdb/node-api is an optional dependency with a native binary. Run the relay for the Parquet sink in a worker (see Deployment), not in web processes.
Erasure
node ace flags:forget <subject-id>await flags.forget(user)Deletes the subject's events and exposures from the log and from every sink that supports it (lucid, ClickHouse, local Parquet files). PostHog erasure goes through PostHog itself. With transports.queue(), batches still waiting in the queue are not touched: run forget again once they are delivered.
Observability
With @adonis-agora/diagnostics installed, flags publish four events on agora:flags:<event>:
| Event | When | Payload |
|---|---|---|
evaluation | A flag is read | flag, variant, reason, errorCode, subject |
exposure | An experiment flag is read | The exposure event |
track | track() records a conversion | The track event |
change | The console, a command, an approval or a schedule changes the ruleset | environment, version, entity, key, deleted, actor, changeRequestId |
The diagnostics OpenTelemetry bridge adds them to the active span, and you can listen to them:
import { onDiagnostic } from '@adonis-agora/diagnostics'
onDiagnostic('flags', 'change', (event) => {
logger.info({ ...event.payload }, 'flag changed')
})change fires in the process that made the change. Other processes pick the new ruleset up without publishing it again.
On a central server, each event is published once. The tenant app publishes its evaluations, with app set to tenant.partition. The control plane publishes the exposures and tracks it receives from tenants, with app set to the tenant, so the tenant does not publish them itself. Set diagnostics: 'local' in the tenant's config/flags.ts to have it publish them too, for example when the control plane does not run diagnostics:
onDiagnostic('flags', 'track', (event) => {
metrics.increment('conversions', { app: event.app })
})For OpenTelemetry's feature-flag attributes (feature_flag.key, feature_flag.result.variant…) and Sentry flag context, add enrichers:
import * as Sentry from '@sentry/node'
import { enrichers } from '@adonis-agora/flags'
enrichers: [enrichers.otel(), enrichers.sentry(Sentry)]enrichers.otel() records evaluations as feature_flag.evaluation span events and takes them over from the diagnostics bridge, so each evaluation appears on the span once. It needs @opentelemetry/api, and works without diagnostics.