Configuration

import { Aside } from ‘@astrojs/starlight/components’;

PulsusDB is configured with environment variables, optionally layered over a YAML file.

Configuration precedence from highest to lowest: CLI flags, environment variables, YAML file, and built-in defaults.

Only --config and --mode are CLI flags. An environment variable set to an empty string is treated as unset.

Core

Variable	Default	Description
`PULSUS_MODE`	`all`	`all`, `writer`, or `reader`
`PULSUS_HOST`	`0.0.0.0`	HTTP bind address
`PULSUS_PORT`	`3100`	HTTP port
`PULSUS_LOG_LEVEL`	`info`	`error`, `warn`, `info`, `debug`, or `trace`
`PULSUS_QUERY_TIMEOUT`	`2m`	Hard per-query deadline
`PULSUS_COMPAT_ENDPOINTS`	`false`	Mount optional third-party API aliases and receivers
`PULSUS_CORS_ORIGIN`	`*`	`Access-Control-Allow-Origin` value

Authentication

Variable	Default	Description
`PULSUS_AUTH_USER`	unset	API Basic auth username; requires the password
`PULSUS_AUTH_PASSWORD`	unset	API Basic auth password; requires the username
`PULSUS_ADMIN_USER`	`admin`	Admin UI username
`PULSUS_ADMIN_PASSWORD`	`admin`	Admin UI password; change before exposure

Inbound TLS

Set both PULSUS_TLS_CERT and PULSUS_TLS_KEY to make the listener TLS-only. Both unset means plaintext. Exactly one set is a startup error.

ClickHouse

Variable	Default	Description
`CLICKHOUSE_SERVER`	`localhost`	Single ClickHouse host
`CLICKHOUSE_SERVERS`	unset	Comma-separated `host[:port][=zone]` endpoints
`CLICKHOUSE_HTTP_PORT`	`8123`	HTTP interface port
`CLICKHOUSE_DB`	`pulsus`	Database created by the schema tool
`CLICKHOUSE_PROTO`	`http`	`http` or `https`
`CLICKHOUSE_AUTH`	`default:`	`user:password` pair
`CLICKHOUSE_TLS_SKIP_VERIFY`	`false`	Skip certificate verification
`CLICKHOUSE_TLS_CA_FILE`	unset	Custom CA bundle for HTTPS
`PULSUS_CH_POOL_SIZE`	`8`	Total query concurrency permits

Consistency

Variable	Default	Description
`CLICKHOUSE_INSERT_QUORUM`	`0`	`0` disables; `1` is rejected; use `>=2` on replicated tables
`CLICKHOUSE_INSERT_QUORUM_PARALLEL`	`true`	Allow parallel quorum inserts
`CLICKHOUSE_INSERT_QUORUM_TIMEOUT`	`120s`	Quorum wait, bounded by the query timeout
`CLICKHOUSE_SELECT_SEQUENTIAL_CONSISTENCY`	`false`	Read-your-writes with non-parallel quorum writes

Sequential consistency requires quorum >=2 and parallel quorum inserts disabled. These settings do not apply to plain MergeTree single-node deployments.

Schema and cluster

Variable	Default	Description
`PULSUS_CLUSTER`	unset	ClickHouse cluster name; enables replicated/distributed schema
`PULSUS_DIST_SUFFIX`	`_dist`	Distributed table suffix used by readers
`PULSUS_STORAGE_POLICY`	unset	ClickHouse storage policy for schema creation
`PULSUS_TRACEQL_INDEXED_ATTRIBUTES`	empty	Comma-separated span/event attributes to index
`PULSUS_LOG_ROLLUP_RESOLUTION`	`5s`	Log aggregate bucket size
`PULSUS_SKIP_UNAVAILABLE_SHARDS`	`false`	Return partial cluster results when a shard is unavailable

Retention is set separately with PULSUS_RETENTION_DAYS when running schema/schema.sh.

Writer and backpressure

Variable	Default	Description
`PULSUS_BATCH_BYTES`	`16MiB`	Per-push estimated landing-byte ceiling
`PULSUS_BATCH_MS`	`200`	Push-suppression claim cadence; not a flush timer
`PULSUS_INSERT_MODE`	`sync`	Default `sync` or `async` acknowledgment
`PULSUS_INGEST_QUEUE_BYTES`	`256MiB`	Total buffered bytes before `429`
`PULSUS_LOG_PATTERNS`	`true`	Ingest-time log pattern extraction
`PULSUS_DISCOVER_LOG_LEVELS`	`true`	Attach detected log-level metadata

YAML example

mode: all
host: 0.0.0.0
port: 3100
log_level: info

clickhouse:
  server: clickhouse.internal
  http_port: 8123
  database: pulsus
  protocol: https

compat_endpoints: false

pulsusdb --config /etc/pulsusdb/config.yaml