Configuration

The user-facing reference is docs/configuration/configuration.md. This page summarises the shape of prometheus.yml, where each top-level block lives in code, and the validation rules that gate it.

Top-level shape

global: { ... } # config.GlobalConfig
runtime: { ... } # config.RunningConfig (gogc, pgocache)
storage: { ... } # config.StorageConfig (TSDB + exemplars)
scrape_configs: [...] # []*config.ScrapeConfig
rule_files: [...]
scrape_config_files: [...] # included scrape configs (3.x)
alerting: { ... } # config.AlertingConfig
remote_write: [...] # []*config.RemoteWriteConfig
remote_read: [...] # []*config.RemoteReadConfig
tracing: { ... } # config.TracingConfig
otlp: { ... } # config.OTLPConfig

Each top-level block has a Go struct of the same name in config/config.go. Defaults are package-level vars (DefaultConfig, DefaultGlobalConfig, etc.).

global

Field	Default	Notes
scrape_interval	1m	Default for all scrape configs.
scrape_timeout	10s	Must be <= scrape_interval.
evaluation_interval	1m	Rule group default.
external_labels	(empty)	Appended to alerts and federation responses.
query_log_file	(empty)	JSONL query log; rotated on SIGHUP.
scrape_failure_log_file	(empty)	JSONL of failed scrapes.
body_size_limit	0 (unlimited)	Bytes.
sample_limit	0	Per-scrape sample cap.
target_limit	0	Per-pool target cap.
extra_scrape_metrics	false	3.x replacement for the extra-scrape-metrics flag.
metric_name_validation_scheme	utf8	legacy or utf8.
scrape_protocols	(auto)	Negotiation order; default starts with PrometheusProto.
scrape_classic_histograms	false	Send _bucket if target also has native.

scrape_configs[]

The full set is in config/config.go::ScrapeConfig (~150 fields). Highlights:

• job_name (required, unique).
• scrape_interval, scrape_timeout, metrics_path, scheme, params, body_size_limit, sample_limit, target_limit, label_limit, etc.
• relabel_configs[] (pre-scrape) and metric_relabel_configs[] (post-parse).
• static_configs[], <sd>_sd_configs[] (one per registered SD).
• tls_config, basic_auth, bearer_token / bearer_token_file, oauth2, proxy_url, proxy_connect_header, enable_compression, enable_http2.
• honor_labels, honor_timestamps, track_timestamps_staleness.

Validation rules include unique job names, mutually exclusive auth options (basic_auth xor bearer_token xor oauth2), and reserved-headers rejection.

rule_files[] and scrape_config_files[]

Both accept glob patterns relative to the directory of the main config file (because the loader implements discovery.DirectorySetter). rule_files[] are loaded by rules.Manager; scrape_config_files[] are merged into the main config at load time.

alerting

alerting:
  alert_relabel_configs: [...]
  alertmanagers:
    - timeout: 10s
      api_version: v2
      <sd>_sd_configs: [...]
      static_configs: [...]
      relabel_configs: [...]
      tls_config: { ... }
      basic_auth: { ... }

Same SD framework as scrape configs. api_version: v2 is the default.

remote_write[] / remote_read[]

See Remote write feature and Remote read feature for the operational view. config/config.go::RemoteWriteConfig and RemoteReadConfig define the schema.

tracing

tracing:
  endpoint: tempo:4317
  client_type: grpc | http
  insecure: true
  timeout: 10s
  sampling_fraction: 0.1
  tls_config: { ... }
  headers: { ... }

otlp

otlp:
  translation_strategy: NoUTF8EscapingWithSuffixes | UnderscoreEscapingWithSuffixes
  promote_resource_attributes: [service.name, service.namespace, ...]
  promote_scope_metadata: false

storage

storage:
  tsdb:
    out_of_order_time_window: 30m
    stale_series_compaction_threshold: 0 # 3.x experimental
  exemplars:
    max_exemplars: 100000

CLI flags

The CLI flag list is generated to docs/command-line/prometheus.md and docs/command-line/promtool.md via make cli-documentation. Many flags are mirrored by config-file equivalents — when both are set, the CLI flag wins.

Reload

SIGHUP (or POST /-/reload with --web.enable-lifecycle) triggers a reload. The new config is parsed, validated, and applied to every manager. If any ApplyConfig returns an error, the reload aborts and the previous config remains in effect (prometheus_config_last_reload_successful flips to 0).

Validation

All validation lives in per-struct Validate() methods in config/config.go. New fields must:

1. Have a default in Default*Config.
2. Apply that default in the relevant UnmarshalYAML.
3. Validate ranges and mutual exclusivity in Validate.
4. Be added to config/testdata/conf.good.yml so the round-trip test catches DeepEqual regressions.

See Config subsystem for the loading / reload flow.