LogDB Configuration And BYOC Reference

Source-backed reference for LogDB runtime environment variables, S3 query-read selection, WAL durability settings, optional gRPC bind configuration, and AWS BYOC Terraform-to-Helm handoff values.

Current availability

Private Beta. Public beta is scheduled for November 2, 2026.

Reference Snapshot

Runtime env vars: 13
BYOC Helm values: 11
BYOC Terraform inputs: 7

Maturity Status

Runtime Configuration

Live

Local bind, data directory, optional gRPC listener, and OTLP backpressure settings are read by the current executable at startup.

BYOC Handoff

Verification Required

The AWS package is a Terraform-to-Helm bootstrap with offline preflight validation. It does not approve full VPC/EKS bootstrap, image publishing, S3-backed publication, support, or GA readiness.

Reference Summary

ID	Type	Name	Method	Key or path	Maturity	Evidence
`ldb-config-http-bind`	configuration	HTTP bind address Selects the Actix HTTP listener address for health, endpoint, OTLP HTTP, and query routes.	`n/a`	`LOGDB_BIND_ADDRESS`	Live	LDB-EVID-009, config.rs, main.rs
`ldb-config-data-dir`	configuration	Data directory Root for local WAL, segment publication, replay checkpoints, audit evidence, and local query reads.	`n/a`	`LOGDB_DATA_DIR`	Live	LDB-EVID-009, config.rs, durable_gateway.rs
`ldb-config-grpc-bind`	configuration	Optional OTLP/gRPC bind address Starts the optional Tonic OTLP logs and traces listener when set to a socket address.	`n/a`	`LOGDB_OTLP_GRPC_BIND_ADDRESS`	Live	LDB-EVID-009, config.rs, main.rs
`ldb-config-otlp-backpressure`	configuration	OTLP gateway backpressure Overrides shared in-flight request, record, and byte budgets for HTTP and gRPC OTLP ingest.	`n/a`	`LOGDB_OTLP_MAX_IN_FLIGHT_*`	Live	LDB-EVID-009, backpressure.rs, config.rs
`ldb-config-s3-query-read`	configuration	S3 query-read store Switches POST /v1/query from local segment bundles to a configured S3 read path.	`n/a`	`LOGDB_QUERY_STORE, LOGDB_QUERY_S3_*`	Verification Required	LDB-EVID-004, LDB-EVID-009, main.rs
`ldb-config-wal-durability`	configuration	WAL durability mode Keeps the default local WAL or opts into replicated-local quorum writes before segment publication.	`n/a`	`LOGDB_WAL_DURABILITY_MODE, LOGDB_WAL_REPLICA_PATHS, LOGDB_WAL_WRITE_QUORUM`	Verification Required	LDB-EVID-005, LDB-EVID-009, config.rs
`ldb-byoc-terraform-bootstrap`	configuration	AWS BYOC Terraform bootstrap Creates customer-owned S3, KMS, and IAM handoff resources with retained-data guardrails.	`terraform apply`	`deploy/aws/byoc/terraform`	Verification Required	LDB-EVID-009, terraform/main.tf, terraform/outputs.tf
`ldb-byoc-helm-values`	configuration	AWS BYOC Helm values Maps chart values into runtime env vars and BYOC handoff metadata for the Kubernetes workload.	`helm install`	`deploy/aws/byoc/helm/service-logdb`	Verification Required	LDB-EVID-009, values.yaml, configmap.yaml
`ldb-byoc-handoff-preflight`	configuration	BYOC handoff preflight Validates Terraform output JSON against expected Helm values, retained resources, and uninstall notes before install automation runs Helm.	`preflight_byoc_handoff`	`LogDB/src/control/byoc_preflight.rs`	Verification Required	LDB-EVID-009, byoc_preflight.rs

Local Runtime Settings

Core startup environment variables
Key	Default	Accepted value	Read at	Restart	Evidence
`LOGDB_BIND_ADDRESS`	127.0.0.1:80	Host and port string accepted by Actix HttpServer::bind, such as 127.0.0.1:4318.	Service startup	Yes	LogDB/src/config.rs, LogDB/src/main.rs
`LOGDB_DATA_DIR`	D:/Data/DB	Non-empty filesystem path. Blank values use the default.	Service startup	Yes	LogDB/src/config.rs
`LOGDB_OTLP_GRPC_BIND_ADDRESS`	unset	Socket address such as 127.0.0.1:4317 or 0.0.0.0:4317. Blank values disable the listener.	Service startup	Yes	LogDB/src/config.rs, LogDB/src/main.rs
`LOGDB_OTLP_MAX_IN_FLIGHT_REQUESTS`	64	Positive u32. Zero, blank, or malformed values use the default.	Service startup	Yes	LogDB/src/config.rs, LogDB/src/ingestion/backpressure.rs
`LOGDB_OTLP_MAX_IN_FLIGHT_RECORDS`	8192	Positive integer. Zero, blank, or malformed values use the default.	Service startup	Yes	LogDB/src/config.rs, LogDB/src/ingestion/backpressure.rs
`LOGDB_OTLP_MAX_IN_FLIGHT_BYTES`	33554432	Positive integer byte count. Zero, blank, or malformed values use the default.	Service startup	Yes	LogDB/src/config.rs, LogDB/src/ingestion/backpressure.rs

