Config

Purpose

config/ defines the YAML schema for prometheus.yml, parses files into Go structs, validates them, and supports atomic reload.

Files

config/
├── config.go            # The whole schema (~67 KB, ~2,400 lines).
├── reload.go            # Filewatcher-based reload helper.
├── config_default_test.go
├── config_test.go       # ~131 KB of golden + scenario tests.
├── config_windows_test.go
├── reload_test.go
└── testdata/
    └── conf.good.yml    # The canonical valid config; every SD must add an entry here.

Top-level structure

global:
  scrape_interval: 15s
  evaluation_interval: 15s
  scrape_timeout: 10s
  external_labels: { ... }
  scrape_failure_log_file: /var/log/prom-fails.log
  body_size_limit: 0
  sample_limit: 0
  query_log_file: ...

runtime:
  gogc: 75

storage:
  tsdb:
    out_of_order_time_window: 0
    stale_series_compaction_threshold: 0 # 3.10 experimental
  exemplars: { max_exemplars: 100000 }

scrape_configs: [...]

rule_files: [...]

alerting:
  alertmanagers: [...]
  alert_relabel_configs: [...]

remote_write: [...]
remote_read: [...]

tracing:
  endpoint: ...
  insecure: true
  client_type: grpc | http

otlp:
  translation_strategy: NoUTF8EscapingWithSuffixes
  promote_resource_attributes: [...]
  promote_scope_metadata: false

The Config struct in config/config.go is one-to-one with the YAML.

Loading

cfg, err := config.LoadFile(path, false, slog.New(...))

LoadFile reads the file, calls config.Load(s, logger), and propagates any non-fatal warnings. config.Load initialises defaults, decodes via yaml.Unmarshal, calls every struct's Validate() method, and then walks discovery.Configs to expand SD-specific subtypes.

Validation rules (a sample)

• Every scrape_config name is unique; defaults to its position-derived name.
• scrape_interval >= scrape_timeout.
• static_configs entries must have a non-empty __address__.
• TLS configs reject mixing inline cert/key with cert_file/key_file.
• Labels must match the model's name regex ([_a-zA-Z][_a-zA-Z0-9]* plus UTF-8 aliasing).
• remote_write[].url cannot be empty.
• metric_relabel_configs.action=labelmap requires a regex.
• Reserved HTTP headers (reservedHeaders) cannot be set in remote-write headers.

The full set is enforced by per-struct Validate() methods. Adding a new field means adding a default and a validation step.

Reload

config/reload.go exposes ReloadConfig and a watcher that fires on filesystem events. The server's cmd/prometheus/main.go uses it indirectly — the watcher is wired via automaxprocs-style helpers and a periodic poll fallback.

A reload is considered successful only when every subsystem's ApplyConfig returns nil. On failure, the previously-successful config remains in effect and prometheus_config_last_reload_successful flips to 0.

Defaults

Defaults live as package-level vars at the top of config.go:

• DefaultConfig, DefaultGlobalConfig, DefaultScrapeConfig, DefaultRemoteWriteConfig, DefaultRemoteReadConfig, DefaultAlertmanagerConfig, DefaultRunningConfig, etc.

The UnmarshalYAML method on each struct copies the default before decoding, so unspecified fields take their defaults rather than zero values.

DirectorySetter

When a config has fields that are file paths (TLS certs, file_sd files, rule files), the relevant struct implements discovery.DirectorySetter so the loader can rewrite relative paths to be relative to the config file directory. Without it, paths in included files are interpreted relative to the working directory, which is rarely what the user wants.

Test fixtures

config/testdata/conf.good.yml is the golden valid config. New SDs must add an entry there. Failure modes are exercised in config_test.go::TestBadConfigs.

Integration points

• cmd/prometheus/main.go calls config.LoadFile and threads the *config.Config through every manager's ApplyConfig.
• promtool check config reuses the same loader.
• Discovery configs are dispatched through discovery.Configs (config.go::ScrapeConfig.ServiceDiscoveryConfigs).

Entry points for modification

• New top-level field: add to Config, give it a default, write a Validate() rule, and document it in docs/configuration/configuration.md.
• Add a per-scrape-config option: add to ScrapeConfig, propagate through scrape.Options, surface it on the loop, and update docs/configuration/configuration.md.
• Tighten existing validation: add a regression test in config_test.go::TestBadConfigs first; many users have older configs that may newly fail, so test the upgrade path.

See Reference: Configuration for the user-facing schema.