Documentation by ClonePartner

Start typing to search.

Job & Dashboard Reference

Metrics config

View Markdown

Configure the task-level metrics array and every backend: noop, sqlite, statsd, http, and mssql, with each config key and default.

Metrics config

Envoy collects execution metrics through pluggable backends declared per task under a top-level metrics: key. Each entry is { backend, config }; the backend registry in src/metrics/index.ts resolves the backend name and constructs the backend with its config. When no metrics are configured, a zero-overhead noop collector is used.

There is no server-level metrics: key — the array lives in task YAML only. For querying and monitoring collected metrics, see Metrics and observability.

Configuration

metrics:
  - backend: sqlite
    config:
      path: ./metrics.db
  - backend: statsd
    config:
      host: ${STATSD_HOST}
      port: 8125
      prefix: envoy
  • backend is required on every entry; a missing value fails parsing with Metrics entry at index <n> must have a backend.
  • config is optional and backend-specific. ${VAR} references in config are resolved from environment variables before the backend is constructed.
  • Multiple backends can be active simultaneously; every metric is fanned out to all of them.
  • An unknown name fails with Unknown metrics backend: <name>. Available: noop, sqlite, statsd, http, mssql.

noop

Does nothing. Useful for explicitly disabling metrics. Takes no config keys.

sqlite

Writes metrics to a local SQLite database (metrics table, WAL mode), buffering and accumulating counters and histograms between flushes.

Config Type Default Description
path string metrics.db Path to the SQLite database file.
flush_interval_ms number 5000 Flush interval.
flush_batch_size number 100 Flush when the buffer reaches this size.
retention_days number 7 Prune metrics older than this many days. 0 disables pruning.
prune_interval_minutes number 60 How often pruning runs.

statsd

Sends metrics over UDP in StatsD format. Compatible with DogStatsD-style collectors.

Config Type Default Description
host string 127.0.0.1 StatsD server host.
port number 8125 StatsD server port.
prefix string envoy Prefix prepended to all metric names.
dogstatsd_tags boolean true Use DogStatsD tag format (key:value).
max_packet_size number 1432 Max UDP packet size before splitting.
flush_interval_ms number 1000 Buffer flush interval.

http

Pushes batched metrics as JSON to an HTTP endpoint with POST. Failed pushes are re-buffered and retried on the next flush.

Config Type Default Description
endpoint string — Required. URL the batch is posted to. Missing value fails with HttpMetricsBackend requires an "endpoint" config value.
auth_token string — Sent as Authorization: Bearer <token> when set.
flush_interval_ms number 2000 Flush interval.
flush_batch_size number 50 Flush when the buffer reaches this size.

mssql

Writes metrics to a metrics table in Microsoft SQL Server, creating the table and indexes if needed.

Config Type Default Description
server string — SQL Server host.
database string — Database name.
user string — Login user.
password string — Login password.
port number — Server port.
encrypt boolean — Encrypt the connection.
trust_server_certificate boolean — Trust the server certificate.
pool_size number 2 Connection pool size.
flush_interval_ms number 5000 Flush interval.
flush_batch_size number 100 Flush when the buffer reaches this size.
retention_days number 7 Prune metrics older than this many days. 0 disables pruning.
prune_interval_minutes number 60 How often pruning runs.

Collected metrics

All metrics are collected automatically — no task changes beyond the metrics: block.

Metric Type Description
envoy.task.duration_ms histogram Total task execution time.
envoy.task.items_total counter Items that reached the output collector.
envoy.task.status counter Completion status (success/error).
envoy.step.duration_ms histogram Wall-clock time for the entire step.
envoy.step.execute_duration_ms histogram Per-item execute() call duration.
envoy.step.items_in counter Items received.
envoy.step.items_out counter Items emitted downstream.
envoy.step.errors counter Failed execute() calls.
envoy.step.inflight gauge Current concurrent execute() calls.
envoy.step.skipped counter Items skipped by run_if/skip_if.
envoy.connector.calls counter Total callMethod invocations.
envoy.connector.call_duration_ms histogram Per-call duration.
envoy.connector.errors counter Failed calls.

The persisting backends (sqlite, http, mssql) drop the high-churn envoy.step.inflight gauge; statsd forwards it.