export LOGDB_BIND_ADDRESS=127.0.0.1:4318
export LOGDB_DATA_DIR="${TMPDIR:-/tmp}/logdb-docs-034"
export LOGDB_OTLP_GRPC_BIND_ADDRESS=127.0.0.1:4317

cargo run

S3 Query-Read Selection

Query store environment variables
Key	Default	Accepted value	Read at	Restart	Evidence
`LOGDB_QUERY_STORE`	local	s3 selects the S3 async object-store read path. Any other value uses the local segment store.	Service startup	Yes	LogDB/src/config.rs, LogDB/src/main.rs
`LOGDB_QUERY_S3_BUCKET`	empty unless LOGDB_QUERY_STORE=s3	S3 bucket name for retained segment bundle reads.	Service startup	Yes	LogDB/src/config.rs, LogDB/src/main.rs
`LOGDB_QUERY_S3_PREFIX`	unset	Segment publication prefix containing bundle directories and manifest.json objects.	Service startup	Yes	docs/query/http-query-api.md, LogDB/src/main.rs
`LOGDB_QUERY_S3_REGION`	AWS SDK default chain	Non-empty AWS region string such as us-east-1.	Service startup	Yes	LogDB/src/config.rs, LogDB/src/main.rs

LOGDB_QUERY_STORE=s3 changes the query read path for POST /v1/query. It does not make endpoint, OTLP HTTP, or OTLP/gRPC ingest publish to S3.

export LOGDB_QUERY_STORE=s3
export LOGDB_QUERY_S3_BUCKET=logdb-alpha
export LOGDB_QUERY_S3_PREFIX=tenant-a/segments
export LOGDB_QUERY_S3_REGION=us-east-1

WAL Durability Settings

Direct-ingest WAL environment variables
Key	Default	Accepted value	Read at	Restart	Evidence
`LOGDB_WAL_DURABILITY_MODE`	local	replicated-local or replicated_local opts into replica quorum.	Service startup	Yes	LogDB/src/config.rs
`LOGDB_WAL_REPLICA_PATHS`	LOGDB_DATA_DIR/wal/replicas/replica-{1,2,3}.wal	Comma-separated local WAL replica paths used only in replicated-local mode.	Service startup	Yes	LogDB/src/config.rs, README.md
`LOGDB_WAL_WRITE_QUORUM`	majority quorum	Positive integer write quorum for replicated-local mode. Zero or malformed values use the default.	Service startup	Yes	LogDB/src/config.rs, README.md

Direct ingest defaults to one local live WAL at wal/live-ingest.wal below LOGDB_DATA_DIR. Replicated-local mode requires a local replica quorum before endpoint, OTLP HTTP/protobuf, OTLP/gRPC, or OTLP JSON compatibility ingestion publishes segment bundles.

AWS BYOC Terraform Bootstrap

Terraform module inputs
Key	Default	Purpose	Evidence
`aws_region`	none	AWS region where customer-owned telemetry resources are created.	terraform/variables.tf
`name_prefix, environment`	none	Lowercase resource-name inputs used to derive names and retained-resource IDs.	terraform/variables.tf, terraform/main.tf
`tenant_id, dataset_id`	none	Tags customer-owned data-plane resources and default object scope.	terraform/variables.tf, terraform/main.tf
`telemetry_prefix`	telemetry	S3 object prefix that the LogDB data-plane IAM policy can list, read, and write.	terraform/variables.tf, terraform/main.tf
`telemetry_bucket_name`	derived from name_prefix, environment, and region	Optional globally unique S3 bucket name; otherwise Terraform derives one.	terraform/variables.tf, terraform/main.tf
`eks_oidc_provider_arn, eks_oidc_provider_url`	none	EKS OIDC provider inputs for the Kubernetes service-account IAM role trust policy.	terraform/variables.tf, terraform/main.tf
`kubernetes_namespace, service_account_name`	service-logdb	Kubernetes identity that can assume the LogDB data-plane role.	terraform/variables.tf, terraform/main.tf

The Terraform module creates one customer-owned telemetry S3 bucket, one customer-owned KMS key and alias, one EKS service-account IAM role, and one scoped IAM policy. The bucket and KMS key use Terraform prevent_destroy; the default IAM policy omits s3:DeleteObject.

AWS BYOC Helm Values

