fast-telemetry 0.0.0__py3-none-any.whl

fast_telemetry/__init__.py

@@ -0,0 +1,10 @@
+try:
+    from ._version import version as __version__
+except ImportError:
+    __version__ = "unknown"
+
+from .core import (
+    MetricsExporter,
+    MetricsCollector,
+    PrometheusMetrics,
+)

fast_telemetry/core.py

@@ -0,0 +1,232 @@
+import os
+import functools
+import inspect
+from abc import abstractmethod, ABC
+from typing import (
+    Callable,
+    Any,
+    ContextManager,
+    TypeVar,
+    ParamSpec,
+    overload,
+    Type,
+)
+from prometheus_client import CollectorRegistry, Counter, Histogram, Gauge, generate_latest
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class MetricsExporter(ABC):
+    """Интерфейс для экспорта метрик (например, в /metrics endpoint)."""
+
+    @abstractmethod
+    def get_registry(self) -> CollectorRegistry:
+        pass
+
+    @abstractmethod
+    def generate_latest_metrics(self) -> bytes:
+        pass
+
+
+class MetricsCollector(ABC):
+    """Интерфейс для сбора метрик в коде приложения."""
+
+    @property
+    @abstractmethod
+    def service_name(self) -> str:
+        pass
+
+    @abstractmethod
+    def inc_error(self, error_type: str | BaseException = "generic") -> None:
+        """Инкремент счетчика ошибок."""
+        pass
+
+    @abstractmethod
+    def timer(self, task_type: str, long_task: bool = False) -> ContextManager[Any]:
+        """
+        Возвращает контекстный менеджер для замера времени.
+        :param task_type: Метка типа задачи (label).
+        :param long_task: Если True, пишет в гистограмму для долгих задач.
+        """
+        pass
+
+    @overload
+    def measure_task(self, func: Callable[P, R]) -> Callable[P, R]: ...
+
+    @overload
+    def measure_task(
+        self, name: str | None = None, *, long_task: bool = False
+    ) -> Callable[[Callable[P, R]], Callable[P, R]]: ...
+
+    def measure_task(
+        self, arg: str | Callable[P, R] | None = None, long_task: bool = False
+    ) -> Callable[P, R] | Callable[[Callable[P, R]], Callable[P, R]]:
+        """
+        Универсальный декоратор для замера времени выполнения функций.
+        Поддерживает sync и async функции.
+        """
+        # Случай 1: @metrics.measure
+        if callable(arg):
+            func = arg
+            return self._create_timer_wrapper(func, func.__name__, long_task=False)
+
+        # Случай 2: @metrics.measure("name") или @metrics.measure(long_task=True)
+        task_name = arg
+
+        def decorator(f: Callable[P, R]) -> Callable[P, R]:
+            name = task_name or f.__name__
+            return self._create_timer_wrapper(f, name, long_task=long_task)
+
+        return decorator
+
+    def _create_timer_wrapper(self, func: Callable[P, R], task_name: str, long_task: bool) -> Callable[P, R]:
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                with self.timer(task_name, long_task=long_task):
+                    return await func(*args, **kwargs)  # type: ignore
+
+            return async_wrapper  # type: ignore
+        else:
+
+            @functools.wraps(func)
+            def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                with self.timer(task_name, long_task=long_task):
+                    return func(*args, **kwargs)
+
+            return sync_wrapper
+
+    @abstractmethod
+    def track_exception(
+        self, *, exclude: list[Type[BaseException]] | None = None
+    ) -> Callable[[Callable[P, R]], Callable[P, R]]:
+        pass
+
+
+class PrometheusMetrics(MetricsCollector, MetricsExporter):
+    """
+    Реализация метрик на базе prometheus-client.
+    Разделяет задачи на Fast (API, легкая логика) и Long (Background tasks, crons).
+    """
+
+    BUCKETS_FAST: tuple[float, ...] = (0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0)
+    BUCKETS_LONG: tuple[float, ...] = (1.0, 5.0, 10.0, 30.0, 60.0, 300.0, 600.0, 1800.0, 3600.0, 7200.0, 14400.0)
+
+    def __init__(
+        self,
+        service_name: str,
+        version: str | None = None,
+        env: str | None = None,
+        prefix: str = "fasttelemetry",
+    ) -> None:
+        self._service_name = service_name
+        self._env = env or os.getenv("APP_ENV", "dev")
+        self._version = version or os.getenv("APP_VERSION", "unknown")
+        self._prefix = f"{prefix.rstrip('_')}_"
+
+        self._registry = CollectorRegistry(auto_describe=True)
+
+        self._app_info: Gauge = self._create_app_info()
+        self._business_errors: Counter = self._create_business_errors()
+        self._task_duration_fast: Histogram = self._create_fast_histogram()
+        self._task_duration_long: Histogram = self._create_long_histogram()
+
+        self._set_initial_values()
+
+    def _create_app_info(self) -> Gauge:
+        return Gauge(
+            name=f"{self._prefix}app_info",
+            documentation="Application information",
+            labelnames=["service", "env", "version"],
+            registry=self._registry,
+        )
+
+    def _create_business_errors(self) -> Counter:
+        return Counter(
+            name=f"{self._prefix}business_errors_total",
+            documentation="Total count of business logic errors",
+            labelnames=["error_type"],
+            registry=self._registry,
+        )
+
+    def _create_fast_histogram(self) -> Histogram:
+        return Histogram(
+            name=f"{self._prefix}task_processing_seconds",
+            documentation="Time spent processing internal tasks (fast)",
+            labelnames=["task_type"],
+            registry=self._registry,
+            buckets=self.BUCKETS_FAST,
+        )
+
+    def _create_long_histogram(self) -> Histogram:
+        return Histogram(
+            name=f"{self._prefix}long_task_processing_seconds",
+            documentation="Time spent processing long-running tasks",
+            labelnames=["task_type"],
+            registry=self._registry,
+            buckets=self.BUCKETS_LONG,
+        )
+
+    def _set_initial_values(self) -> None:
+        """Устанавливает статические значения при старте."""
+        self._app_info.labels(service=self._service_name, env=self._env, version=self._version).set(1)
+
+    @property
+    def service_name(self) -> str:
+        return self._service_name
+
+    def inc_error(self, error_type: str | BaseException = "generic") -> None:
+        if isinstance(error_type, BaseException):
+            error_type = type(error_type).__name__
+        self._business_errors.labels(error_type=error_type).inc()
+
+    def track_exception(
+        self, arg: Callable[P, R] | None = None, *, exclude: list[Type[BaseException]] | None = None
+    ) -> Any:
+        """
+        Декоратор для подсчета исключений.
+        Использует имя класса исключения как метку error_type.
+        """
+
+        def decorator(func: Callable[P, R]) -> Callable[P, R]:
+            if inspect.iscoroutinefunction(func):
+
+                @functools.wraps(func)
+                async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                    try:
+                        return await func(*args, **kwargs)  # type: ignore
+                    except Exception as e:
+                        if not exclude or not isinstance(e, tuple(exclude)):
+                            self.inc_error(e)
+                        raise
+
+                return async_wrapper  # type: ignore
+            else:
+
+                @functools.wraps(func)
+                def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                    try:
+                        return func(*args, **kwargs)
+                    except Exception as e:
+                        if not exclude or not isinstance(e, tuple(exclude)):
+                            self.inc_error(e)
+                        raise
+
+                return sync_wrapper
+
+        if callable(arg):
+            return decorator(arg)
+        return decorator
+
+    def timer(self, task_type: str, long_task: bool = False) -> ContextManager[Any]:
+        if long_task:
+            return self._task_duration_long.labels(task_type=task_type).time()
+        return self._task_duration_fast.labels(task_type=task_type).time()
+
+    def get_registry(self) -> CollectorRegistry:
+        return self._registry
+
+    def generate_latest_metrics(self) -> bytes:
+        return generate_latest(self._registry)

