Sổ tay kỹ thuật

Prometheus config – scrape, relabel, file_sd, promtool

cheatsheet#prometheus#telemetry· cập nhật 2026-11-06

Tra nhanh các khối scrape_configs, relabel_configs, metric_relabel_configs, file_sd và lệnh promtool khi sửa prometheus.yml.

Sửa trang này
Mục lục

Ví dụ dùng schema chung của section: label source (thiết bị) và name (interface). Query xem PromQL cheatsheet, scrape SNMP xem snmp_exporter.

Khung prometheus.yml

/etc/prometheus/prometheus.yml
global:
  scrape_interval: 30s
  scrape_timeout: 10s          # phải ≤ scrape_interval
  evaluation_interval: 30s
  external_labels:
    region: hni                # gắn khi gửi ra ngoài (remote_write, federation, Alertmanager)
 
rule_files: ["rules/*.yml"]
 
scrape_configs:
  - job_name: telegraf
    static_configs:
      - targets: ["telegraf-01.example.net:9273"]
        labels: {site: hni}
  - job_name: network-file-sd
    file_sd_configs:
      - files: ["targets/*.yml"]
        refresh_interval: 5m

Tham số scrape_config hay dùng

Mục đích Tham số
Ghi đè chu kỳ/timeout cho riêng job scrape_interval: 60s, scrape_timeout: 50s
Đổi path / scheme metrics_path: /snmp, scheme: https
Query string gửi kèm params: {module: [if_mib]}
Giữ label do target tự đặt (federation, pushgateway) honor_labels: true
Bỏ timestamp do target gửi honor_timestamps: false
Basic auth / bearer token từ file basic_auth: {username: prom, password_file: /etc/prometheus/pass} / authorization: {credentials_file: /etc/prometheus/token}
TLS tới target tls_config: {ca_file: /etc/prometheus/ca.pem, insecure_skip_verify: false}
Chặn target trả quá nhiều series sample_limit: 50000 (vượt thì cả lần scrape bị coi là lỗi)

Meta label trong relabel_configs

Label Ý nghĩa
__address__ host:port sẽ scrape; sau relabel, nếu không có instance thì instance lấy giá trị này
__scheme__, __metrics_path__ Scheme và path của lần scrape
__param_<tên> Tham số URL ?<tên>=...
__scrape_interval__, __scrape_timeout__ Ghi đè interval/timeout theo từng target
__meta_* Label do service discovery sinh (vd __meta_filepath với file_sd)
__tmp_* Tên tự đặt để lưu tạm, không bao giờ được Prometheus dùng

Mọi label bắt đầu bằng __ bị xoá sau bước relabel_configs, nên muốn giữ thì phải copy sang label thường.

Action của relabel

Mặc định: action: replace, separator: ";", regex: (.*), replacement: $1. Regex luôn được neo hai đầu (^...$).

Mục đích Rule
Copy label {source_labels: [__param_target], target_label: source}
Gán giá trị cố định {target_label: __address__, replacement: "snmp-exporter.example.net:9116"}
Lấy một phần (bỏ port) {source_labels: [__address__], regex: "([^:]+):\\d+", target_label: source}
Ghép nhiều label {source_labels: [source, name], separator: "/", target_label: if_id}
Chỉ giữ target khớp {source_labels: [site], regex: "hni|hcm", action: keep}
Bỏ target khớp {source_labels: [role], regex: lab, action: drop}
Đổi tên hàng loạt từ meta label {regex: "__meta_kubernetes_pod_label_(.+)", action: labelmap}
Xoá label {regex: "ifAlias|ifDescr", action: labeldrop}
Chỉ giữ một số label {regex: "__name__|source|name|job|instance", action: labelkeep}
Chia target cho nhiều Prometheus {source_labels: [__address__], modulus: 2, target_label: __tmp_hash, action: hashmod} rồi {source_labels: [__tmp_hash], regex: "0", action: keep}
Chữ thường {source_labels: [source], target_label: source, action: lowercase}

relabel_configs và metric_relabel_configs

Khối Chạy lúc nào Dùng để
relabel_configs Trước khi scrape, trên target Chọn target, đổi __address__, gắn label source/site
metric_relabel_configs Sau khi scrape, trên từng series, trước khi ghi TSDB Bỏ metric/label gây cardinality cao, đổi tên metric
write_relabel_configs Trong remote_write Lọc series gửi ra ngoài
metric_relabel_configs mẫu
metric_relabel_configs:
  - source_labels: [__name__]
    regex: "go_.*|process_.*"         # bỏ metric runtime của exporter
    action: drop
  - source_labels: [__name__, name]
    regex: "interfaces_.*;(Null|Loopback).*"
    action: drop                      # bỏ interface ảo
  - regex: "description|path"
    action: labeldrop                 # label động, làm nổ cardinality

file_sd

/etc/prometheus/targets/routers-hni.yml
- targets: ["198.51.100.11:9273", "198.51.100.12:9273"]
  labels:
    site: hni
    role: pe

Prometheus tự đọc lại khi file đổi (không cần reload). Dạng .json cũng được: [{"targets": [...], "labels": {...}}]. Sinh file này từ inventory (Ansible, NetBox) là cách đơn giản nhất để đồng bộ danh sách thiết bị.

promtool và vận hành

Mục đích Lệnh
Kiểm tra config (kèm rule_files) promtool check config /etc/prometheus/prometheus.yml
Chỉ kiểm cú pháp, bỏ qua file tham chiếu promtool check config --syntax-only prometheus.yml
Lint output của exporter curl -s localhost:9273/metrics | promtool check metrics
Unit test rule promtool test rules tests/interfaces_test.yml
Query khoảng thời gian promtool query range --start=$(date -d '-1 hour' +%s) --end=$(date +%s) --step=60s http://localhost:9090 'up'
Phân tích cardinality của TSDB promtool tsdb analyze /var/lib/prometheus
Reload không restart kill -HUP $(pidof prometheus) hoặc curl -X POST localhost:9090/-/reload (cần --web.enable-lifecycle)
Xem target và lỗi scrape curl -s localhost:9090/api/v1/targets | jq '.data.activeTargets[] | {scrapeUrl, health, lastError}'
Xem label trước/sau relabel Web UI → Status → Targets (hoặc Service Discovery)

Metric scrape_samples_scraped, scrape_duration_seconds và up có sẵn cho mọi target: topk(10, scrape_samples_scraped) cho biết exporter nào đang đẩy nhiều series nhất.