DIAL Analytics security and observability

This reference covers security and observability for platform engineers operating DIAL Analytics. 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).
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.

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 ADAS 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	Create and export spans; when off the SDK hands out a no-op tracer, so tracing is fully inert.
OTEL_LOGS_EXPORT_ENABLED	OTEL_EXPORT_ENABLED	Export application logs over OTLP.
OTEL_METRICS_EXPORT_ENABLED	OTEL_EXPORT_ENABLED	Export application 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.
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 traces and logs: http or grpc. Metrics are always sent over HTTP.
OTEL_TRACES_SAMPLING_PROBABILITY	1.0	Probability (0.0–1.0) that a new trace is sampled; parent-based, so upstream decisions are honoured.
OTEL_SERVICE_NAME	ai-dial-analytics	service.name resource attribute.
OTEL_RESOURCE_ATTRIBUTES	—	Extra resource attributes as key=value,key=value; a service.name entry here always loses to the property above, so use OTEL_SERVICE_NAME.

Authentication

Source: configuration reference.

Variable	Default	Description
SECURITY_MODE	none	Required if the service is exposed. oidc enforces authentication and privilege-based authorization; none disables all of it. Matched case-insensitively; any other value fails startup.
SECURITY_REQUIRE_EMAIL	false	Reject a token with no resolvable email claim. oidc only.
SECURITY_ROLES_MAPPING	{"ConfigAdmin":["FULL_ADMIN"],"admin":["FULL_ADMIN"]}	Default JSON mapping of provider role names to privilege or bundle names, merged under each provider's own mapping. An unknown value fails startup. 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. 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: with an empty list, every token is rejected. Accepted aud values; an api://-prefixed variant of each is also accepted.
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 privilege or bundle names, 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.

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. Blank fails startup when enabled.
API_KEY_ROLES_MAPPING	—	JSON mapping of Core project-key role names to privileges or bundles. An unknown token fails startup; an empty mapping does not—a deployment may authenticate project keys and authorize them for nothing beyond their per-table grants.
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	true	Probe Core reachability at startup and fail fast if unreachable. Set false to skip.

Provider configuration

Providers are configured in an external YAML file through SPRING_CONFIG_ADDITIONAL_LOCATION. JWT providers need an issuer, JWKS URL, accepted audiences, and role claims. 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. 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 authentication in oidc mode unless DISABLE_SWAGGER_AUTHORIZATION=true.

Analytics authorizes privileges and table grants, including sensitive-column access and row policies. Global privileges and per-table grants are combined; narrowing a table grant cannot revoke a global privilege. TABLE_SENSITIVE is an additional clearance, not permission to read a table by itself.

Role bundle	Declared privileges
FULL_ADMIN	All privileges
READ_ONLY_ADMIN	TABLE_READ, REGISTRY_READ, AUDIT_READ, SAVED_QUERY_WRITE
READ_ONLY_ANALYTIC	TABLE_READ, SAVED_QUERY_WRITE
READ_ONLY_SENSITIVE_ANALYTIC	TABLE_READ, TABLE_SENSITIVE, SAVED_QUERY_WRITE

Declared privileges imply others, so the effective sets are larger: TABLE_READ and TABLE_MODIFY grant TABLE_GET, which grants TABLE_LIST; SAVED_QUERY_WRITE and SAVED_QUERY_PUBLISH grant SAVED_QUERY_READ. See privilege implications.

Opaque-token introspection has no cache in this service; the OPAQUE_TOKEN_* variables belong to the runner. Public ingress should allow only consumer query endpoints. Keep mutations and runner endpoints internal. Flight SQL requires a separate gRPC route when enabled.

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. Analytics additionally pins its SQL renderer and jclouds wire, header, and signature loggers. The exact names are in log4j2.xml.

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

Metrics use HTTP even when traces and logs use grpc. OTEL_RESOURCE_ATTRIBUTES adds SDK resource attributes; OTEL_SERVICE_NAME wins for the service name.

Further reading

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