Helm chart values
Key	Default	Purpose	Evidence
`config.bindAddress`	0.0.0.0:8080	Sets LOGDB_BIND_ADDRESS in the chart ConfigMap.	values.yaml, templates/configmap.yaml
`config.otlpGrpcBindAddress`	0.0.0.0:4317	Sets LOGDB_OTLP_GRPC_BIND_ADDRESS and enables the gRPC container port.	values.yaml, templates/configmap.yaml
`config.otlpMaxInFlightRequests`	64	Sets LOGDB_OTLP_MAX_IN_FLIGHT_REQUESTS.	values.yaml, templates/configmap.yaml
`config.otlpMaxInFlightRecords`	8192	Sets LOGDB_OTLP_MAX_IN_FLIGHT_RECORDS.	values.yaml, templates/configmap.yaml
`config.otlpMaxInFlightBytes`	33554432	Sets LOGDB_OTLP_MAX_IN_FLIGHT_BYTES.	values.yaml, templates/configmap.yaml
`config.dataDir`	/var/lib/logdb	Sets LOGDB_DATA_DIR and mounts an emptyDir local-data volume there.	values.yaml, templates/deployment.yaml
`config.awsRegion`	empty	Sets LOGDB_AWS_REGION as BYOC handoff metadata.	values.yaml, templates/configmap.yaml
`config.telemetryBucket`	empty	Sets LOGDB_TELEMETRY_BUCKET as BYOC handoff metadata.	values.yaml, templates/configmap.yaml
`config.telemetryPrefix`	telemetry	Sets LOGDB_TELEMETRY_PREFIX as BYOC handoff metadata.	values.yaml, templates/configmap.yaml
`config.kmsKeyArn`	empty	Sets LOGDB_KMS_KEY_ARN as BYOC handoff metadata.	values.yaml, templates/configmap.yaml
`service.grpc.port`	4317	Exposes the OTLP/gRPC service port.	values.yaml, templates/service.yaml

The current chart maps runtime settings into a ConfigMap and exposes HTTP on port 80 to container port 8080 plus OTLP/gRPC on service port 4317. LOGDB_AWS_REGION, LOGDB_TELEMETRY_BUCKET, LOGDB_TELEMETRY_PREFIX, and LOGDB_KMS_KEY_ARN are BYOC handoff metadata in this package; runtime S3 query reads still use the LOGDB_QUERY_* settings above.

Handoff Preflight

preflight_byoc_handoff parses terraform output -json content, validates exact Helm handoff values, checks normalized telemetry prefixes, verifies retained S3 and KMS resources, and returns deterministic Helm --set arguments.

terraform output -json > /tmp/logdb-byoc-output.json

# Current validation entry points live in LogDB:
cargo test control::byoc_preflight
./scripts/validate-byoc-layout.sh

Errors

Error	Applies to	Meaning	Recovery
Startup bind failure	LOGDB_BIND_ADDRESS	The HTTP bind address is invalid, privileged, unavailable, or already in use.	Use an unprivileged loopback or container bind address and restart.
Invalid gRPC bind address	LOGDB_OTLP_GRPC_BIND_ADDRESS	The optional gRPC listener value cannot parse as a socket address.	Use a host:port value such as 127.0.0.1:4317 or unset the variable.
Invalid S3 query store configuration	LOGDB_QUERY_STORE=s3 and LOGDB_QUERY_S3_*	Bucket, prefix, or region validation failed before the service started.	Use a non-empty bucket, a safe relative prefix, and a non-empty region when overriding the AWS SDK chain.
WAL durability startup failure	LOGDB_WAL_DURABILITY_MODE=replicated-local	Replica paths or write quorum cannot satisfy replicated-local startup validation.	Use reachable local replica paths and a quorum no larger than the available replica set.
BYOC preflight failure	Terraform output JSON and Helm values	Required Terraform outputs are missing, mismatched, unnormalized, or do not identify retained resources.	Rerun terraform output -json, pass the exact Helm handoff values, and keep retained S3/KMS uninstall notes visible.

Boundaries

Local, S3 Query Read, BYOC

Local runtime settings control the service process. LOGDB_QUERY_STORE=s3 controls only retained segment reads for query. BYOC chart values are the install handoff for an existing Kubernetes cluster.

Future Deployment Work

Full VPC/EKS bootstrap, image publishing, live S3 publication, replay from customer-owned S3, security approvals, support posture, and GA commitments require follow-up evidence.

Safe Next Steps

Available: DOCS-033
Read OTLP and query reference
Route, header, query filter, limit, and error details for the configured runtime.
Available now
Review LogDB evidence
Check source records before strengthening configuration, BYOC, S3, WAL, or deployment wording.
Available: DOCS-039
Compare OTLP and S3 query scope
Distinguish live ingest, optional gRPC, local query, S3 query reads, metrics/profile exclusions, and future publication work.