Skip to content

Command-line reference

Command-line reference

Every command exits 0 on success and 1 on failure, with the reason on stderr; a flag it does not know, or a missing one, exits 2. telemetryd <command> --help prints what is here, for the binary you have.

Commands that read the configuration take -c, --config <PATH> (discovered when omitted) and --data-dir <DIR> (./telemetryd-data if it exists, else the platform data directory). Commands that talk to a running instance take --url (default http://127.0.0.1:4319) and a token; pass tokens through the environment variable named, since an argument shows in ps and in shell history.

Command Does
serve run the server
status print a running instance's status
query run a LogQL query against a running instance
export write a time range out as OTLP, or post it to another instance
import read a time range in, from another instance or an export file
validate check a configuration and show where each value came from
clickhouse schema print the ClickHouse statements an instance would run
clickhouse check check the ClickHouse account can do what an instance needs
clickhouse migrate bring a ClickHouse database up to this version's layout
clickhouse import copy a stopped single node's data directory into ClickHouse
init write a configuration with generated tokens
service print, install or remove a service unit
version print version and build information

serve

Runs the server. Works with no arguments at all.

Flag Default
-c, --config <PATH> discovered telemetryd.toml
--data-dir <DIR> see above where to store data
--listen <ADDR> server.listen one port serves ingest, query and the UI APIs
--insecure off allow a non-loopback address with no token configured; refused otherwise
--log-level <LEVEL> log.level trace, debug, info, warn or error

SIGHUP re-reads the configuration: credentials, retention.*, storage.disk_budget and log.level change in place, and anything else is refused by name. See the configuration reference.

status

Flag Default
--url <URL> http://127.0.0.1:4319 the instance
--token <TOKEN> TELEMETRYD_AUTH_ADMIN_TOKEN admin token; the query token on an instance with none
--json off the raw /status JSON instead of the summary

query

telemetryd query [LOGQL]. Without a query, everything from the last hour.

Flag Default
--since <DURATION> 1h how far back
--limit <N> 100 most recent first, up to this many
--forward off oldest first
--output <text|json> text json is one object per line
--url <URL> http://127.0.0.1:4319 the instance
--token <TOKEN> TELEMETRYD_AUTH_QUERY_TOKEN query token

A metric query (sum by (app) (count_over_time({level="error"}[1h]))) is answered at now, one line per series. See Query from the shell.

export

Flag Default
--since <DURATION> 1h how far back
--query <LOGQL> {app=~".+"} what to export; a selector must require a value
--signal <logs|traces|metrics> logs anything but logs needs the source to be a telemetryd
--url <URL> http://127.0.0.1:4319 the instance to read from
--token <TOKEN> TELEMETRYD_AUTH_QUERY_TOKEN token for --url
--output <PATH> stdout where to write
--to <URL> — post to another instance instead, through /api/v1/export: all three signals at full fidelity
--to-token <TOKEN> TELEMETRYD_AUTH_INGEST_TOKEN ingest token for --to
--progress <auto|tty|plain|json|none> auto a live meter on a terminal, lines otherwise; json is NDJSON on stderr

See Getting data out, and bringing it in.

import

Flag Default
--from <URL> — a Loki-compatible API to read from
--file <PATH> — a file telemetryd export wrote; - is stdin
--since <DURATION> 1h how far back
--query <LOGQL> {app=~".+"} what to import
--from-token <TOKEN> — token for --from
--signal <logs|traces|metrics> logs metrics come through Prometheus remote read, with their own timestamps
--url <URL> http://127.0.0.1:4319 the instance to write into
--token <TOKEN> TELEMETRYD_AUTH_INGEST_TOKEN ingest token for --url
--progress <…> auto as for export
--allow-expiring off import a range older than the destination keeps; refused otherwise, since it would be deleted

validate

Takes --config and --data-dir. Type-checks the configuration, runs the cross-field rules, and prints every resolved value with the layer it came from.

clickhouse schema

Prints every statement an instance would run — database, tables, views, TTLs, in order, each idempotent — for a DBA to review or run.

Flag Default
--shards <auto|one|many> auto auto asks the server how many shards clickhouse.cluster has; one (replicated tables) and many (each shard's tables, Distributed over them) print without connecting

clickhouse check

Takes --config and --data-dir. Connects with the configured account and checks, changing nothing: the password can be read, the server answers, the database and every table and view are there or can be made, system.parts is readable, and the cluster and storage policy named exist.

clickhouse migrate

Brings a database an older telemetryd created up to this version's layout while instances keep writing. Every step can be repeated, and an interrupted run continues where it stopped. See Upgrading a deployment.

Flag Default
--dry-run off say what would be done; change nothing
--backfill off fill in rollups created after the rows they summarise; reads those rows once
--materialize-indexes off index partitions written before an index existed, then drop the indexes it replaces
--keep-old off keep a rebuilt table's old copy under its temporary name
--take-over off go ahead although another run holds the lease — for a run that died, never one still running
--statement-timeout <DURATION> 6h how long one statement may take
--json off NDJSON events on stdout

clickhouse import

Copies a stopped single node's data directory — sealed segments and the write-ahead log — into ClickHouse, writing records as an instance would. Resumes where an interrupted run stopped. See Moving from one node.

Flag Default
--from-data-dir <DIR> required the single node's data directory; it must be stopped
--signal <logs|traces|metrics> all three which signals
--since <DURATION> the destination's retention only records this recent
--batch <N> 50000 records per insert
--restart off start from the beginning
--json off NDJSON events on stdout

init

Flag Default
--dir <DIR> /etc/telemetryd where the configuration and token files go
--force off overwrite an existing configuration, which rotates every token

service

telemetryd service print, install and uninstall. print and install take --user <USER> (default telemetryd), the system user the service runs as; it is created only when it is the default and does not exist. See Run it as a service.

version

--check also asks GitHub whether a newer release exists — the only thing telemetryd ever contacts outside your infrastructure, and only when asked.