Configuration¶

The Carbonizer is configured by a single YAML file. On the shipped RPM the default path is /etc/pdns-carbonizer/carbonizer.yml, and a heavily-commented template with every option is installed next to it as /etc/pdns-carbonizer/carbonizer.example.yml. The location can be overridden with --config (see Operations → command-line flags).

The format intentionally mirrors a subset of the Prometheus configuration file, so existing Prometheus knowledge transfers directly. Carbonizer-only extensions are clearly marked below. The service does not validate against the Prometheus schema — Prometheus will reject this file because of the extra options, and the Carbonizer will reject some unsupported Prometheus options. The two cannot share the exact same file.

Every config option is documented on this page. Use your browser's in-page search (Ctrl/⌘-F) to jump straight to the field you care about.

Top-level structure¶

Parameter	Type	Default	Description
`global`	`Global`	`{}`	Defaults for all scrape jobs.
`carbonizer`	`Carbonizer`	`{}`	Carbonizer-specific settings (destinations, templates, recording, debug surfaces).
`scrape_configs`	`[]ScrapeConfig`	`[]`	One entry per scrape job. The Carbonizer exits at startup if this list is empty.

Deprecation policy¶

None. All historical options are still accepted.

Full example¶

The file below is example.yml from the source tree and is installed as /etc/pdns-carbonizer/carbonizer.example.yml. It exercises the common options with explanatory comments. The per-section reference below is authoritative; this block is for orientation.

Click to expand the shipped example.yml

# Global Prometheus compatible options.
global:
  # These set the defaults for the scrape jobs.
  # How often to scrape metrics (default 1 minute if not set)
  scrape_interval: 15s
  #scrape_timeout: 10s

# Carbonizer specific global options.
# Bind address format examples: ":1234", "127.0.0.1:1234", "[::1]:1234"
carbonizer:
  # Port you can connect to for verbose debug dumps (default: none)
  #debug_address: "127.0.0.1:4848"

  # Port you can connect to for realtime carbon dumps (default: none)
  #listen_address: ":4849"

  # HTTP port that serves our own /metrics and the status page (default: none)
  http_address: "127.0.0.1:9480"

  # List of destinations to send Carbon to (Graphite or compatible servers).
  # Both host and port are required.
  destinations:
    - 127.0.0.1:2003

  # The default template used to generate carbon metrics (you can override this
  # per job).
  #template: "carbonizer.$job.$instance.$__name__.$__labels__"

  # Globally ignored labels for $__labels__. It is usually better to define
  # this per job instead.
  #ignore_labels:
  #  - some_useless_label

  # Connect timeout for destinations.
  #connect_timeout: 2s

  # Spread scrapes over this interval instead of starting all simultaneously.
  #scrape_spread: 1s

  # Enable verbose logging for scrape errors and success (defaults: false)
  #log_scrape_errors: true
  #log_scrape_success: true

  record:
      # Nothing is recorded if not set.
      dest_dir: tmp/carbonizer-recordings/
      #file_duration: 1h
      #keep_duration: 72h

scrape_configs:
  - job_name: 'carbonizer' # Scrape own metrics
    scrape_interval: 5s
    scrape_timeout: 1s
    static_configs:
      - targets: ['localhost:9480']

global¶

Defaults for the scrape jobs. The same field set as the Prometheus global: block, but only the two values below are read.

Parameter	Type	Default	Description
`scrape_interval`	`go: Duration`	`1m`	How often each scrape job polls its targets, unless overridden per job.
`scrape_timeout`	`go: Duration`	`10s`	Per-request HTTP timeout for each scrape, unless overridden per job.

carbonizer¶

Carbonizer-specific global options. None of these have direct equivalents in Prometheus.

Bind addresses use the standard Go host:port form. Empty host (e.g. ":9480") binds on all interfaces; an explicit 127.0.0.1 or [::1] binds on loopback only.

Output¶

Parameter	Type	Default	Description
`destinations`	`[]string`	`[]`	List of `host:port` Carbon/Graphite servers to forward to over TCP. Empty list means no Carbon is sent (a warning is logged at startup).
`connect_timeout`	`go: Duration`	`2s`	TCP connect timeout per destination. Each batch opens a new connection, so keep this short.

HTTP and debug surfaces¶

Parameter	Type	Default	Description
`http_address`	`string`	`""` (disabled)	Bind address for the HTTP server that exposes the status page, `/metrics`, the per-target last-scrape views, and `/tap`. See Operations → HTTP endpoints.
`debug_address`	`string`	`""` (disabled)	TCP bind address that dumps the raw scrape body and the converted Carbon lines to every connected client. Very verbose.
`listen_address`	`string`	`""` (disabled)	TCP bind address that dumps just the Carbon lines that would be sent to a real destination. Useful for sanity-checking templates.

The three address fields can also be set or overridden from the command line — see Operations → command-line flags.

Template defaults¶

These set the defaults for all scrape_configs. Each job can override them with its own template and ignore_labels keys.

