nebius.aio.metrics

module documentation
(source)

Callback-based SDK metrics helpers.

Metrics are optional. The metrics and auth_metrics parameters accept an object with callback methods or a mapping of callback functions. Use Python snake_case names. camelCase aliases support compatibility with the TypeScript SDK.

Full SDK/config metrics may implement:

  • config_load(metric: ConfigMetric)
  • credentials_resolve(metric: ConfigMetric)

Auth metrics may implement:

  • token_acquire(metric: TokenAcquireMetric)
  • token_lifetime(metric: TokenLifetimeMetric)
  • token_refresh(metric: TokenRefreshMetric)
  • cache_hit(metric: CacheMetric)
  • cache_miss(metric: CacheMetric)
  • cache_store(metric: CacheMetric)
  • cache_refresh(metric: CacheMetric)
  • cache_invalidate(metric: CacheMetric)

Callbacks can be synchronous or asynchronous. A short timeout limits awaitable callback results. A running event loop schedules these callbacks. Synchronous code waits for them. The SDK ignores callback exceptions, so metrics do not change request or authentication behavior.

Class AuthMetricsRecorder Small mutable auth metrics recorder with a fixed provider label.
Class CacheMetric Authentication cache metric payload.
Class ConfigMetric Config-reader metric payload.
Class Metrics Optional metric callbacks with bounded awaitable callback execution.
Class TokenAcquireMetric Token acquisition metric payload.
Class TokenLifetimeMetric Token lifetime metric payload.
Class TokenRefreshMetric Token refresh metric payload.
Function auth_metric_provider Return an auth provider label from a bearer hook.
Function auth_metrics_recorder Create an auth metrics recorder, preserving shared callback cells.
Function bind_auth_metrics Attach auth metrics to bearer or return an instrumented wrapper.
Function emit_metric Call a metric callback if present and swallow callback failures.
Function metric_duration_seconds Return elapsed seconds since start.
Function metric_start Return a monotonic start timestamp for metric duration measurement.
Function record_config_metric Emit a config-reader metric.
Function sanitize_metric_callback_timeout_seconds Return a finite metric callback timeout bounded to SDK limits.
Constant DEFAULT_METRIC_CALLBACK_TIMEOUT_SECONDS Default wall-clock cap for awaitable metric callback results.
Constant MAX_METRIC_CALLBACK_TIMEOUT_SECONDS Highest accepted wall-clock cap for awaitable metric callback results.
Constant METRIC_RESULT_ERROR Undocumented
Constant METRIC_RESULT_SUCCESS Undocumented
Constant MIN_METRIC_CALLBACK_TIMEOUT_SECONDS Lowest accepted wall-clock cap for awaitable metric callback results.
Type Alias MetricCallback Synchronous or asynchronous metric callback.
Type Alias MetricResult Undocumented
Variable AuthMetricsLike Object or mapping with optional auth metric callbacks.
Variable MetricsLike Object or mapping with optional config and auth metric callbacks.
Class _AuthMetricsCell Undocumented
Class _InstrumentedBearer No class docstring; 3/3 properties, 0/2 instance variable, 3/4 methods documented
Class _InstrumentedReceiver No class docstring; 1/1 property, 0/3 instance variable, 2/4 methods documented
Function _apply_metrics_setter Undocumented
Function _discard_metric_task Remove a completed fallback metric task from global tracking.
Function _metric_attribute_value Undocumented
Function _metric_callback Undocumented
Function _metric_callback_timeout Undocumented
Function _metric_mapping_value Undocumented
Function _reset_metric_tasks_after_fork Drop inherited fallback tasks and replace a possibly locked lock.
Function _run_metric_awaitable Undocumented
Function _schedule_metric_awaitable Undocumented
Async Function _swallow_metric_awaitable Undocumented
Constant _CALLBACK_TIMEOUT_NAMES Undocumented
Variable _metric_tasks Undocumented
Variable _metric_tasks_lock Undocumented
def auth_metric_provider(bearer: object | None) -> str: (source)

