DIAL Analytics configuration

DIAL Analytics reads service settings from Spring configuration and stores catalog objects through its API. This reference is for platform engineers with existing Core request logs and database infrastructure. It assumes familiarity with the service dependencies.

Where each setting lives

Place	What it sets	Reference
Container environment	Database connections, blob discovery, ingestion schedules, budgets, and pipeline limits	Environment variables
External Spring YAML	Providers, cursor keyrings, ingestion target lists, and other map or list overrides	Security and observability
ClickHouse server configuration	Encryption codec key, users, grants, and storage settings	Database prerequisites
Analytics catalog API	Tables, schemas, grants, saved queries, dashboards, and pipeline definitions	DIAL Admin: Analytics
DIAL Admin environment	Analytics menu switches and internal service URLs	Connect DIAL Admin

Configuration uses Spring Boot precedence: command-line arguments override system properties, environment variables, and configuration files. SPRING_CONFIG_ADDITIONAL_LOCATION=file:/config/analytics.yml adds an external file. List overrides replace the corresponding list, including sync.targets; unspecified entries are not appended automatically. See the configuration documentation.

Database prerequisites

ClickHouse 25.3 LTS or newer is required; native AI query functions additionally require 26.8. The reader needs SELECT on exposed tables. The writer needs SELECT, INSERT, CREATE TABLE, ALTER, and DROP TABLE for the full service surface. The writer also needs SELECT on system.parts and system.data_skipping_indices: without them the enrichment relayout fails, the lookup index is never added, and a schema PATCH that drops a column fails.

For grants scoped per table, include the ingestion ledger _dial_internal_ingested_blob and failure ledger _dial_internal_failed_ingest. Startup migrations need DDL rights; removing those rights without provisioning schemas separately prevents startup. The ClickHouse requirements provide the complete grant matrix.

Payload body columns and rating comments require an AES-256-GCM-SIV codec key in ClickHouse's config.d:

<clickhouse>
  <encryption_codecs>
    <aes_256_gcm_siv>
      <key_hex>&lt;CLICKHOUSE_ENCRYPTION_KEY_HEX&gt;</key_hex>
    </aes_256_gcm_siv>
  </encryption_codecs>
</clickhouse>

Replace the placeholder with a 64-character hexadecimal secret supplied during deployment. The key must remain available to read existing encrypted columns. See the server-side encryption requirement.

PostgreSQL stores the catalog and audit history. Its user needs schema migration permissions unless POSTGRES_MIGRATIONS_ENABLED=false and the schema is provisioned separately. The runner needs its own database, rather than sharing this catalog schema.

Log blob layout

Analytics reads gzip-compressed usage logs from one blob container or bucket and finds them from the date alone, so the producer's layout must match the settings below. The defaults describe DIAL Core's own layout.

Part	Setting	Default
Container or bucket	`BLOB_BUCKET`	`logs`
Base path	`SYNC_PATH_PREFIX`	`logs`
Date directory	`SYNC_DATE_PATH_PATTERN`	`yyyy/MM/dd`
File name prefix, followed by an embedded epoch	`SYNC_FILE_NAME_PREFIX_PATTERN`	`'date='yyyy-MM-dd`

The same settings govern the daily run, the poller, and operator backfills. A mismatch does not fail: Analytics silently discovers nothing. The patterns are defined in Data sync schedule. How Core's logs reach the container is described in Send usage logs to blob storage.

Docker Compose example

This fragment assumes ClickHouse, PostgreSQL, and Core already run on the same network. The ClickHouse encryption key and database users must already exist. Both PostgreSQL databases must be provisioned before adding the runner fragment.

The mounted analytics.yml contains the provider configuration. The environment placeholders represent credentials from the deployment's secret store, and <VERSION> is an image tag from Docker Hub. This is a service fragment, rather than a complete DIAL assembly.

