0.3.0

This version adds MVX Metrics as a new foundation-level public component of mvx-common.

MVX Metrics is a backend-neutral metric event and aggregation layer for applications and reusable Python libraries that need measurable runtime visibility without binding production code to a specific monitoring backend.

This release also updates the public package positioning: mvx-common now provides two main public components, MVX Logger and MVX Metrics.

Added

MVX Metrics

Added MVX Metrics as a new public component of mvx-common.

MVX Metrics provides a structured metric event and aggregation layer. Production code reports what happened through metric events. Metrics decide which events are relevant, how those events affect their dimensions, and how aggregated runtime state is exposed through snapshots.

Key features

  • emit structured metric events instead of manually updating raw counters in production code

  • let production code describe what happened while metrics decide how to interpret events and update quantitative dimensions

  • keep domain-specific metric meaning close to the component that owns the domain, without coupling that component to metric collection, export, storage, or visualization infrastructure

  • keep recorders, runtimes, and future adapters generic, so they can collect and deliver metric events without knowing business-specific metric semantics

  • change the final observability backend by replacing recorders or adapters instead of changing event-producing production code

  • keep metric emission lightweight on the production path while aggregation and delivery are handled outside the business operation flow

  • support both synchronous and asynchronous event-producing code through a small recorder contract and runtime boundary

  • safely bridge thread and event-loop boundaries for metric processing

  • expose metric snapshots as stable aggregated runtime state for diagnostics, tests, dashboards, exporters, and higher-level health checks

  • provide clear extension points for future integrations through snapshots, recorder hooks, custom recorders, and metrics runtime support without turning the core package into a monitoring platform

MVX Metrics is not a replacement for Prometheus, OpenTelemetry, StatsD, monitoring dashboards, metric storage, alerting, or visualization systems. It is the backend-neutral core layer that can sit before those tools or other export backends.

Metric event and metric model

Added the core metric event and metric abstractions:

MetricEvent
Metric
MetricsRecorderProto

MetricEvent defines the input fact reported by production code.

Metric defines the interpretation and aggregation boundary. A metric decides whether a received event is relevant, updates its own internal state, and exposes that state through snapshots.

MetricsRecorderProto defines the small recorder contract used by production code and reusable library components.

Asyncio metrics recorder

Added AsyncioMetricsRecorder as the default recorder implementation for asynchronous metric event processing.

The recorder provides:

thread-safe event acceptance
lazy startup
event buffering
pending-event accounting
overflow handling
metric dispatch
metric snapshot access
start and stop lifecycle
recorder hooks

The recorder keeps metric event emission lightweight on the production path while metric-side processing is handled outside the business operation flow.

Metrics runtime

Added MetricsRuntime for running metrics recorders outside the production operation flow.

The runtime provides:

dedicated thread and event loop management
recorder creation
recorder lookup
recorder stop and removal
runtime shutdown

The runtime is an execution boundary for metrics processing. It is not a monitoring backend and does not own metric export, storage, querying, alerting, or visualization.

Metrics errors and lifecycle types

Added public errors, lifecycle states, outcomes, and overflow policy types used by the metrics recorder and runtime APIs.

These types make recorder and runtime behavior explicit and allow applications and tests to reason about metrics lifecycle outcomes without depending on implementation details.

Changed

Package public positioning

Changed the public positioning of mvx-common.

mvx-common is no longer documented as a package whose main public component is only MVX Logger. It is now documented as a foundation package whose main public components are:

MVX Logger
MVX Metrics

MVX Logger entity id provider

Renamed the log_invocation entity id provider property from identity to entity_id.

The LogEntityIdProviderProto contract now expects:

@property
def entity_id(self) -> str: ...

log_invocation uses this value as LogEventMeta.entity_id when no explicit entity_id_getter is supplied.

Classes that rely on automatic method-based entity id resolution should expose entity_id instead of identity.

Documentation

MVX Metrics documentation

Added a full documentation section for MVX Metrics.

The documentation describes:

metrics overview
getting started
processing pipeline
recorder processing
runtime model
snapshot surface
extension model
failure model

Repository and package README files

Updated repository and package README files to describe mvx-common as a foundation package with two main public components:

MVX Logger
MVX Metrics

The README files now include separate descriptions and documentation links for MVX Logger and MVX Metrics.

Version history

Added this version history entry for 0.3.0.