> ## 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 Configuration

> Configure scrape targets, storage backends, and retention for Timeseries

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                                |

```bash theme={null}
./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 =`.

```yaml theme={null}
# 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.

```yaml theme={null}
# 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.

```yaml theme={null}
# 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`.

```yaml theme={null}
# The storage backend type.
type: <string> # One of: InMemory, SlateDb
```

<Tabs>
  <Tab title="InMemory">
    Stores data in memory only. Data is lost on restart. Useful for testing
    and development. No additional fields are required.

    ```yaml theme={null}
    storage:
      type: InMemory
    ```
  </Tab>

  <Tab title="SlateDb">
    Persists data to an object store via [SlateDB](https://slatedb.io).

    ```yaml theme={null}
    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>
    ```
  </Tab>
</Tabs>

### `<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.

```yaml theme={null}
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](/timeseries/production#block-cache) for recommended
sizes.

### `<object_store_config>`

The object store is tagged by `type`.

<Tabs>
  <Tab title="Local filesystem">
    ```yaml theme={null}
    object_store:
      type: Local
      # Directory path for local storage.
      path: <string>
    ```
  </Tab>

  <Tab title="AWS S3">
    ```yaml theme={null}
    object_store:
      type: Aws
      # AWS region (e.g. us-west-2).
      region: <string>
      # S3 bucket name.
      bucket: <string>
    ```
  </Tab>

  <Tab title="In-memory">
    ```yaml theme={null}
    object_store:
      type: InMemory
    ```
  </Tab>
</Tabs>

### `<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.

```yaml theme={null}
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.

### `<buffer_consumer_config>`

Enables the durable-queue write path. See the
[Stateless Ingest page](/timeseries/ingest) for the full architecture, the
OpenTelemetry Collector side, and operational guidance.

```yaml theme={null}
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 ]
```

Requires read-write mode. When absent, no consumer starts.

## Examples

<Tabs>
  <Tab title="Local development">
    ```yaml prometheus.yaml theme={null}
    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
    ```
  </Tab>

  <Tab title="Production (S3)">
    ```yaml prometheus.yaml theme={null}
    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
    ```
  </Tab>

  <Tab title="Testing (in-memory)">
    ```yaml prometheus.yaml theme={null}
    global:
      scrape_interval: 5s

    scrape_configs:
      - job_name: "test-app"
        static_configs:
          - targets: ["localhost:9090"]

    storage:
      type: InMemory
    ```
  </Tab>
</Tabs>