Unlocking Versioned Metrics: The First Release Candidate in Hostmetrics
Versioned metrics exist to address the challenge of evolving metric definitions while maintaining compatibility with existing systems. By allowing both legacy and new definitions to coexist, you can ensure that your observability stack remains robust and adaptable. This is particularly crucial in dynamic environments where metrics can change frequently, and you need to avoid breaking existing integrations.
To implement versioned metrics, mdatagen has been enhanced to support suffixes that denote versions, using the format <metric-name>@<version-number>. This suffix is only a key in the metadata.yaml file and is stripped away during emission. For instance, a metric defined as process.cpu.utilization@v1 will be emitted simply as process.cpu.utilization. This allows you to manage transitions smoothly, using parameters like migration for aliasing, and feature gates to control which metrics are emitted based on your specific conditions.
In production, be mindful of the stability levels assigned to your metrics. The example provided uses stability: beta because mdatagen does not define a stability level for Release Candidates. This is a crucial detail that can impact your monitoring strategy. Always ensure that your feature gates are correctly configured to manage the emission of old and new metrics effectively, as this can prevent data loss during transitions.
Key takeaways
- →Understand versioned metrics to manage legacy and new definitions simultaneously.
- →Utilize mdatagen's suffix support for seamless metric versioning.
- →Configure feature gates to control metric emissions based on your conditions.
- →Pay attention to stability levels when defining new metrics.
- →Use migration parameters for aliasing during metric transitions.
Why it matters
In production, the ability to version metrics means you can evolve your observability strategy without risking data integrity. This flexibility is crucial for maintaining reliable monitoring as your applications grow and change.
Code examples
1process.cpu.utilization:
2 enabled:
3 false
4 description:
5 >-
6 Percentage of total CPU time used by the process since last scrape,
7 expressed as a value between 0 and 1. On the first scrape, no data point is emitted for this metric.
8 unit:
9 '1'
10 stability:
11 development
12 gauge:
13 value_type:
14 double
15 attributes:
16 [state]
17 migration:
18 to:
19 process.cpu.utilization@v1
20 through_gates:
21 disable_old:
22 scraper.process.DontEmitV0SystemConventions
23 enable_new:
24 scraper.process.EmitV1SystemConventions1process.cpu.utilization@v1:
2 enabled:
3 false
4 description:
5 >-
6 Difference in process.cpu.time since the last measurement, divided by the
7 elapsed time and number of CPUs available to the process. On the first
8 scrape, no data point is emitted for this metric.
9 unit:
10 '1'
11 stability:
12 beta
13 gauge:
14 value_type:
15 double
16 attributes:
17 [cpu.mode]When NOT to use this
The official docs don't call out specific anti-patterns here. Use your judgment based on your scale and requirements.
Want the complete reference?
Read official docsOpenAI & Anthropic-compatible inference API — no GPU provisioning needed. 55+ models, pay-per-token with no minimums. VPC + zero data retention by default.
Try Serverless Inference →Prometheus and OpenTelemetry: Bridging the Gap in 2026
The interoperability between Prometheus and OpenTelemetry has significantly improved, addressing key challenges in observability. With ongoing efforts to make Prometheus exporters compatible with OpenTelemetry Collector distributions, this integration is set to enhance your monitoring strategy.
Dual-Exporting .NET Metrics: Mastering OTLP and Prometheus
Unlock the power of dual-exporting metrics in your .NET applications with OTLP and Prometheus. Learn how to leverage the Meter class to efficiently collect and expose metrics through both exporters, ensuring comprehensive observability. This approach simplifies your monitoring setup and enhances your data collection strategy.
Prometheus Storage: Mastering Local Time Series Data
Prometheus's local storage is crucial for efficient time series data management. It uses a custom format and a write-ahead log to ensure data integrity during crashes. Dive in to understand how to optimize your storage setup.
Get the daily digest
One email. 5 articles. Every morning.
No spam. Unsubscribe anytime.