Errors

This page documents metrics-related errors.

MVX Metrics has two error families:

  • recorder errors;

  • runtime errors.

Recorder errors belong to AsyncioMetricsRecorder.

Runtime errors belong to MetricsRuntime.

Error hierarchy

AsyncioMetricsRecorderError
|
+-- AsyncioMetricsRecorderLoopUnavailableError
+-- AsyncioMetricsRecorderInvalidStateError
+-- AsyncioMetricsRecorderOnStartingHookFailedError
+-- AsyncioMetricsRecorderOnStoppedHookFailedError
+-- AsyncioMetricsRecorderQueueOverflowError
+-- AsyncioMetricsRecorderDispatcherCancelledError
+-- AsyncioMetricsRecorderUnexpectedError


MetricsRuntimeError
|
+-- MetricsRuntimeInvalidStateError
+-- MetricsRuntimeStartupError
+-- MetricsRuntimeShutdownError
+-- MetricsRuntimeLoopUnavailableError
+-- MetricsRuntimeRecorderError
|   |
|   +-- MetricsRuntimeRecorderStartupError
|   +-- MetricsRuntimeRecorderAlreadyExistsError
|   +-- MetricsRuntimeRecorderNotFoundError
|   +-- MetricsRuntimeRecorderStopError
|
+-- MetricsRuntimeUnexpectedError

Both base error classes inherit from ReasonedError.

Unexpected errors also inherit from RuntimeUnexpectedError.

Recorder errors

Recorder errors describe failures in AsyncioMetricsRecorder construction, lifecycle, queue handling, dispatcher execution, and recorder hooks.

class mvx.common.metrics.AsyncioMetricsRecorderError(*, message, details=None, cause=None, reason=None)

Base class for AsyncioMetricsRecorder errors.

All errors raised by the async recorder runtime inherit from this class and carry a reason code from _AsyncioMetricsRecorderErrorReason.

Parameters:

  • message (str)

  • details (Optional[Mapping[str, Any]])

  • cause (Optional[Exception])

  • reason (Optional[str])

class mvx.common.metrics.AsyncioMetricsRecorderLoopUnavailableError

Raised when direct recorder construction cannot find a running event loop.

AsyncioMetricsRecorder is bound to an existing asyncio event loop. Dedicated-loop creation is handled by the metrics runtime layer.

class mvx.common.metrics.AsyncioMetricsRecorderInvalidStateError(recorder_state, expected_states, cause=None)

Raised when a recorder operation is not valid for the current lifecycle state.

Parameters:
class mvx.common.metrics.AsyncioMetricsRecorderOnStartingHookFailedError(cause)

Raised when the _on_starting() lifecycle hook fails.

Parameters:

cause (Exception)

class mvx.common.metrics.AsyncioMetricsRecorderOnStoppedHookFailedError(cause)

Raised when the _on_stopped() lifecycle hook fails.

Parameters:

cause (Exception)

class mvx.common.metrics.AsyncioMetricsRecorderQueueOverflowError

Raised when the accepted-event limit is reached.

This error is raised when queue overflow policy is RAISE_ERROR.

class mvx.common.metrics.AsyncioMetricsRecorderDispatcherCancelledError

Raised when the dispatcher task is cancelled unexpectedly.

Normal shutdown cancels the dispatcher as part of stopping. This error represents cancellation outside the normal stopping path.

class mvx.common.metrics.AsyncioMetricsRecorderUnexpectedError(cause)

Raised when the async metrics recorder catches an unexpected internal failure.

This error wraps failures that are not part of the normal recorder control flow and marks them as unexpected runtime errors.

Parameters:

cause (Exception)

Runtime errors

Runtime errors describe failures in MetricsRuntime lifecycle, runtime loop access, recorder registry operations, and recorder management.

class mvx.common.metrics.MetricsRuntimeError(*, message, details=None, cause=None, reason=None)

Base class for metrics runtime errors.

