DIAL Analytics Enrichment Runner configuration

DIAL Analytics Enrichment Runner uses Spring configuration for upstream connections, scheduling, and runtime limits. This reference is for platform engineers with a matching Analytics deployment. Pipeline definitions remain in Analytics; the runner owns execution state.

Where each setting lives

Place	What it sets	Reference
Runner environment	PostgreSQL, Analytics and Core connections, scheduling, retries, and budgets	Environment variables
External Spring YAML	Identity providers and inbound authorization	Security and observability
Analytics pipeline definition	Source, target, trigger, transform, enabled state, and per-pipeline advanced settings	DIAL Admin: Pipelines
Runner PostgreSQL database	Jobs, cursors, group state, dead letters, history, and spend	Runtime constraints
Admin Frontend environment	Internal runner URL for pipeline runtime controls	DIAL Admin analytics settings

Command-line arguments override system properties, environment variables, and configuration files under Spring Boot precedence. SPRING_CONFIG_ADDITIONAL_LOCATION adds an external YAML file. Durations use Spring syntax, such as 30s or 5m; cron expressions have six fields. See the configuration documentation.

Docker Compose example

This fragment joins the network containing the Analytics fragment, PostgreSQL, and Core. A separate analytics_runner database and its user must already exist. The mounted file contains the OIDC provider configuration. Replace <VERSION> with the image tag that matches your Analytics deployment.

services:
  analytics-enrichment-runner:
    image: epam/ai-dial-analytics-enrichment-runner:<VERSION>
    expose:
      - "5000"
    read_only: true
    tmpfs:
      - /tmp
    environment:
      POSTGRES_HOST: postgres
      POSTGRES_DATABASE: analytics_runner
      POSTGRES_DATASOURCE_USERNAME: analytics_runner
      POSTGRES_DATASOURCE_PASSWORD: "<RUNNER_POSTGRES_PASSWORD>"
      ADAS_BASE_URL: http://analytics:5000
      ADAS_API_KEY: "<ANALYTICS_RUNNER_DIAL_API_KEY>"
      DIAL_BASE_URL: http://core:8080
      DIAL_API_KEY: "<MODEL_CALL_DIAL_API_KEY>"
      SECURITY_MODE: oidc
      API_KEY_ENABLED: "true"
      API_KEY_CORE_URL: http://core:8080
      API_KEY_ROLES_MAPPING: '{"analytics-runner":["FULL_ADMIN"]}'
      SPRING_CONFIG_ADDITIONAL_LOCATION: file:/config/runner.yml
    volumes:
      - ./runner.yml:/config/runner.yml:ro

The outbound Analytics key must belong to a Core project role accepted by Analytics, such as analytics-runner in the companion fragment. Pipelines reading sensitive columns require an Analytics identity with the corresponding clearance. The model-call key needs access to the pipeline's model deployments. Neither key protects the runner's inbound API.

There is no direct ClickHouse connection. The default Analytics HTTP read timeout is 180000 milliseconds, above Analytics' 120s statement budget. Group fetches with several heavy columns may need more headroom. See Upstream settings.

Connect DIAL Admin

Set DIAL_ANALYTICS_RUNNER_API_URL=http://analytics-enrichment-runner:5000 on Admin Frontend alongside its Analytics connection settings. Its server must reach that URL. Both services need providers that accept the forwarded user's token, and the runner requires FULL_ADMIN for every /v1 operation.

Deliberate stopping uses the pipeline's enabled flag in Analytics. POST /v1/pipelines/{name}/pause returns 404, and POST /v1/pipelines/{name}/resume lifts only a circuit-breaker pause. Admin releases exposing the earlier pause API require compatibility review; the setting alone does not adapt those controls.

Paired deployment order

The Analytics and runner instructions prescribe a coordinated deployment:

1. Scale the runner to zero and wait until its old instances have stopped.
2. Deploy the new Analytics version.
3. Deploy the matching runner version.
4. Scale the runner back to one and wait for readiness after its first successful pipeline sync.

During the stop, no runner scans or model calls occur, and enrichment-dependent rollups can lag. A rolling update that overlaps old runner instances with upgraded Analytics does not provide this deployment order.

Warning

Analytics automatically aligns existing row enrichment layouts on upgrade, with no rollback to the earlier layout. Review both Analytics and runner upgrade guides before updating existing data. The upgrade restarts the runner, which clears every pause. To keep a pipeline that an operator paused on purpose stopped, list GET /v1/pipelines/paused and set enabled: false in Analytics for each entry with origin operator before the upgrade.

Verification and troubleshooting

docker compose exec analytics-enrichment-runner wget -qO- http://0.0.0.0:5000/actuator/health/liveness
docker compose exec analytics-enrichment-runner wget -qO- http://0.0.0.0:5000/actuator/health/readiness

Liveness checks the process; readiness includes PostgreSQL and a successful Analytics pipeline sync. The first sync starts after 10000 milliseconds, then polls every 30000 milliseconds. Startup probe allowances must cover the initial delay and at least one polling interval.

Symptom	What to check
Liveness is up but readiness is down	PostgreSQL, Analytics URL, outbound key, initial sync delay, and matching contract versions
An authenticated user receives 403	The runner requires FULL_ADMIN; read-only roles grant no access
Pipeline is enabled but no model calls occur	Trigger, compiled definition sync, Core deployment access, spend gate, circuit breaker, and backlog
Scan, group fetch, or materialize returns 400	Runner maximums must not exceed corresponding Analytics limits
Pipeline read times out repeatedly	Runner ADAS_READ_TIMEOUT_MS must exceed Analytics' statement timeout, including multi-statement group reads
Calls continue beyond a spend budget	Limits are soft enqueue gates; queued or concurrent work can exceed them
Operator pause returns 404	Use Analytics' enabled: false; the runner has no /pause endpoint