Runtime

This page documents the MetricsRuntime API.

MetricsRuntime is the synchronous management layer for runtime-owned recorders. It owns the runtime thread, the runtime asyncio event loop, and the recorder registry.

Production components normally do not depend on MetricsRuntime directly. Application code creates the runtime, creates recorders inside it, and passes those recorders to production components.

Public API

enum mvx.common.metrics.MetricsRuntimeState(value)

Lifecycle states of the metrics runtime.

The runtime owns the dedicated metrics thread, event loop, recorder registry, and lifecycle coordination for package-managed metrics recorders.

Member Type:: str

Valid values are as follows:

VIRGIN = <MetricsRuntimeState.VIRGIN: 'VIRGIN'>: Runtime has been created but has not started yet.

STARTING = <MetricsRuntimeState.STARTING: 'STARTING'>: Runtime startup is in progress.

RUNNING = <MetricsRuntimeState.RUNNING: 'RUNNING'>: Runtime is running and can create or manage recorders.

STOPPING = <MetricsRuntimeState.STOPPING: 'STOPPING'>: Runtime shutdown is in progress.

CLOSED = <MetricsRuntimeState.CLOSED: 'CLOSED'>: Runtime has been shut down and cannot be restarted.

FAILURE = <MetricsRuntimeState.FAILURE: 'FAILURE'>: Runtime entered a terminal failure state.

class mvx.common.metrics.MetricsRuntime(*, namespace, default_recorder_queue_max_size=None, default_recorder_queue_overflow_policy=AsyncioMetricsRecorderQueueOverflowPolicy.DROP, log_context=None)

Synchronous management layer for runtime-owned metrics recorders.

The runtime owns a dedicated thread, an asyncio event loop inside that thread, and a registry of AsyncioMetricsRecorder instances created inside that loop.

Public methods are synchronous. Operations that must run on the runtime event loop are scheduled internally, and the public method waits for their result.

A typical application creates one runtime for the application or for a large subsystem, then creates multiple recorders inside that runtime.

Create a metrics runtime in VIRGIN state.

The constructor does not start the runtime thread or create the runtime event loop. Call start() before creating recorders.

Parameters:

namespace (str) – runtime namespace used for the runtime thread name, recorder defaults, and logging identity.
default_recorder_queue_max_size (int | None) – default pending-event limit for recorders created by this runtime.
default_recorder_queue_overflow_policy (AsyncioMetricsRecorderQueueOverflowPolicy) – default overflow policy for recorders created by this runtime.
log_context (LogContext | None) – optional log context used by runtime diagnostics and as the default log context for created recorders.

Raises:

ValueError – if namespace is None, or if default_recorder_queue_max_size is not positive.
TypeError – if an argument has an invalid type.

get_log_context()

Return the log context associated with this runtime.

Used by log_invocation decorators and passed as the default log context to recorders created by this runtime when no recorder-specific context is provided.

Return type:: LogContextProto | None
Returns:: runtime log context, or None when runtime logging is disabled.

property entity_id: str

Return the runtime identity used by logging.

For MetricsRuntime, the logging entity id is the runtime namespace.

Returns:: runtime namespace.

get_status()

Return the current runtime lifecycle state.

Return type:: MetricsRuntimeState
Returns:: current runtime state.

start()

Start the metrics runtime.

The method creates a dedicated runtime thread, creates an asyncio event loop inside that thread, waits until the loop is ready, and moves the runtime to RUNNING state.

Calling start() on an already running runtime is a no-op.

Raises:

MetricsRuntimeInvalidStateError – if the runtime is not in VIRGIN state and is not already running.
MetricsRuntimeStartupError – if the runtime thread or event loop does not become ready in time.
MetricsRuntimeLoopUnavailableError – if startup finishes without an available runtime event loop.

Return type:

None

Returns:

None.

shutdown()

Shut down the metrics runtime.

Shutdown stops and removes runtime-owned recorders, stops the runtime event loop, joins the runtime thread, clears runtime thread/loop references, and moves the runtime to CLOSED state.

Calling shutdown() on a VIRGIN or already closed runtime leaves it in CLOSED state.

Raises:

MetricsRuntimeInvalidStateError – if shutdown is requested from an invalid state.
MetricsRuntimeLoopUnavailableError – if the runtime is running but its loop is missing.
MetricsRuntimeShutdownError – if recorder shutdown, event-loop shutdown, or thread joining fails.

Return type:

None

Returns:

None.

create_recorder(recorder_id, *, entity_id=None, namespace=None, queue_max_size=None, queue_overflow_policy=None, log_context=None)

Create, start, register, and return a recorder owned by this runtime.

The recorder is created inside the runtime event loop. The runtime starts the recorder before adding it to the recorder registry. If no explicit entity_id is provided, the normalized recorder id is used as the recorder entity id.

Recorder-specific options override runtime defaults.

Parameters:

recorder_id (str) – recorder id used as the runtime registry key.
entity_id (str | None) – optional measured entity id for the recorder.
namespace (str | None) – optional recorder namespace. Defaults to the runtime namespace.
queue_max_size (int | None) – optional pending-event limit for this recorder.
queue_overflow_policy (AsyncioMetricsRecorderQueueOverflowPolicy | None) – optional overflow policy for this recorder.
log_context (LogContext | None) – optional log context for this recorder. Defaults to the runtime log context.

Raises:

ValueError – if recorder_id is None or empty, or if queue_max_size is not positive.
TypeError – if an argument has an invalid type.
MetricsRuntimeInvalidStateError – if the runtime is not running.
MetricsRuntimeLoopUnavailableError – if the runtime loop is unavailable.
MetricsRuntimeRecorderAlreadyExistsError – if a recorder with this id already exists or is being created.
MetricsRuntimeRecorderStartupError – if recorder creation or startup fails.

