DIAL Analytics Enrichment Runner security and observability

This reference covers security and observability 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.

Warning

SECURITY_MODE=none disables authentication and authorization. Use oidc before exposing the service on a shared network.

Logging

Source: configuration reference.

Variable	Default	Description
APP_LOG_LEVEL	INFO	Log level for the application package (TRACE/DEBUG/INFO/WARN/ERROR).
LOGGER_STATUS_LOG_LEVEL	WARN	Level of Log4j2's own internal status logger (configuration diagnostics).
LOG_CONFIG_PATH	/app/log-config/logging.levels.json	Runtime level file (below). A file that never existed changes nothing; removing an applied file reverts its loggers to their baseline.
LOG_CONFIG_INTERVAL	10s	How often the level file is re-read; at least 1s.
EXECUTION_TRACE_ENABLED	true	Call tracing for @LogExecution classes, active only while a class's logger is at TRACE.
STATUS_REPORT_INTERVAL	5m	How often each pipeline logs its status line.

API documentation

Source: configuration reference.

Variable	Default	Description
API_DOCS_ENABLED	true	Serve the OpenAPI document at /v3/api-docs; false also disables the UI, which is rendered from it.
SWAGGER_UI_ENABLED	true	Serve the Swagger UI at /swagger-ui.html, keeping the OpenAPI JSON available.
DISABLE_SWAGGER_AUTHORIZATION	false	Serve the OpenAPI document and Swagger UI without a credential in oidc mode. They map every functional endpoint, so leave it false wherever the runner is broadly reachable.

OpenTelemetry

Source: configuration reference.

Variable	Default	Description
OTEL_EXPORT_ENABLED	false	Master switch for OTLP export of traces, logs and metrics.
OTEL_TRACES_EXPORT_ENABLED	OTEL_EXPORT_ENABLED	Export spans over OTLP.
OTEL_LOGS_EXPORT_ENABLED	OTEL_EXPORT_ENABLED	Export application logs over OTLP.
OTEL_METRICS_EXPORT_ENABLED	OTEL_EXPORT_ENABLED	Export metrics over OTLP, additively to the Prometheus endpoint.
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:4318	Required if any export is enabled. Collector base URL, no trailing slash. The default points at localhost.
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	base + /v1/traces	Full traces URL; overrides the base for this signal.
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	base + /v1/logs	Full logs URL; overrides the base for this signal.
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT	base + /v1/metrics	Full metrics URL; overrides the base for this signal.
OTEL_EXPORTER_OTLP_PROTOCOL	http	Transport for all three signals: http or grpc.
OTEL_TRACES_SAMPLING_PROBABILITY	1.0	Probability (0.0–1.0) that a new trace is sampled.
OTEL_METRICS_EXPORT_INTERVAL	60s	How often accumulated metrics are flushed. Traces and logs are batched by the SDK's own defaults and have no equivalent knob.
OTEL_SERVICE_NAME	analytics-enrichment-runner	service.name resource attribute reported to telemetry backends.

Authentication

Source: configuration reference.

Variable	Default	Description
SECURITY_MODE	none	Required if the service is exposed. oidc enforces authentication and role-based authorization; none permits every request. Must be exactly one of those two, lowercase.
SECURITY_REQUIRE_EMAIL	false	Reject a caller whose identity carries no resolvable email claim. A DIAL project key is exempt, being a service identity Core returns no email for. oidc only.
SECURITY_ROLES_MAPPING	{"ConfigAdmin":["FULL_ADMIN"],"admin":["FULL_ADMIN"]}	Default JSON mapping of provider role names to application roles (FULL_ADMIN / READ_ONLY_ADMIN), merged under each provider's own mapping. Also used for JWT-rooted API keys. A role with no entry is dropped. oidc only.
SECURITY_EMAIL_CLAIM	unique_name	Default claim to read the caller's email from when a provider sets none. oidc only.
SECURITY_USER_CLAIM	oid	Default claim used as the authenticated principal name when a provider sets none. Note the name mismatch between variable and property. oidc only.

Identity provider properties

These map entries have no fixed environment-variable names. See Provider configuration.

Source: configuration reference.

Property	Default	Description
providers.<name>.issuer	—	Required for JWT providers. Expected iss claim (a URL), or a tenant id when aliases is set.
providers.<name>.jwk-set-uri	—	Required for JWT providers. JWKS endpoint for the provider's signing keys. With issuer, marks the provider as a JWT provider.
providers.<name>.user-info-endpoint	—	Required for opaque providers. OIDC userinfo endpoint introspected for opaque tokens. Marks the provider as an opaque provider.
providers.<name>.audiences	—	Required for JWT providers. Accepted aud values; an api://-prefixed variant of each is also accepted. Not applicable to opaque providers.
providers.<name>.role-claims	—	Required for deployment. Dotted claim paths to read provider role names from (roles, resource_access.roles). For opaque providers these read the userinfo response. A single fn:-prefixed entry selects a role converter instead.
providers.<name>.email-claims	—	Claim names to read the caller's email from, tried in order; falls back to SECURITY_EMAIL_CLAIM.
providers.<name>.principal-claim	—	Claim used as the principal name; falls back to SECURITY_USER_CLAIM.
providers.<name>.roles-mapping	—	JSON mapping of this provider's role names to application roles, merged over SECURITY_ROLES_MAPPING.
providers.<name>.aliases	—	Host aliases used to expand Azure v1/v2 issuer URLs from a tenant id in issuer. JWT providers.

Opaque token introspection

Source: configuration reference.

