Configuration (signals.yaml)

Config file lookup order

The daemon resolves its configuration file from the first source that exists, in this order:

• The path passed to the --config flag.
• /etc/signals/signals.yaml
• ./signals.yaml(relative to the daemon's working directory).

If no file is found the daemon starts from built-in defaults. After the file is parsed, environment-variable overrides are applied on top of the file values (see Environment-variable overrides), and finally duration strings such as poll_interval are parsed.

Top-level keys

• env — string. Default dev. One of dev, lab, prod. Tightens validation: in prod every enabled target must use verify-ca or verify-full TLS, and an operator-supplied weak API token is a hard error rather than a warning.
• signals — the collector daemon settings (see below).
• targets — the list of PostgreSQL targets to collect from.
• api — the local control API the daemon serves and signalsctl talks to.
• database — the local SQLite snapshot store.

signals: — collector settings

• poll_interval — duration string. Default 5m. Collection cadence. Must be greater than zero; values below 30s emit a warning.
• retention_days — integer. Default 30. Snapshots and query runs older than this are pruned. A value of zero or less disables cleanup (indefinite retention). Mutually exclusive with the structured retention block.
• retention — structured per-class retention. Keys short_days, medium_days, long_days (integers, each must be >= 0). Each unset class falls back to retention_days. Setting both retention_days and any retention.* class is a hard error.
• log_level — string. Default info. One of debug, info, warn, error.
• log_json — boolean. Default false. Emit logs as JSON.
• max_concurrent_targets — integer. Default 4. How many targets are collected in parallel.
• target_timeout — duration string. Default 60s. Per-target collection deadline. Must be greater than zero.
• query_timeout — duration string. Default 10s. Per-query deadline. Must be greater than zero.
• min_snapshot_interval — duration string. Default 60s. Minimum gap between completed snapshots for the same target; rate-limits collection. Must be greater than zero; signalsctl collect now --force bypasses it.
• high_sensitivity_collectors_enabled — boolean. Default true. Runs collectors that read more detailed activity (such as query text). Set false to opt out for privacy.
• collect_array_range_histograms — boolean. Default false. Per-collector opt-in for the array / range histogram collector. Layered on top of high_sensitivity_collectors_enabled — both must be true for the collector to run.
• metrics_enabled — boolean. Default false. Serve a Prometheus metrics endpoint.
• metrics_path — string. Default /metrics. Must start with / and must not collide with reserved API paths (/health, /status, /collect/now, /export).
• export_per_collector_files — boolean. Default false. Adds a derivative per-collector/<id>.json directory to the export ZIP. The canonical NDJSON layout is unaffected.
• mode — string. Default standalone. Either standalone or managed; managed activates the control-plane token check and requires one of the control-plane token sources below.
• control_plane_token_file — string path. The file holding the control-plane token (managed mode). Mutually exclusive with control_plane_token_env.
• control_plane_token_env — string. The name of an environment variable holding the control-plane token (managed mode). Mutually exclusive with control_plane_token_file.
• circuit — per-target circuit-breaker thresholds: fail_threshold (integer, >= 0; zero falls back to the default of 3 consecutive failures) and open_cooldown (duration string, >= 0; zero falls back to the default of 5 minutes).

api: — local control API

• listen_addr — string. Default 127.0.0.1:8081. Address the control API binds to. Must not be empty.
• read_timeout — duration string. Default 30s.
• write_timeout — duration string. Default 180s.
• token — string. Optional operator-supplied bearer token. Mutually exclusive with token_file. An operator-supplied token must be at least 32 characters with at least 8 distinct characters; a weak token is a warning in dev/lab and a hard error in prod. When neither token nor token_file is set, a strong token is generated automatically.
• token_file — string path. A file containing the bearer token. Mutually exclusive with token.
• tls_cert_file — string path. Optional. Enables daemon-terminated TLS for the API. All-or-nothing with tls_key_file: set both for HTTPS, neither for plain HTTP; setting exactly one is a hard error.
• tls_key_file — string path. The private key paired with tls_cert_file.

database: — local snapshot store

• path — string. Default /data/signals.db. The SQLite file collected snapshots are appended to. Must not be empty.
• wal — boolean. Default true. Use SQLite write-ahead logging.

targets: — PostgreSQL targets

A list; each entry describes one database to collect from. Within a config, name must be unique, and name, host, user, and dbname are required. A failure on one target does not block the others.

Connection fields

• name — string, required. Stable identifier for the target.
• host — string, required. Hostname or endpoint.
• port — integer. PostgreSQL port (conventionally 5432).
• dbname — string, required. The logical database to connect to.
• user — string, required. The login role.
• enabled — boolean. Default true when the key is omitted. Set enabled: false explicitly to disable a target.
• sslmode — string. A libpq value: disable, allow, prefer, require, verify-ca, or verify-full. Empty applies the libpq default. verify-ca/verify-full require sslrootcert_file.
• sslrootcert_file — string path. The CA bundle that signs the server certificate. Required for verify-ca/verify-full.

Password credential fields

Supply at most one of the following for the default password auth method; specifying more than one is a hard error.

• password_file — string path to a file containing the password.
• password_env — name of an environment variable holding the password.
• pgpass_file — path to a libpq-format pgpass file.

Authentication-method fields

auth_method selects the credential provider (empty means the default password provider). The remaining fields below are consumed only by specific methods. The full provider semantics — which fields each method requires, the passwordless and verify-full rules, and the cloud-specific behaviour — are documented in Authentication methods.

• auth_method — string. One of password, aws_rds_iam, azure_entra, gcp_cloudsql_iam, secret_store, mtls.
• region — string. AWS region; consumed only by aws_rds_iam.
• azure_client_id — string. User-assigned managed-identity client ID; consumed only by azure_entra.
• gcp_impersonate_service_account — string. Service-account email to impersonate; consumed only by gcp_cloudsql_iam.
• secret_ref — string. Cloud secret-store reference (AWS Secrets Manager ARN, SSM Parameter Store ARN, Azure Key Vault URI, or GCP Secret Manager name); required by secret_store.
• secret_json_key — string. Key within a JSON secret whose value is the password; consumed only by secret_store.
• max_cache_ttl — duration string (>= 0). Bounds reuse of a fetched secret; consumed only by secret_store.
• sslcert — string path. PEM client certificate; required by mtls.
• sslkey — string path. PEM private key; required by mtls.
• sslkey_passphrase_file — string path. Optional passphrase file for an encrypted sslkey (mtls only).

Per-target collectors (collectors:)

• profile — string. One of default, restricted, custom. Empty inherits the daemon-wide default.
• include — list of collector IDs to allow.
• exclude — list of collector IDs to deny. A collector ID may not appear in both include and exclude.

Environment-variable overrides

Environment variables are applied after the file is parsed and take precedence over file values. Integer variables must parse as integers; boolean variables accept true/false/1/0 only.

• SIGNALS_ENV → env
• SIGNALS_POLL_INTERVAL → signals.poll_interval
• SIGNALS_RETENTION_DAYS → signals.retention_days
• SIGNALS_LOG_LEVEL → signals.log_level
• SIGNALS_LOG_JSON → signals.log_json
• SIGNALS_MAX_CONCURRENT_TARGETS → signals.max_concurrent_targets
• SIGNALS_TARGET_TIMEOUT → signals.target_timeout
• SIGNALS_QUERY_TIMEOUT → signals.query_timeout
• SIGNALS_MIN_SNAPSHOT_INTERVAL → signals.min_snapshot_interval
• SIGNALS_HIGH_SENSITIVITY_COLLECTORS_ENABLED → signals.high_sensitivity_collectors_enabled
• SIGNALS_COLLECT_ARRAY_RANGE_HISTOGRAMS → signals.collect_array_range_histograms
• SIGNALS_METRICS_ENABLED → signals.metrics_enabled
• SIGNALS_METRICS_PATH → signals.metrics_path
• SIGNALS_EXPORT_PER_COLLECTOR_FILES → signals.export_per_collector_files
• SIGNALS_MODE → signals.mode
• SIGNALS_CONTROL_PLANE_TOKEN_FILE → signals.control_plane_token_file
• SIGNALS_CONTROL_PLANE_TOKEN_ENV → signals.control_plane_token_env
• SIGNALS_LISTEN_ADDR → api.listen_addr
• SIGNALS_WRITE_TIMEOUT → api.write_timeout
• SIGNALS_API_TOKEN → the resolved API token
• SIGNALS_API_TOKEN_FILE → the resolved API token, read from a file (takes precedence over SIGNALS_API_TOKEN)
• SIGNALS_API_TLS_CERT_FILE → api.tls_cert_file
• SIGNALS_API_TLS_KEY_FILE → api.tls_key_file
• SIGNALS_DB_PATH → database.path
• SIGNALS_ALLOW_INSECURE_PG_TLS — boolean. Permits a weak PostgreSQL sslmode in non-prod; never permitted in prod.
• SIGNALS_ALLOW_UNSAFE_ROLE — boolean. Env-only role-safety override.

A single target can also be supplied entirely from the environment (convenient in containers) when SIGNALS_TARGET_HOST is set: SIGNALS_TARGET_NAME (default default), SIGNALS_TARGET_PORT (default 5432), SIGNALS_TARGET_DBNAME (default postgres), SIGNALS_TARGET_USER, SIGNALS_TARGET_SSLMODE, SIGNALS_TARGET_SSLROOTCERT_FILE, SIGNALS_TARGET_PASSWORD_FILE, SIGNALS_TARGET_PASSWORD_ENV, and SIGNALS_TARGET_PGPASS_FILE. The resulting target is appended to any targets defined in the file.

Full signals.yaml example

The complete schema with all available fields and their defaults:

# signals.yaml
env: dev  # dev, lab, prod
signals:
  poll_interval: 5m
  retention_days: 30
  log_level: info           # debug, info, warn, error
  log_json: false
  max_concurrent_targets: 4
  target_timeout: 60s
  query_timeout: 10s
targets:
  - name: my-database
    host: localhost
    port: 5432
    dbname: postgres
    user: signals
    password_file: /path/to/password    # or password_env or pgpass_file
    sslmode: prefer
    sslrootcert_file: /path/to/ca.crt   # required for verify-ca/verify-full
    enabled: true
database:
  path: /data/signals.db
  wal: true
api:
  listen_addr: "127.0.0.1:8081"
  read_timeout: 30s
  write_timeout: 180s

Multi-target example

Signals collects concurrently across multiple targets. Each target is collected independently; max_concurrent_targets (default 4) controls how many run in parallel.

# signals.yaml
env: prod
signals:
  poll_interval: 5m
  retention_days: 30
  max_concurrent_targets: 4
  target_timeout: 60s
  query_timeout: 10s
targets:
  - name: prod-primary
    host: primary.db.internal
    port: 5432
    dbname: app
    user: signals
    password_file: /run/secrets/pg_password_primary
    sslmode: verify-full
    sslrootcert_file: /etc/ssl/certs/pg-ca.crt
    enabled: true

  - name: prod-replica
    host: replica.db.internal
    port: 5432
    dbname: app
    user: signals
    password_file: /run/secrets/pg_password_replica
    sslmode: verify-full
    sslrootcert_file: /etc/ssl/certs/pg-ca.crt
    enabled: true

  - name: staging
    host: staging.db.internal
    port: 5432
    dbname: app
    user: signals
    password_env: PG_PASSWORD_STAGING
    sslmode: require
    enabled: true
database:
  path: /data/signals.db
  wal: true
api:
  listen_addr: "127.0.0.1:8081"