Return type:

AsyncioMetricsRecorder

Returns:

started recorder instance.

get_recorder(recorder_id)

Return a recorder by id.

Parameters:

recorder_id (str) – recorder id to look up.

Raises:

ValueError – if recorder_id is None or empty.
TypeError – if recorder_id is not a string.
MetricsRuntimeInvalidStateError – if the runtime is not running.
MetricsRuntimeLoopUnavailableError – if the runtime loop is unavailable.
MetricsRuntimeRecorderNotFoundError – if no recorder with this id exists.

Return type:

AsyncioMetricsRecorder

Returns:

recorder registered under the given id.

try_get_recorder(recorder_id)

Return a recorder by id, or None if it is not registered.

Parameters:

recorder_id (str) – recorder id to look up.

Raises:

ValueError – if recorder_id is None or empty.
TypeError – if recorder_id is not a string.
MetricsRuntimeInvalidStateError – if the runtime is not running.
MetricsRuntimeLoopUnavailableError – if the runtime loop is unavailable.

Return type:

AsyncioMetricsRecorder | None

Returns:

recorder registered under the given id, or None.

list_recorder_ids()

Return ids of recorders currently registered in this runtime.

Raises:

MetricsRuntimeInvalidStateError – if the runtime is not running.
MetricsRuntimeLoopUnavailableError – if the runtime loop is unavailable.

Return type:

tuple[str, ...]

Returns:

tuple of registered recorder ids.

stop_recorder(recorder_id)

Stop a runtime-owned recorder without removing it from the registry.

If the recorder is already stopped, the method returns successfully.

Parameters:

recorder_id (str) – recorder id to stop.

Raises:

ValueError – if recorder_id is None or empty.
TypeError – if recorder_id is not a string.
MetricsRuntimeInvalidStateError – if the runtime is not running.
MetricsRuntimeLoopUnavailableError – if the runtime loop is unavailable.
MetricsRuntimeRecorderNotFoundError – if no recorder with this id exists or the recorder is being removed.
MetricsRuntimeRecorderStopError – if the recorder cannot be stopped.

Return type:

None

Returns:

None.

stop_and_remove_recorder(recorder_id)

Stop a runtime-owned recorder and remove it from the registry.

If the recorder is running or stopping, the runtime waits for recorder stop. If the recorder is already stopped, it is removed directly. The recorder is removed from the registry even when recorder stop fails.

Parameters:

recorder_id (str) – recorder id to stop and remove.

Raises:

ValueError – if recorder_id is None or empty.
TypeError – if recorder_id is not a string.
MetricsRuntimeInvalidStateError – if the runtime is not running.
MetricsRuntimeLoopUnavailableError – if the runtime loop is unavailable.
MetricsRuntimeRecorderNotFoundError – if no recorder with this id exists or the recorder is already being removed.
MetricsRuntimeRecorderStopError – if the recorder cannot be stopped.

Return type:

AsyncioMetricsRecorder

Returns:

removed recorder instance.

Runtime lifecycle

A runtime is created in VIRGIN state.

runtime = MetricsRuntime(namespace="example.metrics")

The constructor does not start the runtime thread or create the runtime event loop.

Start the runtime before creating recorders:

runtime.start()

Shut it down when metrics processing is no longer needed:

runtime.shutdown()

A typical shape is:

runtime = MetricsRuntime(namespace="example.metrics")
runtime.start()

try:
    recorder = runtime.create_recorder("document_storage")
    ...
finally:
    runtime.shutdown()

Recorder creation

Use create_recorder() to create a recorder inside the runtime-managed event loop:

recorder = runtime.create_recorder("document_storage")

The method creates an AsyncioMetricsRecorder, starts it, stores it in the runtime registry, and returns the ready-to-use recorder.

Recorder options can be provided per recorder:

recorder = runtime.create_recorder(
    "document_storage",
    entity_id="document-storage-main",
    namespace="example.metrics.document_storage",
    queue_max_size=10_000,
    queue_overflow_policy=AsyncioMetricsRecorderQueueOverflowPolicy.DROP,
)

If no explicit entity_id is provided, the recorder id is used as the recorder entity id.

Recorder registry

MetricsRuntime keeps recorders created inside it.

The registry API includes:

recorder = runtime.get_recorder("document_storage")

recorder = runtime.try_get_recorder("document_storage")

recorder_ids = runtime.list_recorder_ids()

get_recorder() raises if the recorder does not exist.

try_get_recorder() returns None when the recorder is not registered.

Recorder stopping and removal

A recorder can be stopped without being removed:

runtime.stop_recorder("document_storage")

A recorder can also be stopped and removed from the registry:

recorder = runtime.stop_and_remove_recorder("document_storage")

Use stop_recorder() when the recorder should remain registered.

Use stop_and_remove_recorder() when the measured scope is gone and the recorder should no longer be managed by the runtime.

Runtime state

MetricsRuntimeState describes the runtime lifecycle.

The usual path is:

VIRGIN
   |
   v
STARTING
   |
   v
RUNNING
   |
   v
STOPPING
   |
   v
CLOSED

If startup or shutdown fails, the runtime can move to FAILURE.

The current state can be read with:

state = runtime.get_status()

Logging

MetricsRuntime can use MVX Logger when a log_context is provided.

Runtime public operations are instrumented with log_invocation, including:

metrics_runtime.start
metrics_runtime.shutdown
metrics_runtime.create_recorder
metrics_runtime.get_recorder
metrics_runtime.try_get_recorder
metrics_runtime.list_recorder_ids
metrics_runtime.stop_recorder
metrics_runtime.stop_and_remove_recorder

Ready-to-use runtime logging policies are documented in the logging policies API page.