Parameter	Type	Default	Description
`template`	`string`	`carbonizer.$job.$instance.$__name__.$__labels__`	Default Carbon path template. See Architecture → Templates for the language.
`ignore_labels`	`[]string`	`[]`	Labels to exclude from `$__labels__`. Labels named explicitly in the template are always included regardless. Per-job `ignore_labels` are appended to this list, not replaced.

Scrape behaviour¶

Parameter	Type	Default	Description
`scrape_spread`	`go: Duration`	`1s`	The initial scrapes of all targets are spread over this interval to prevent CPU peaks every `scrape_interval`. The most efficient value is roughly equal to the typical `scrape_interval`. `0` disables spreading.
`log_scrape_errors`	`boolean`	`false`	Log a line for every scrape that fails (fetch or parse error).
`log_scrape_success`	`boolean`	`false`	Log a line for every scrape that succeeds. Useful in development; very chatty in production.

record¶

Optional automatic recording of every successful scrape to a rolling directory of compressed files. See Architecture → Recording format for what the files contain. Disabled if dest_dir is empty.

Parameter	Type	Default	Description
`dest_dir`	`string`	`""` (disabled)	Directory to write recording files into. Created if missing. Recording is only enabled when this is set.
`file_duration`	`go: Duration`	`1h`	How long each file is appended to before rolling over to a new one. `h` is the largest unit Go durations support.
`keep_duration`	`go: Duration`	`72h`	How long files are kept before being deleted by the periodic cleanup. The decision uses the file's start time, so set `file_duration` significantly smaller than `keep_duration`.

Note

Recordings are bzip2-compressed with a sizeable buffer. With a low scrape rate it can take several minutes before any data appears in a freshly opened file. This is expected — Close() flushes when the file rolls over.

scrape_configs¶

A list of scrape jobs. The Carbonizer logs ERROR: No scrape targets defined, exiting. and exits if this list is empty.

This is a strict subset of the Prometheus scrape_configs schema. Service discovery (*_sd_configs), relabeling, and TLS options are not supported; only the fields below are read. The two Carbonizer-only fields (template, ignore_labels) are extensions Prometheus will reject.

Parameter	Type	Default	Description
`job_name`	`string`	—	Free-form job label. Becomes `$job` in the template and appears in all per-job metrics. Required.
`scrape_interval`	`go: Duration`	inherits `global.scrape_interval`	How often each target in this job is polled.
`scrape_timeout`	`go: Duration`	inherits `global.scrape_timeout`	Per-request HTTP timeout for this job's scrapes. Also sent to the target as `X-Prometheus-Scrape-Timeout-Seconds`.
`honor_labels`	`boolean`	`false`	If `true`, keep `job` and `instance` labels that already exist on scraped metrics instead of overwriting them. Only enable for trusted services that aggregate metrics from multiple sources. See Architecture → Honor labels.
`scheme`	`string`	`http`	URL scheme used to fetch each target. `http` or `https`.
`metrics_path`	`string`	`/metrics`	URL path used to fetch each target.
`static_configs`	`[]StaticConfig`	`[]`	The list of targets to scrape. Only static target lists are supported.
`basic_auth`	`BasicAuth`	`{}`	Optional HTTP Basic auth credentials sent on every scrape request.
`proxy`	`[ProxyConfig](https://github.com/PowerDNS/go-tlsconfig)`	`{}`	Optional HTTP/SOCKS5 proxy. Without it, the standard `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` environment variables apply.
`template`	`string`	inherits `carbonizer.template`	Carbon path template for this job. Overrides the global default.
`ignore_labels`	`[]string`	inherits `carbonizer.ignore_labels`	Labels to exclude from `$__labels__` for this job. The global list is appended after this one — both apply.

A sample is dropped from the Carbon output if the template references a label that the scraped metric does not have. This is by design: it keeps the dotted path well-formed. To diagnose dropped samples, watch carbonizer_carbon_convert_metric_error_total.

static_configs¶

Parameter	Type	Default	Description
`targets`	`[]string`	`[]`	List of `host:port` targets to scrape. Each entry produces one independent scraper goroutine and becomes `$instance` in the template.

basic_auth¶

If either field is non-empty, the scrape request is sent with HTTP Basic auth.

Parameter	Type	Default	Description
`username`	`string`	`""`	Basic auth username.
`password`	`string`	`""`	Basic auth password.

proxy¶

Single-field wrapper around the shared go-tlsconfig proxy helper.

Parameter	Type	Default	Description
`url`	`string`	`""`	Proxy URL, e.g. `http://user:password@proxy.example:8080`. Schemes: `http`, `https`, `socks5`, `socks5h`. Empty falls back to the standard `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY` environment variables.

scrape_configs:
  - job_name: 'cadvisor'
    honor_labels: true
    static_configs:
      - targets: ['cadvisor:8080']

  - job_name: 'pdns-recursor'
    ignore_labels:
      - pdns_metric
    static_configs:
      - targets: ['192.168.99.2:9153']

  - job_name: 'pdns-recursor-classic'
    # Use the original metric name from the platform exporter, unescaped.
    template: "pdns.$instance.recursor.$=pdns_metric"
    static_configs:
      - targets: ['192.168.99.2:9153']