Skip to main content
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.
FlagEnvironment VariableDefaultDescription
-c, --configPROMETHEUS_CONFIG_FILEnonePath to the prometheus.yaml configuration file
-p, --portOPEN_TSDB_PORT9090Port 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 ingest consumer. See the Stateless Ingest page for the full write path.
[ ingest_consumer: <ingest_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.
storage:
  type: InMemory

​
<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 ]
See the production guide for recommended sizes.

​
<object_store_config>

The object store is tagged by type. 
object_store:
  type: Local
  # Directory path for local storage.
  path: <string>

​
<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 ]
Disable the warmer when starting read-only replicas that only serve recent queries, where the up-front scan cost outweighs the benefit.

​
<ingest_consumer_config>

Enables the durable-queue write path. See the Stateless Ingest page for the full architecture, the OpenTelemetry Collector side, and operational guidance. 
ingest_consumer:
  # Object store holding the ingest 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 ]
Requires read-write mode. When absent, no consumer starts.

​
Examples

prometheus.yaml
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