fast_telemetry/integrations/fastapi.py

@@ -0,0 +1,30 @@
+from typing import Iterable
+
+from fastapi import FastAPI
+from prometheus_fastapi_instrumentator import Instrumentator
+from ..core import PrometheusMetrics
+
+
+def setup_fastapi_metrics(
+    app: FastAPI, metrics: PrometheusMetrics, excluded_routes: Iterable[str] | None = None
+) -> None:
+    """
+    Настраивает автоматический мониторинг HTTP запросов
+    и добавляет эндпоинт /metrics.
+    """
+    if excluded_routes is None:
+        excluded_routes = set()
+    else:
+        excluded_routes = set(excluded_routes)
+    excluded_routes.update({"/metrics", app.docs_url, app.redoc_url, app.openapi_url})
+    instrumentator = Instrumentator(
+        should_group_status_codes=False,
+        should_ignore_untemplated=True,
+        excluded_handlers=list(excluded_routes),
+        inprogress_name="http_requests_inprogress",
+        inprogress_labels=True,
+        registry=metrics.get_registry(),
+    )
+
+    instrumentator.instrument(app)
+    instrumentator.expose(app, include_in_schema=False)

fast_telemetry/integrations/faststream.py

@@ -0,0 +1,102 @@
+from typing import Type, Protocol
+
+from faststream._internal.broker import BrokerUsecase
+from faststream.asgi import AsgiFastStream
+from faststream.prometheus import PrometheusMiddleware
+from prometheus_client import make_asgi_app
+
+from ..core import PrometheusMetrics
+
+
+class MiddlewareFactory(Protocol):
+    def __call__(self, metrics: PrometheusMetrics) -> PrometheusMiddleware: ...
+
+
+_BROKER_MIDDLEWARE_MAP: dict[Type[BrokerUsecase], MiddlewareFactory] = {}
+
+# --- RabbitMQ ---
+try:
+    from faststream.rabbit import RabbitBroker
+    from faststream.rabbit.prometheus import RabbitPrometheusMiddleware
+
+    class CustomRabbitMiddleware(RabbitPrometheusMiddleware):
+        def __init__(self, metrics: PrometheusMetrics):
+            super().__init__(registry=metrics.get_registry(), custom_labels={"service": metrics.service_name})
+
+    _BROKER_MIDDLEWARE_MAP[RabbitBroker] = CustomRabbitMiddleware
+except ImportError:
+    pass
+
+# --- Kafka ---
+try:
+    from faststream.kafka import KafkaBroker
+    from faststream.kafka.prometheus import KafkaPrometheusMiddleware
+
+    class CustomKafkaMiddleware(KafkaPrometheusMiddleware):
+        def __init__(self, metrics: PrometheusMetrics):
+            super().__init__(registry=metrics.get_registry(), custom_labels={"service": metrics.service_name})
+
+    _BROKER_MIDDLEWARE_MAP[KafkaBroker] = CustomKafkaMiddleware
+except ImportError:
+    pass
+
+# --- Redis ---
+try:
+    from faststream.redis import RedisBroker
+    from faststream.redis.prometheus import RedisPrometheusMiddleware
+
+    class CustomRedisMiddleware(RedisPrometheusMiddleware):
+        def __init__(self, metrics: PrometheusMetrics):
+            super().__init__(registry=metrics.get_registry(), custom_labels={"service": metrics.service_name})
+
+    _BROKER_MIDDLEWARE_MAP[RedisBroker] = CustomRedisMiddleware
+except ImportError:
+    pass
+
+try:
+    from faststream.confluent import KafkaBroker as ConfluentBroker
+    from faststream.confluent.prometheus import KafkaPrometheusMiddleware as ConfluentPrometheusMiddleware
+
+    class CustomConfluentPrometheusMiddleware(ConfluentPrometheusMiddleware):
+        def __init__(self, metrics: PrometheusMetrics):
+            super().__init__(registry=metrics.get_registry(), custom_labels={"service": metrics.service_name})
+
+    _BROKER_MIDDLEWARE_MAP[ConfluentBroker] = CustomConfluentPrometheusMiddleware
+except ImportError:
+    pass
+
+# --- Nats ---
+try:
+    from faststream.nats import NatsBroker
+    from faststream.nats.prometheus import NatsPrometheusMiddleware
+
+    class CustomNatsPrometheusMiddleware(NatsPrometheusMiddleware):
+        def __init__(self, metrics: PrometheusMetrics):
+            super().__init__(registry=metrics.get_registry(), custom_labels={"service": metrics.service_name})
+
+    _BROKER_MIDDLEWARE_MAP[NatsBroker] = CustomNatsPrometheusMiddleware
+
+except ImportError:
+    pass
+
+
+def setup_faststream_metrics(app: AsgiFastStream, metrics: PrometheusMetrics) -> None:
+    broker = app.broker
+    broker_type = type(broker)
+
+    middleware_cls = _BROKER_MIDDLEWARE_MAP.get(broker_type)
+
+    if not middleware_cls:
+        for b_cls, m_cls in _BROKER_MIDDLEWARE_MAP.items():
+            if isinstance(broker, b_cls):
+                middleware_cls = m_cls
+                break
+
+    if not middleware_cls:
+        available = [k.__name__ for k in _BROKER_MIDDLEWARE_MAP.keys()]
+        raise ValueError(
+            f"Unsupported broker type: {broker_type.__name__}. " f"Installed drivers support: {', '.join(available)}"
+        )
+    app.routes.append(("/metrics", make_asgi_app(metrics.get_registry())))
+
+    app.broker.add_middleware(middleware_cls(metrics=metrics))

