Metric Documentation and Discovery
What You'll Learn
You'll learn how to maintain metric catalogs so teams can quickly understand what each metric measures, avoiding confusion and misuse across your organization.
Why Metric Documentation Matters
Imagine joining a team and discovering hundreds of metrics with names like user_events_total, api_latency_ms, and cache_hit_rate. Without documentation, you're left guessing: What events count? Which API endpoints? What cache layer?
Metric documentation solves this by creating a searchable catalog where each metric includes:
- Description: What the metric measures in plain language
- Units: milliseconds, bytes, requests/second, percentage
- Examples: Sample values and typical ranges
- Owner: Which team maintains it
- Query examples: How to use it in PromQL or other query languages
Building a Discoverable Catalog
Think of your metric catalog like a library card system. Without it, finding the right book (metric) is impossible. With it, everyone knows where to look.
Key components:
- Naming conventions (already established) ensure consistency
- Automated extraction from metric systems using their metadata APIs
- Version control for documentation alongside code
- Search functionality by name, tag, or owner
- Usage examples showing common queries and dashboards
Many teams use tools like Prometheus's metadata API, internal wikis, or dedicated platforms like Datadog's metric summaries to maintain these catalogs.
Discovery in Practice
When someone asks "How do I measure cache performance?", they should search the catalog and immediately find cache_hit_rate with a description: "Ratio of cache hits to total requests, measured per service instance. Range: 0.0-1.0"
Key Takeaway:
A well-maintained metric catalog with descriptions, units, and examples transforms metrics from mysterious numbers into actionable insights that any team member can understand and use confidently.