scylladb/docs/README-metrics.md

ScyllaDB metrics docs scripts

The following files extracts metrics from C++ source files and generates documentation:

• scripts/get_description.py - Metrics parser and extractor
• scripts/metrics-config.yml - Configuration for special cases only
• docs/_ext/scylladb_metrics.py - Sphinx extension for rendering

Configuration

The system automatically handles most metrics extraction. You only need configuration in the metrics-config.yml file for:

Complex parameter combinations:

"cdc/log.cc":
  params:
    part_name;suffix: [["static_row", "total"], ["clustering_row", "failed"]]
    kind: ["total", "failed"]

Multiple parameter values:

"service/storage_proxy.cc":
  params:
    _short_description_prefix: ["total_write_attempts", "write_errors"]

Complex expressions:

"tracing/tracing.cc":
  params:
    "max_pending_trace_records + write_event_records_threshold": "max_pending_trace_records + write_event_records_threshold"

Group assignments:

"cql3/query_processor.cc":
  groups:
    "80": query_processor

Skip files:

"seastar/tests/unit/metrics_test.cc": skip

Validation

Use the built-in validation to check all metrics files:

# Validate all metrics files
python scripts/get_description.py --validate -c scripts/metrics-config.yml

# Validate with verbose output
python scripts/get_description.py --validate -c scripts/metrics-config.yml -v

The GitHub workflow docs-validate-metrics.yml automatically runs validation on PRs to master that modify .cc files or metrics configuration.

Common fixes

• "Parameter not found": Add parameter mapping to config params section
• "Could not resolve param": Check parameter name matches C++ code exactly
• "No group found": Add group mapping or verify add_group() calls