fast_telemetry/integrations/worker.py

@@ -0,0 +1,124 @@
+import asyncio
+import functools
+import inspect
+import logging
+import os
+import socket
+from abc import abstractmethod
+from types import TracebackType
+from typing import Type, Callable
+
+from prometheus_client import start_http_server, push_to_gateway
+
+from ..core import PrometheusMetrics, MetricsCollector, P, R
+
+logger = logging.getLogger(__name__)
+
+
+class IJobMetricsCollector(MetricsCollector):
+    @abstractmethod
+    def track_job(
+        self, gateway_url: str, timeout: float = 5.0, grouping_key: dict[str, str] | None = None
+    ) -> "_UnifiedJobPusher":
+        """
+        Создает трекер для job-а.
+        Может использоваться как контекстный менеджер или декоратор.
+        """
+        pass
+
+    @abstractmethod
+    def start_server(self, port: int = 8000, addr: str = "0.0.0.0") -> None:
+        pass
+
+
+class _UnifiedJobPusher:
+    """
+    Гибридный объект: Context Manager + Decorator.
+    Отправляет метрики в Pushgateway при завершении работы блока или функции.
+    """
+
+    def __init__(self, metrics: "WorkerMetrics", gateway_url: str, timeout: float, grouping_key: dict[str, str] | None):
+        self.metrics = metrics
+        self.gateway_url = gateway_url
+        self.timeout = timeout
+        # Группируем по инстансу, чтобы воркеры не перезатирали метрики друг друга
+        self.grouping_key = grouping_key or {"instance": self.metrics.instance_id}
+
+    def _push(self) -> None:
+        """Безопасная отправка метрик (не должна ронять скрипт)."""
+        try:
+            push_to_gateway(
+                self.gateway_url,
+                job=self.metrics.service_name,
+                registry=self.metrics.get_registry(),
+                grouping_key=self.grouping_key,
+                timeout=self.timeout,
+            )
+        except Exception:
+            logger.exception(f"Failed to push metrics to {self.gateway_url}")
+
+    def __enter__(self) -> "_UnifiedJobPusher":
+        return self
+
+    def __exit__(
+        self, exc_type: Type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None
+    ) -> None:
+        self._push()
+
+    async def __aenter__(self) -> "_UnifiedJobPusher":
+        return self
+
+    async def __aexit__(
+        self, exc_type: Type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None
+    ) -> None:
+        await asyncio.to_thread(self._push)
+
+    def __call__(self, func: Callable[[P], R]) -> Callable[[P], R]:
+        """Позволяет использовать объект как декоратор @metrics.track_job(...)"""
+        if inspect.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                async with self:
+                    return await func(*args, **kwargs)  # type: ignore
+
+            return async_wrapper  # type: ignore
+        else:
+
+            @functools.wraps(func)
+            def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                with self:
+                    return func(*args, **kwargs)
+
+            return sync_wrapper
+
+
+class WorkerMetrics(PrometheusMetrics, IJobMetricsCollector):
+    def __init__(self, service_name: str, version: str | None = None, env: str | None = None) -> None:
+        super().__init__(service_name=service_name, version=version, env=env)
+        self._is_server_started = False
+        # Уникальный ID для каждого запуска скрипта/пода
+        self._instance_id = f"{socket.gethostname()}-{os.getpid()}"
+
+    @property
+    def instance_id(self) -> str:
+        return self._instance_id
+
+    def start_server(self, port: int = 8000, addr: str = "0.0.0.0") -> None:
+        """
+        Запускает HTTP сервер (Daemon thread) для pull-модели (если нужно).
+        """
+        if self._is_server_started:
+            logger.warning("Metrics server is already running")
+            return
+
+        start_http_server(port, addr=addr, registry=self._registry)
+        self._is_server_started = True
+
+    def track_job(
+        self, gateway_url: str, timeout: float = 5.0, grouping_key: dict[str, str] | None = None
+    ) -> _UnifiedJobPusher:
+        """
+        Возвращает объект, который работает и как ContextManager, и как Decorator.
+        """
+        return _UnifiedJobPusher(metrics=self, gateway_url=gateway_url, timeout=timeout, grouping_key=grouping_key)

