Course contentsShow
← System Design
Lesson 1216 of 1,91930. Observability: MetricsFree lesson

Metric Documentation and Discovery

Maintaining metric catalogs with descriptions, units, and examples so teams understand what metrics measure.

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.