Documentation Index
Fetch the complete documentation index at: https://opendata.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
Timeseries is configured through CLI arguments and a Prometheus-compatible YAML
configuration file. The CLI arguments control server startup, while the YAML
file defines scrape targets, storage backends, and operational parameters.
CLI Arguments
Pass these flags when starting the opendata-timeseries binary.
| Flag | Environment Variable | Default | Description |
|---|
-c, --config | PROMETHEUS_CONFIG_FILE | none | Path to the prometheus.yaml configuration file |
-p, --port | OPEN_TSDB_PORT | 9090 | Port to listen on |
./opendata-timeseries --config prometheus.yaml --port 9090
Configuration File
The configuration file follows the Prometheus YAML format with additional
sections for storage. The generic placeholders used in this reference are:
<string>: a regular string<int>: an integer value<duration>: a duration matching [0-9]+(ms|s|m|h|d) (e.g. 30s, 1m, 2h)
A value enclosed in [ ] is optional. The default value is shown after | default =.
# Default settings applied to all scrape jobs.
global:
# How often to scrape targets.
[ scrape_interval: <duration> | default = 15s ]
# List of scrape job configurations.
scrape_configs:
[ - <scrape_config> ... ]
# Storage backend configuration (required).
storage:
<storage_config>
# How often (in seconds) to flush data from memory to durable storage.
[ flush_interval_secs: <int> | default = 5 ]
# Startup cache warmer (enabled by default).
[ cache_warmer: <cache_warmer_config> ]
# Durable buffer consumer. See the Stateless Ingest page for the full write path.
[ buffer_consumer: <buffer_consumer_config> ]
<scrape_config>
Each scrape config defines a set of targets and the parameters for scraping them.
# Name for this scrape job. Added as the `job` label on all scraped metrics.
job_name: <string>
# Override the global scrape interval for this job.
[ scrape_interval: <duration> | default = <global.scrape_interval> ]
# List of static target groups to scrape.
static_configs:
[ - <static_config> ... ]
<static_config>
A static config defines a list of targets and a common set of labels to apply.
# Endpoints to scrape in host:port format.
targets:
[ - <string> ... ]
# Labels to attach to all metrics scraped from these targets.
labels:
[ <string>: <string> ... ]
<storage_config>
Storage is tagged by type.
# The storage backend type.
type: <string> # One of: InMemory, SlateDb
Stores data in memory only. Data is lost on restart. Useful for testing
and development. No additional fields are required. Persists data to an object store via SlateDB.storage:
type: SlateDb
# Path prefix for SlateDB data within the object store.
[ path: <string> | default = "data" ]
# Path to a SlateDB settings file (TOML/YAML/JSON).
# If omitted, SlateDB checks for SlateDb.toml, SlateDb.json, or SlateDb.yaml
# in the working directory and merges any SLATEDB_-prefixed environment variables.
[ settings_path: <string> ]
# Block cache (optional). See <block_cache_config> below.
[ block_cache: <block_cache_config> ]
# Object store provider configuration (required).
object_store:
<object_store_config>
<block_cache_config>
The block cache sits in front of SlateDB and holds decoded SST blocks. It is
tagged by type. Only FoyerHybrid is currently available.
block_cache:
type: FoyerHybrid
# In-memory tier capacity in bytes.
memory_capacity: <int>
# On-disk tier capacity in bytes.
disk_capacity: <int>
# Directory for the on-disk tier.
disk_path: <string>
# When entries are promoted to the disk tier.
# WriteOnInsertion persists every cached block; WriteOnEviction
# only persists on memory eviction.
[ write_policy: <string> | default = WriteOnInsertion ]
# Flush thread count for the disk engine.
[ flushers: <int> | default = 4 ]
# Flush-pipeline buffer pool size in bytes. Actual allocation is ~2x
# this value (flushers double-buffer). Defaults to memory_capacity / 32.
[ buffer_pool_size: <int> ]
# Write-queue size threshold in bytes. Entries beyond this are dropped
# rather than blocking the cache.
[ submit_queue_size_threshold: <int> | default = 1073741824 ]
<object_store_config>
The object store is tagged by type.
Local filesystem
AWS S3
In-memory
object_store:
type: Local
# Directory path for local storage.
path: <string>
object_store:
type: Aws
# AWS region (e.g. us-west-2).
region: <string>
# S3 bucket name.
bucket: <string>
object_store:
type: InMemory
<cache_warmer_config>
On startup, the server scans recent time bucket key ranges through the storage
reader. The block cache picks up those blocks as a side effect, so the first
queries after a restart do not pay cold-cache latency. The warmer runs once
and exits.
Enabled by default. Set cache_warmer: null to disable.
cache_warmer:
# How far back to scan on startup.
[ warm_range: <duration> | default = 24h ]
# Whether to warm raw sample data in addition to index metadata.
[ include_samples: <bool> | default = true ]
<buffer_consumer_config>
Enables the durable-queue write path. See the
Stateless Ingest page for the full architecture, the
OpenTelemetry Collector side, and operational guidance.
buffer_consumer:
# Object store holding the buffer queue. May differ from the TSDB's
# storage bucket.
object_store:
<object_store_config>
# Must match the manifest path configured on the producer side.
[ manifest_path: <string> | default = "ingest/manifest" ]
# Delay between polls when the queue is empty.
[ poll_interval: <duration> | default = 1s ]
Examples
Local development
Production (S3)
Testing (in-memory)
global:
scrape_interval: 15s
scrape_configs:
- job_name: "my-app"
static_configs:
- targets: ["localhost:9090"]
storage:
type: SlateDb
path: data
object_store:
type: Local
path: ./data
flush_interval_secs: 5
global:
scrape_interval: 30s
scrape_configs:
- job_name: "node-exporter"
scrape_interval: 15s
static_configs:
- targets: ["host-a:9100", "host-b:9100"]
labels:
env: production
- job_name: "api-server"
static_configs:
- targets: ["api-1:8080", "api-2:8080"]
labels:
env: production
storage:
type: SlateDb
path: data
object_store:
type: Aws
region: us-west-2
bucket: my-metrics-bucket
global:
scrape_interval: 5s
scrape_configs:
- job_name: "test-app"
static_configs:
- targets: ["localhost:9090"]
storage:
type: InMemory