fast_telemetry-0.0.0.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: fast-telemetry
+Version: 0.0.0
+Summary: Internal standardized metrics library
+Requires-Python: >=3.11
+Requires-Dist: prometheus-client~=0.21.0
+Provides-Extra: web
+Requires-Dist: fastapi~=0.115.0; extra == "web"
+Requires-Dist: prometheus-fastapi-instrumentator~=7.1.0; extra == "web"
+Provides-Extra: stream
+Requires-Dist: faststream~=0.6.0; extra == "stream"

fast_telemetry-0.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fast_telemetry/__init__.py,sha256=maomIZLdB92E2j9kW1caPUa-_B799ZTGEi24NY-ERZI,191
+fast_telemetry/core.py,sha256=T39rEQuM2W95S9_9ww05a6RSIRFgvo7XFagqKBXGqCk,8431
+fast_telemetry/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fast_telemetry/integrations/fastapi.py,sha256=-IMpWpViu27iBXWvBTyXs5Uxeq2JFB0Jt5Hz5Y5KEck,1052
+fast_telemetry/integrations/faststream.py,sha256=12WvzC4l8o2Vec8GSI2-58cx6aP63o7-cohxZNgyZqA,3650
+fast_telemetry/integrations/worker.py,sha256=BQCLdjxTB3PluD7Bxv-rPzOjWTkBde6ssg4KOxQENeQ,4713
+fast_telemetry-0.0.0.dist-info/METADATA,sha256=eASeq92li4u940ns7EExrhXRTLMxYXehFwpWUpdW92w,385
+fast_telemetry-0.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+fast_telemetry-0.0.0.dist-info/top_level.txt,sha256=OvY6pUtFsIZyuDZiiIF6RFF-mfjMuvXDpUbz4XXXop0,24
+fast_telemetry-0.0.0.dist-info/RECORD,,

fast_telemetry-0.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fast_telemetry-0.0.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+__init__
+fast_telemetry