Return an auth provider label from a bearer hook.

def auth_metrics_recorder(metrics: AuthMetricsLike, provider: str) -> AuthMetricsRecorder: (source)

Create an auth metrics recorder, preserving shared callback cells.

def bind_auth_metrics(bearer: object, metrics: AuthMetricsLike) -> object: (source)

Attach auth metrics to bearer or return an instrumented wrapper.

def emit_metric(metrics: object | None, names: tuple[str, str], metric: object): (source)

Call a metric callback if present and swallow callback failures.

def metric_duration_seconds(start: float) -> float: (source)

Return elapsed seconds since start.

def metric_start() -> float: (source)

Return a monotonic start timestamp for metric duration measurement.

def record_config_metric(metrics: MetricsLike, kind: Literal['config_load', 'credentials_resolve'], source: str, result: MetricResult, duration_seconds: float): (source)

Emit a config-reader metric.

def sanitize_metric_callback_timeout_seconds(value: object) -> float: (source)

Return a finite metric callback timeout bounded to SDK limits.

DEFAULT_METRIC_CALLBACK_TIMEOUT_SECONDS: float = (source)

Default wall-clock cap for awaitable metric callback results.

Value
1.0
MAX_METRIC_CALLBACK_TIMEOUT_SECONDS: float = (source)

Highest accepted wall-clock cap for awaitable metric callback results.

Value
5.0
METRIC_RESULT_ERROR: MetricResult = (source)

Undocumented

Value
'error'
METRIC_RESULT_SUCCESS: MetricResult = (source)

Undocumented

Value
'success'
MIN_METRIC_CALLBACK_TIMEOUT_SECONDS: float = (source)

Lowest accepted wall-clock cap for awaitable metric callback results.

Value
0.001
MetricCallback = (source)

Synchronous or asynchronous metric callback.

Value
Callable[[object], object]
MetricResult = (source)

Undocumented

Value
Literal['success', 'error']
AuthMetricsLike = (source)

Object or mapping with optional auth metric callbacks.

MetricsLike = (source)

Object or mapping with optional config and auth metric callbacks.

def _apply_metrics_setter(bearer: object, metrics: AuthMetricsLike, seen: set[int] | None = None) -> bool: (source)

Undocumented

def _discard_metric_task(task: Task[None]): (source)

Remove a completed fallback metric task from global tracking.

This fallback set is used only when no SDK task scheduler is active.

Parameters
task:Task[None]Completed metric callback task.
def _metric_attribute_value(metrics: object, name: str) -> object | None: (source)

Undocumented

def _metric_callback(metrics: object | None, names: tuple[str, str]) -> Callable[[object], object] | None: (source)

Undocumented

def _metric_callback_timeout(metrics: object | None) -> float: (source)

Undocumented

def _metric_mapping_value(metrics: Mapping[object, object], name: str) -> object | None: (source)

Undocumented

def _reset_metric_tasks_after_fork(): (source)

Drop inherited fallback tasks and replace a possibly locked lock.

def _run_metric_awaitable(awaitable: Awaitable[object], timeout: float): (source)

Undocumented

def _schedule_metric_awaitable(awaitable: Awaitable[object], timeout: object = DEFAULT_METRIC_CALLBACK_TIMEOUT_SECONDS): (source)

Undocumented

async def _swallow_metric_awaitable(awaitable: Awaitable[object], timeout: float): (source)

Undocumented

_CALLBACK_TIMEOUT_NAMES: tuple[str, ...] = (source)

Undocumented

Value
('callback_timeout_seconds',
 'callbackTimeoutSeconds',
 'callback_timeout',
 'callbackTimeout')
_metric_tasks: set[Task[None]] = (source)

Undocumented

_metric_tasks_lock = (source)

Undocumented