Configuration

Observy works without a configuration file. Configuration is loaded in this precedence order, with higher layers overriding lower layers:

1. CLI flags
2. Environment variables
3. YAML config file
4. Runtime defaults

The config file name is observy-config.yaml. Observy searches the current working directory and ~/.config/observy/.

Example Config

data_storage_root_dir: ~/.local/share/observy/data
otlp_grpc_port: 4317
web_port: 8080
storage_provider: sqlite
otel_exporter_host: noop
dashboard_cookie_secure: false
ingestion_authentication_enabled: false
web_tls_certificate_path: ""
web_tls_private_key_path: ""
otlp_grpc_tls_certificate_path: ""
otlp_grpc_tls_private_key_path: ""
logs_value_cache_top_k: 5000
logs_value_cache_threshold: 1000
logs_value_cache_max_value_length_bytes: 256
logs_value_cache_excluded_attributes:
  - trace_id
  - span_id
  - parent_span_id
  - user_id
  - user.id
  - session_id
  - request_id
  - correlation_id

Options

Config key	Env variable	CLI flag	Default	Description
data_storage_root_dir	OBSERVY_DATA_STORAGE_ROOT_DIR	--data-dir	~/.local/share/observy/data	Root directory for local data.
otlp_grpc_port	OBSERVY_OTLP_GRPC_PORT	--otlp-grpc-port	4317	OTLP/gRPC receiver port.
web_port	OBSERVY_WEB_PORT	--web-port	8080	Dashboard port. It serves HTTP by default or HTTPS when direct dashboard TLS is configured.
storage_provider	OBSERVY_STORAGE_PROVIDER	--storage-provider	sqlite	Storage provider: sqlite or duckdb for persisted telemetry; mock is for development and tests.
otel_exporter_host	OBSERVY_OTEL_EXPORTER_HOST	--otel-exporter-host	noop	OTLP endpoint for Observy’s own telemetry, or noop to disable export.
dashboard_cookie_secure	OBSERVY_DASHBOARD_COOKIE_SECURE	--dashboard-cookie-secure	false	Mark dashboard cookies Secure when HTTPS terminates at a proxy. Direct dashboard HTTPS also uses Secure cookies.
ingestion_authentication_enabled	OBSERVY_INGESTION_AUTHENTICATION_ENABLED	--ingestion-authentication-enabled	false	Require an active Bearer ingestion key for every OTLP/gRPC export.
web_tls_certificate_path	OBSERVY_WEB_TLS_CERTIFICATE_PATH	--web-tls-certificate-path	empty	PEM certificate chain for direct dashboard HTTPS.
web_tls_private_key_path	OBSERVY_WEB_TLS_PRIVATE_KEY_PATH	--web-tls-private-key-path	empty	PEM private key for direct dashboard HTTPS.
otlp_grpc_tls_certificate_path	OBSERVY_OTLP_GRPC_TLS_CERTIFICATE_PATH	--otlp-grpc-tls-certificate-path	empty	PEM certificate chain for OTLP/gRPC TLS.
otlp_grpc_tls_private_key_path	OBSERVY_OTLP_GRPC_TLS_PRIVATE_KEY_PATH	--otlp-grpc-tls-private-key-path	empty	PEM private key for OTLP/gRPC TLS.
logs_value_cache_top_k	OBSERVY_LOGS_VALUE_CACHE_TOP_K	--logs-value-cache-top-k	5000	Maximum number of candidate log attribute values tracked for promotion.
logs_value_cache_threshold	OBSERVY_LOGS_VALUE_CACHE_THRESHOLD	--logs-value-cache-threshold	1000	Occurrences required before a log attribute value is promoted into the value lookup table.
logs_value_cache_max_value_length_bytes	OBSERVY_LOGS_VALUE_CACHE_MAX_VALUE_LENGTH_BYTES	--logs-value-cache-max-value-length-bytes	256	Maximum promoted value length in bytes. Longer values remain inline.
logs_value_cache_excluded_attributes	OBSERVY_LOGS_VALUE_CACHE_EXCLUDED_ATTRIBUTES	Not available	high-cardinality ID fields	Attribute names whose values are never promoted.

OBSERVY_AUTH_BOOTSTRAP_USERNAME and OBSERVY_AUTH_BOOTSTRAP_PASSWORD are separate first-run environment variables. They have no YAML or CLI equivalent. Both are required for a fresh data root, and later bootstrap values are ignored after the first administrator exists.

Environment Variable Example

OBSERVY_OTLP_GRPC_PORT=14317 \
OBSERVY_WEB_PORT=18080 \
OBSERVY_STORAGE_PROVIDER=duckdb \
OBSERVY_OTEL_EXPORTER_HOST=noop \
./observy

Security Example

OBSERVY_AUTH_BOOTSTRAP_USERNAME='<administrator-name>' \
OBSERVY_AUTH_BOOTSTRAP_PASSWORD='<administrator-password>' \
OBSERVY_DASHBOARD_COOKIE_SECURE=true \
OBSERVY_INGESTION_AUTHENTICATION_ENABLED=true \
OBSERVY_OTLP_GRPC_TLS_CERTIFICATE_PATH=/etc/observy/tls/otlp-chain.pem \
OBSERVY_OTLP_GRPC_TLS_PRIVATE_KEY_PATH=/etc/observy/tls/otlp-key.pem \
./observy

See Secure Server Deployment for dashboard HTTPS, reverse proxy, OTLP/gRPC TLS, and ingestion-key guidance.

Data Storage

Observy creates the configured data root if it does not exist.

SQLite stores three database files under:

{data_storage_root_dir}/sqlite/
  logs.db
  metrics.db
  traces.db

DuckDB stores its data under the same root:

{data_storage_root_dir}/duckdb/
  logs.db
  metrics.db
  traces.db

Use sqlite or duckdb when you want persisted telemetry.

Authentication state is stored at:

{data_storage_root_dir}/auth/auth.db

Protect this file as credential state. Include it in backups and restores with the telemetry storage directories.