services:
  analytics:
    image: epam/ai-dial-analytics:<VERSION>
    expose:
      - "5000"
      - "9464"
    environment:
      CLICKHOUSE_HOST: clickhouse
      CLICKHOUSE_DATABASE: analytics
      CLICKHOUSE_USER: analytics_reader
      CLICKHOUSE_PASSWORD: "<CLICKHOUSE_READER_PASSWORD>"
      CLICKHOUSE_WRITER_USER: analytics_writer
      CLICKHOUSE_WRITER_PASSWORD: "<CLICKHOUSE_WRITER_PASSWORD>"
      POSTGRES_HOST: postgres
      POSTGRES_DATABASE: analytics_catalog
      POSTGRES_DATASOURCE_USERNAME: analytics
      POSTGRES_DATASOURCE_PASSWORD: "<POSTGRES_PASSWORD>"
      BLOB_PROVIDER: azureblob
      BLOB_BUCKET: logs
      BLOB_ENDPOINT: "https://<STORAGE_ACCOUNT>.blob.core.windows.net"
      BLOB_IDENTITY: "<STORAGE_ACCOUNT>"
      BLOB_CREDENTIAL: "<STORAGE_ACCOUNT_KEY>"
      ENRICHMENT_CURSOR_SECRET: "<CURSOR_SIGNING_SECRET>"
      MANAGEMENT_SERVER_PORT: "9464"
      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/analytics.yml
    volumes:
      - ./analytics.yml:/config/analytics.yml:ro

BLOB_BUCKET and the SYNC_* discovery patterns must match the actual producer. For Azure managed identity, omit the shared-key pair and provide workload identity and reader access. For S3, use BLOB_PROVIDER=aws-s3 and a region-specific endpoint. See Blob source.

Port 9464 is explicitly configured here; it is not the service's default management port. expose makes no host port mapping; checks can run inside the container.

Connect DIAL Admin

Deploy Analytics with reachable databases and blob storage. Configure OIDC providers to validate the tokens forwarded by Admin.
Set the Admin Frontend variables below, using the service URL reachable from its server.
Configure a matching Enrichment Runner for enrichment pipelines and their runtime controls.
Check ingestion, then query an available table in DIAL Admin: Queries.

ANALYTICS_ENABLED=true
DIAL_ANALYTICS_API_URL=http://analytics:5000
ANALYTICS_USAGE_ENABLED=true
ANALYTICS_SESSIONS_ENABLED=true
DIAL_ANALYTICS_RUNNER_API_URL=http://analytics-enrichment-runner:5000

These are Admin Frontend settings, not Analytics settings. Their complete reference, including query assistance and public connection URLs, is DIAL Admin analytics settings. Enabling them does not deploy the backing services.

Initialize the recommended catalog

Fresh installations need the catalog bundle for Sessions and evaluation baggage data. The bundle contains definitions, not data, table grants, or runner state. Its SQL enrichments make no model calls.

Confirm dial_usage_log and dial_usage_log_payload are active after migrations.
Import the bundle through DIAL Admin's configuration import workflow. Review the preview before confirming; existing objects are retained.
Grant table access, accounting for sensitive email and display-name columns.
Enable usage-client-identity-live and usage-request-baggage-live, then sessions_rollup.
Wait for enrichment and aggregate pipelines to catch up before checking Sessions.

The dependency order is specified in the recommended catalog instructions. The first Sessions rollup rescans historical usage, so initialization can require additional processing time.

Verification and troubleshooting

docker compose exec analytics wget -qO- http://0.0.0.0:9464/actuator/health/readiness

An UP response confirms application readiness and PostgreSQL connectivity. It does not prove blob ingestion or ClickHouse query access. Check both through the data and Queries screens after logs arrive.

Symptom	What to check
Startup fails during ClickHouse migration	Encryption codec key, the writer credential (migrations authenticate only as the writer), writer DDL rights, and both internal ledger tables
No new usage rows	Blob credentials, bucket, discovery patterns, producer output, and data-sync failures
Sessions is empty	Recommended catalog import, active payload table, enabled enrichment pipelines, runner readiness, and rollup progress
A query returns `401` or `403`	Issuer, audience, role mapping, table grants, and sensitive-column clearance
Pipeline reads time out	Keep runner HTTP read timeout above the Analytics pipeline statement budget, with group-fetch headroom
Runner reports contract mismatch	Deploy both services at the matching version using the paired deployment order

Where each setting lives​

Database prerequisites​

Log blob layout​

Docker Compose example​

Connect DIAL Admin​

Initialize the recommended catalog​

Verification and troubleshooting​