Telemetry¶

def configure_metrics(meter: Any) -> None:  # noqa: ANN401
    """Configure MT5 metrics using the provided meter.

    Args:
        meter: An OpenTelemetry ``Meter`` or duck-typed compatible object.
    """
    _metrics.configure(meter)

def enable_otel_metrics(
    service_name: str = "mt5cli",
    readers: list[Any] | None = None,
) -> None:
    """Enable OTel metrics by wiring up an SDK ``MeterProvider`` pipeline.

    Requires the ``otel`` optional dependency group:
    ``pip install "mt5cli[otel]"``.

    Args:
        service_name: OTel meter/service name used for the ``Resource`` and
            the meter itself.
        readers: Optional list of metric readers. When *None* (the default),
            a :class:`~opentelemetry.sdk.metrics.export.PeriodicExportingMetricReader`
            backed by an OTLP HTTP exporter is created automatically
            (reads the endpoint from ``OTEL_EXPORTER_OTLP_ENDPOINT``).
            Pass a custom list (e.g. ``InMemoryMetricReader`` for tests)
            to override.

    Raises:
        ImportError: If ``opentelemetry-api`` is not installed, or if
            ``readers`` is *None* and
            ``opentelemetry-exporter-otlp-proto-http`` is not installed.
    """
    if not _OTEL_AVAILABLE:
        msg = (
            "opentelemetry-api is not installed. "
            'Install it with: pip install "mt5cli[otel]"'
        )
        raise ImportError(msg)
    if readers is None:
        if _OtelOTLPExporter is None:
            msg = (
                "opentelemetry-exporter-otlp-proto-http is required for the "
                "default OTLP export pipeline. "
                'Install it with: pip install "mt5cli[otel]" or pass a '
                "custom readers list."
            )
            raise ImportError(msg)
        readers = [_OtelPeriodicReader(_OtelOTLPExporter())]  # type: ignore[misc]
    resource = _OtelResource.create({"service.name": service_name})  # type: ignore[union-attr]
    provider = _OtelMeterProvider(resource=resource, metric_readers=readers)  # type: ignore[misc]
    _otel_metrics_mod.set_meter_provider(provider)  # type: ignore[union-attr]
    meter = provider.get_meter(service_name)
    configure_metrics(meter)

def get_metrics() -> _Mt5Metrics:
    """Return the global :class:`_Mt5Metrics` instance.

    Returns:
        The global metric registry (no-op until :func:`configure_metrics` is
        called).
    """
    return _metrics