Variable	Default	Description
OPAQUE_TOKEN_CACHE_TTL_SECONDS	60	TTL for cached successful introspections, and the worst-case revocation window. 0 disables caching; must not be negative.
OPAQUE_TOKEN_CACHE_MAX_SIZE	10000	Maximum cached introspection entries. Must not be negative.
OPAQUE_TOKEN_REQUEST_TIMEOUT_MS	3000	Connect and read timeout for the userinfo call. Must be greater than zero—startup fails otherwise, because 0 means no timeout rather than the fastest one.

API-key authentication

Source: configuration reference.

Variable	Default	Description
API_KEY_ENABLED	false	Master switch. Only takes effect in oidc mode.
API_KEY_CORE_URL	—	Required if API_KEY_ENABLED is true. DIAL Core base URL, for example http://core:8080. Keys are introspected against <core-url>/v1/user/info.
API_KEY_ROLES_MAPPING	—	Required for project-key callers. JSON mapping of Core project-key role names to application roles, for example {"admin":["FULL_ADMIN"]}. There is no fallback: unset, a project key authenticates and is then refused 403. Startup fails only when neither this nor SECURITY_ROLES_MAPPING maps any role.
API_KEY_CACHE_TTL_SECONDS	60	TTL for cached successful introspections. Also bounds how long a key revoked in Core keeps working.
API_KEY_CACHE_MAX_SIZE	10000	Maximum cached introspection entries.
API_KEY_REQUEST_TIMEOUT_MS	3000	Connect and read timeout for the Core introspection call.
API_KEY_STARTUP_PROBE	false	Probe Core reachability at startup and fail fast if unreachable, catching a wrong API_KEY_CORE_URL at once. Off by default so an unreachable Core does not stop the runner starting; enable it only with generous startup-probe headroom, or a Core outage surfaces as a CrashLoopBackOff.

Provider configuration

Providers are configured in an external YAML file through SPRING_CONFIG_ADDITIONAL_LOCATION. Every provider needs role claims. JWT providers also need an issuer, JWKS URL, and accepted audiences. Opaque providers use a userinfo endpoint. JWT-shaped tokens require a JWT provider; there is no opaque-token fallback.

providers:
  keycloak:
    issuer: https://<KEYCLOAK_HOST>/realms/dial
    jwk-set-uri: https://<KEYCLOAK_HOST>/realms/dial/protocol/openid-connect/certs
    audiences: [dial-admin-console]
    role-claims: [roles]
    email-claims: [email]
    principal-claim: sub
    roles-mapping: '{"admin":["FULL_ADMIN"]}'

The issuer and audience must match the access token presented by DIAL Admin. Provider mappings override matching entries in SECURITY_ROLES_MAPPING. Environment binding removes property-name dashes: PROVIDERS_KEYCLOAK_JWKSETURI, rather than PROVIDERS_KEYCLOAK_JWK_SET_URI.

fn:getGoogleWorkspaceGroups can replace the role-claim paths as a single entry, only on a provider with a user-info-endpoint; on any other provider, startup fails. It requires Cloud Identity API access, a resolvable email, and a token permitting group-membership reads. Only direct memberships on the first result page are read; nested groups do not grant access.

Credentials and endpoint exposure

API_KEY_ENABLED applies only in oidc mode and still requires a configured identity provider. It validates inbound Api-Key headers against Core's /v1/user/info. Project keys use API_KEY_ROLES_MAPPING; JWT-rooted keys use the default role mapping and claim names. Only successful key introspections are cached. The cache TTL also bounds the revocation delay.

Health, info, and Prometheus endpoints remain unauthenticated, including full health details. OpenAPI and Swagger require the FULL_ADMIN authority in oidc mode unless DISABLE_SWAGGER_AUTHORIZATION=true.

Every /v1 endpoint requires FULL_ADMIN, including reads. READ_ONLY_ADMIN can be a mapping target but grants no access to the runner API. At least one usable identity provider is required. Every provider must have role claims, and JWT providers must also have accepted audiences.

Opaque-token and API-key cache misses each have a fixed concurrency limit of 16. Opaque-token overflow returns 401; API-key overflow returns 503. Only successful introspections are cached. Tokens are offered to each configured opaque provider, so those providers must trust each other.

Keep the runner's control plane internal. Backfills and dead-letter requeues (POST /v1/dlq/{id}/requeue, POST /v1/dlq/requeue, and POST /v1/pipelines/{name}/groups/{groupKey}/requeue) can trigger paid model calls. ADAS_API_KEY and DIAL_API_KEY authenticate outgoing requests; neither protects incoming requests.

Logging and telemetry behavior

OTLP export is off by default. Per-signal switches override OTEL_EXPORT_ENABLED. Signal endpoint overrides take precedence over the base collector URL; Prometheus remains available independently. The log-level file supports runtime changes without a restart. A file that never existed leaves levels unchanged; removing an applied file reverts its loggers to their baseline. Mount its directory in Kubernetes, because subPath mounts do not receive updates. validTill sets an expiry in epoch milliseconds. Without it, a debug level persists until the file changes and logs a warning. This behavior comes from the log-level updater's missing-file handling and expiry handling.

HTTP-body and SQL-value loggers are pinned at INFO; the runtime file cannot lower their levels. The exact names are in log4j2-spring.xml.

{
  "loggerLevels": {
    "<LOGGER_NAME>": {
      "defaultLevel": "INFO",
      "configuredLevel": "DEBUG",
      "validTill": 1799999999999
    }
  }
}

All three signals use one SDK resource. Boot's separate Micrometer OTLP exporter is disabled to avoid duplicate metrics.

Further reading

• Environment variables — companion settings reference
• DIAL Admin analytics settings — frontend feature switches and service URLs