This version is still in development and is not considered stable yet. For the latest stable version, please use Korvet 0.12.5!

Metrics Contract

This contract defines the shared observability rules for the runtime metrics rollout.

Stability Policy

The rollout is additive only:

  • Existing metric names must not be renamed or removed during the rollout.

  • Existing tag keys on exported metrics must not be removed or repurposed.

  • New metrics and new tag keys may be added when they follow the shared vocabulary on this page.

  • Breaking metric changes require a separate deprecation and migration plan.

Shared Catalog

The korvet-observability module is the single source of truth for:

  • Shared metric names

  • Shared tag keys

  • Micrometer helpers that register meters against the global registry

Current preserved Korvet metric families:

  • korvet.produce.*

  • korvet.fetch.*

  • korvet.errors

  • korvet.lossy_offsets

  • korvet.backpressure.*

  • korvet.storage.archive.*

  • korvet.storage.parquet.*

  • korvet.storage.delta.*

Allowed Tag Keys

Only the following tag keys are allowed for Korvet-owned metrics:

  • topic

  • partition

  • operation

  • result

  • error_type

  • phase

  • stream

  • tier

  • compression

  • value_type

  • api_key

  • command

  • local

  • remote

  • module

Use the smallest tag set that still supports aggregation and debugging.

Forbidden High-Cardinality Tags

The following tag keys are forbidden on Korvet-owned metrics because they explode time-series cardinality:

  • consumer

  • consumer_group

  • message_id

  • offset

  • partition_epoch

  • request_id

  • session_id

  • transaction_id

  • user_id

If a new use case seems to require one of these dimensions, that is a design review item, not a local implementation decision.