Parameters:

  • message (str)

  • details (Optional[Mapping[str, Any]])

  • cause (Optional[Exception])

  • reason (Optional[str])

class mvx.common.metrics.MetricsRuntimeInvalidStateError(runtime_state, expected_states, cause=None)

Raised when a metrics runtime operation is not valid for the current lifecycle state.

Parameters:
class mvx.common.metrics.MetricsRuntimeStartupError(cause=None)

Raised when the metrics runtime cannot be started.

This error wraps startup failures that prevent the runtime thread, event loop, or runtime infrastructure from reaching the running state.

Parameters:

cause (Exception | None)

class mvx.common.metrics.MetricsRuntimeShutdownError(details=None, cause=None)

Raised when the metrics runtime cannot be shut down cleanly.

This error wraps failures that occur while stopping recorders, terminating the runtime loop, or closing the runtime infrastructure.

Parameters:

  • details (dict[str, Any] | None)

  • cause (Exception | None)

class mvx.common.metrics.MetricsRuntimeLoopUnavailableError

Raised when the metrics runtime event loop is not available.

This error is used when runtime code needs access to the dedicated metrics event loop, but the loop has not been created or is no longer available.

class mvx.common.metrics.MetricsRuntimeRecorderError(*, message, details=None, cause=None, reason, recorder_id)

Base class for metrics-runtime recorder errors.

These errors describe failures related to recorder lifecycle or recorder registry operations managed by the metrics runtime.

Parameters:

  • message (str)

  • details (dict[str, Any] | None)

  • cause (Exception | None)

  • reason (str)

  • recorder_id (str)

class mvx.common.metrics.MetricsRuntimeRecorderStartupError(recorder_id, cause=None)

Raised when a metrics recorder cannot be started by the runtime.

This error wraps failures raised while creating or starting a recorder inside the metrics runtime infrastructure.

Parameters:

  • recorder_id (str)

  • cause (Exception | None)

class mvx.common.metrics.MetricsRuntimeRecorderAlreadyExistsError(recorder_id)

Raised when a recorder with the requested id is already registered.

Recorder ids are unique within one metrics runtime instance.

Parameters:

recorder_id (str)

class mvx.common.metrics.MetricsRuntimeRecorderNotFoundError(recorder_id)

Raised when a recorder with the requested id is not registered.

Parameters:

recorder_id (str)

class mvx.common.metrics.MetricsRuntimeRecorderStopError(recorder_id, cause=None)

Raised when a metrics recorder cannot be stopped by the runtime.

This error wraps failures raised while stopping a recorder managed by the metrics runtime infrastructure.

Parameters:

  • recorder_id (str)

  • cause (Exception | None)

class mvx.common.metrics.MetricsRuntimeUnexpectedError(message='unexpected metrics runtime error', details=None, cause=None)

Raised when the metrics runtime catches an unexpected internal failure.

This error wraps failures that are not part of the normal metrics runtime control flow and marks them as unexpected runtime errors.

Parameters:

  • message (str)

  • details (dict[str, Any] | None)

  • cause (Exception | None)

Boundary with production errors

Metrics errors are infrastructure errors.

They are separate from production-domain errors.

For example, this is a production error:

raise ValueError("document_id must not be empty")

This is a recorder infrastructure error:

raise AsyncioMetricsRecorderQueueOverflowError()

A production component may choose to suppress recorder errors when metrics are optional:

try:
    self._metrics_recorder.register_event(event=event)
except Exception:
    pass

Runtime management code usually should not hide runtime errors silently.

Runtime errors describe problems with runtime startup, shutdown, event-loop access, recorder registry operations, or recorder lifecycle management.

Summary

Use recorder errors for AsyncioMetricsRecorder construction, lifecycle, queue, hook, and dispatcher failures.

Use runtime errors for MetricsRuntime startup, shutdown, loop, registry, and recorder-management failures.

Production-domain errors remain separate from metrics infrastructure errors.