DIAL Analytics Enrichment Runner environment variables

This reference covers environment variables for platform engineers operating DIAL Analytics Enrichment Runner. It assumes the service connections are configured.

Defaults

Defaults come from the application.yml and configuration documentation. — means no configured value. Actual defaults containing localhost are reproduced unchanged; container deployments need reachable service names.

Container environment

Source: configuration reference.

Variable	Default	Description
USE_SYSTEM_CA_CERTS	—	Any non-empty value (1, true, yes) imports certificates mounted into /certificates/ at startup.
JAVA_OPTS	—	Extra JVM arguments appended to the launch command.
DEBUG_OPTS	—	JVM debug arguments, applied before JAVA_OPTS.
SPRING_CONFIG_ADDITIONAL_LOCATION	—	External YAML/properties location overriding any property here.

Server

Source: configuration reference.

Variable	Default	Description
HTTP_PORT	5000	Port the runner serves HTTP on—functional endpoints under /v1, operational under /actuator/*. The dial-extension chart's container port.
SHUTDOWN_TIMEOUT	30s	On SIGTERM the server stops accepting requests and waits this long for in-flight work before forcing exit.

PostgreSQL

Source: configuration reference.

Variable	Default	Description
POSTGRES_HOST	localhost	Required for deployment. PostgreSQL host.
POSTGRES_PORT	5432	PostgreSQL port.
POSTGRES_DATABASE	testdb	Required for deployment. Database name.
POSTGRES_OPS	—	Extra JDBC query options appended after ?, for example sslmode=require.
POSTGRES_DATASOURCE_USERNAME	postgres	Required for deployment. Datasource user. Needs DDL on its own schema when migrations are enabled.
POSTGRES_DATASOURCE_PASSWORD	postgres	Required for deployment. Password for that user. Supply from the deployment's secret store.
POSTGRES_MIGRATIONS_ENABLED	true	Run the Flyway migrations under classpath:db/migration/postgres at startup. Disable only when the schema is provisioned out of band.

Job scheduler (db-scheduler)

Source: configuration reference.

Variable	Default	Description
DB_SCHEDULER_HEARTBEAT	45s	How often a running execution updates its heartbeat. Tuned below the library default so a crashed replica's in-flight work is revived promptly.
DB_SCHEDULER_POLLING_INTERVAL	10s	How often the scheduler polls for due executions.
DB_SCHEDULER_THREADS	3	Worker threads consuming due executions. Keep threads × ADAS's 2 GiB read ceiling under ClickHouse's free memory; 8 GiB fits 3, 16 GiB fits 5.
DB_SCHEDULER_AUTO_START	true	Whether the scheduler starts polling on application start.

ADAS

Source: configuration reference.

Variable	Default	Description
ADAS_BASE_URL	http://localhost:5000	Required for deployment. ADAS base URL.
ADAS_API_KEY	—	Required for deployment. DIAL Api-Key presented to ADAS. Supply from the deployment's secret store.
ADAS_CONNECT_TIMEOUT_MS	5000	HTTP connect timeout for ADAS calls.
ADAS_READ_TIMEOUT_MS	180000	HTTP read timeout for ADAS calls. Must stay above ADAS's PIPELINE_BUDGET_TIMEOUT; equal values let a refusal race a socket timeout.
ADAS_PIPELINES_POLL_INTERVAL_MS	30000	How often the runner polls GET /v1/pipelines?kind=enrich&view=compiled to refresh the pipeline cache and reconcile recurring tasks.
ADAS_PIPELINES_INITIAL_DELAY_MS	10000	Delay before the first sync. Readiness reports DOWN until that sync succeeds, so size a startup probe for this plus at least one poll interval.

DIAL Core

Source: configuration reference.

Variable	Default	Description
DIAL_BASE_URL	http://localhost:5000	Required for LLM transforms. DIAL Core base URL.
DIAL_API_KEY	ADAS_API_KEY	DIAL Api-Key for chat/completions. Leave unset when one key serves both; supply from the deployment's secret store otherwise.
DIAL_API_VERSION	2025-01-01-preview	The api-version query parameter on every chat/completions call. Core forwards the query string verbatim and the Azure-OpenAI-compatible adapters reject a request without it, so match what the target deployment's adapter expects. Blank omits the parameter.
DIAL_CONNECT_TIMEOUT_MS	5000	HTTP connect timeout for DIAL calls.
DIAL_READ_TIMEOUT_MS	60000	HTTP read timeout for DIAL calls.
DIAL_DEFAULT_RPM	60	Per-pipeline requests per minute when a pipeline declares no advanced.rate_rpm. Per-process, so DIAL Core's own per-key limit is the real backstop.
DIAL_RATE_LIMITER_TIMEOUT	5s	How long a worker waits for a rate-limit permit before failing the chunk, which then retries with backoff.

Scan

Source: configuration reference.

Variable	Default	Description
SCAN_DEFAULT_SCAN_LIMIT	1000	Scan page size when a pipeline declares no advanced.rows_per_scan.
SCAN_MAX_SCAN_LIMIT	10000	Ceiling the runner clamps a page to. Keep at or below ADAS's own enrichment.scan.max-limit—ADAS answers an over-limit scan with 400 rather than clamping it.
SCAN_DEFAULT_CHUNK	25	Work-item chunk size when a pipeline declares no advanced.rows_per_call.
SCAN_MAX_INFLIGHT	1000	Backpressure: while the pipeline's pending and delayed work items (enrichment chunks, group chunks, and row upserts) exceed this, scan fires are skipped and the group readiness sweep enqueues nothing.
SCAN_MAX_PAGES_PER_FIRE	50	Per-fire drain budget—at most this many pages per scheduled fire. Shared with the Class-1 lane.

Worker

Source: configuration reference.

Variable	Default	Description
WORKER_REPAIR_RETRIES	1	How many times an invalid model response is re-requested, with the validation error as a corrective message, before the row is dead-lettered.
WORKER_ROW_PARALLELISM	4	Rows evaluated concurrently within one chunk; 1 is sequential.
WORKER_MAX_ATTEMPTS	5	Consecutive failures retried before a chunk is archived to the DLQ. The same limit applies to group items and write-back retries.
WORKER_BACKOFF_BASE	10s	Base delay for exponential backoff with jitter between chunk retries.

SQL materialize

Source: configuration reference.

Variable	Default	Description
CLASS1_DEFAULT_LIMIT	10000	Window size in source rows when a pipeline declares no advanced.rows_per_scan.
CLASS1_MAX_LIMIT	100000	Ceiling the runner clamps a window to. Keep at or below ADAS's own enrichment.materialize.max-limit—ADAS rejects an over-limit request rather than clamping it.

Group enrichment

Source: configuration reference.

Variable	Default	Description
GROUP_SCAN_CADENCE	1m	Fixed delay of a group pipeline's mark scan. At least 1s, or startup fails. Keep it well below ready_when.idle and GROUP_DEFAULT_IDLE. Later rows remain unmarked for up to one cadence, which can make active groups appear idle and trigger repeated evaluation. Sync WARNs once per generation for a group pipeline whose effective idle window is under twice this. Keep it the same on every replica: each poll rewrites a stored schedule that differs, so mixed values flap.
GROUP_SWEEP_INTERVAL	30s	How often the readiness sweep runs. Sweeping more often than groups change is harmless: work items are keyed by group version, so a re-sweep of an unchanged group is suppressed.
GROUP_SWEEP_INITIAL_DELAY	15s	Delay before the first sweep, so the first pipeline sync completes before groups are swept.
GROUP_SWEEP_BATCH	500	Maximum groups one sweep pass enqueues per pipeline, so a large dirty backlog cannot monopolise a single pass.
GROUP_MAX_INFLIGHT	0	Ceiling on one group pipeline's pending work (compute plus write-back); the sweep defers the rest. 0 derives it as DB_SCHEDULER_THREADS × 10.
GROUP_EVICTION_CRON	0 30 3 * * *	Schedule for evicting quiet groups from group_state.
GROUP_EVICTION_MARGIN	7d	Grace added on top of a pipeline's readiness window before its quiet, clean groups may be evicted. A dirty group is never evicted.
GROUP_DEFAULT_IDLE	10m	Idle window when a pipeline declares no ready_when.idle. Applies to a signal-only pipeline too, as the backstop that gets a never-signalled group evaluated and eventually evicted.
GROUP_FETCH_LIMIT	200	Members requested per group. Keep at or below ADAS's own enrichment.group-fetch.max-rows—ADAS rejects a larger value rather than clamping it.
GROUP_INPUT_TOKEN_BUDGET	60000	Approximate token ceiling on a group's assembled input, applied on top of ADAS's row and byte caps; 0 disables the runner's own trimming. Tune against runner_group_input_budget_cut_total, not against the truncated rate, which a narrowing member_select also sets.

Spend

Source: configuration reference.

Variable	Default	Description
SPEND_PAUSE_ENABLED	false	Skip a pipeline at enqueue once its daily spend reaches a configured budget.
SPEND_BUDGET_DAILY_CALLS	0	Set this budget, the token budget, or both when SPEND_PAUSE_ENABLED is true. Maximum successful DIAL calls per pipeline per day; failed calls are counted separately and not charged. 0 is unlimited.
SPEND_BUDGET_DAILY_TOKENS	0	Set this budget, the calls budget, or both when SPEND_PAUSE_ENABLED is true. Maximum token usage per pipeline per day; 0 is unlimited.

Dead-letter queue and circuit breaker

Source: configuration reference.

Variable	Default	Description
DLQ_RETENTION_DAYS	30	How long dead-lettered items and their raw responses are kept before the TTL sweep deletes them. This is the only place derived content persists.
DLQ_SWEEP_CRON	0 0 3 * * *	Cron schedule for the DLQ TTL sweep.
DLQ_BREAKER_THRESHOLD	500	Absolute dead-letter count within one scan page or worker chunk that auto-pauses the pipeline. Non-positive disables this lever.
DLQ_BREAKER_FRACTION	0.5	Fraction that must be dead-lettered to auto-pause: of a scan page or worker chunk on the row lane, of the recent-outcome window on the group lane. Non-positive disables this lever.
DLQ_BREAKER_GROUP_WINDOW	50	How many of a pipeline's most recent group outcomes the fraction is measured over. The window must be full before it can trip, so this is also the minimum sample; 0 disables auto-pause for group pipelines
DLQ_BREAKER_PAUSE_FOR	15m	How long the first auto-pause of a pipeline lasts before it resumes itself; each consecutive auto-pause doubles it. 0 disables expiry.
DLQ_BREAKER_PAUSE_MAX	4h	Ceiling on that doubling.

Runtime constraints

The runner owns a PostgreSQL database separate from the Analytics catalog; both can share a PostgreSQL server. It connects to ClickHouse only through Analytics. Pipeline advanced settings (rows_per_scan, rows_per_call, rate_rpm, and sample_fraction) override the matching scan, batch, and rate defaults for one pipeline. WORKER_* settings have no per-pipeline override, and maximum limits still apply. Runner scan, materialize, and group-fetch limits must not exceed the corresponding Analytics limits.

ADAS_READ_TIMEOUT_MS must exceed Analytics' PIPELINE_BUDGET_TIMEOUT, including headroom for multi-statement group fetches. Scheduler threads and row parallelism share the datasource's connection pool. Concurrency also multiplies ClickHouse memory demand and model requests. DIAL_DEFAULT_RPM is per process; Core's per-key limits provide a shared limit across replicas.

Warning

Spend limits are disabled by default. Enabling SPEND_PAUSE_ENABLED requires a nonzero calls or tokens budget to have any effect. These are soft daily gates; queued work and concurrent calls can exceed them. Dead-letter entries include raw responses and expire after DLQ_RETENTION_DAYS.

Spend totals cover all generations of a pipeline within the same UTC day. Editing its definition does not reset those totals; the daily rollover releases the budget gate. Circuit-breaker pauses expire automatically unless their duration is 0; restarting clears the in-memory pauses. Deliberate stopping uses enabled: false in Analytics and retains queued work. POST /v1/pipelines/{name}/resume lifts a circuit-breaker pause; POST /v1/pipelines/{name}/pause is removed. Backfill runs keep POST /v1/backfills/{runId}/pause and /resume.

Further reading

• Security and observability — companion settings reference
• DIAL Admin analytics settings — frontend feature switches and service URLs