fast-telemetry 0.0.0__py3-none-any.whl → 0.0.2__py3-none-any.whl

fast_telemetry/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.0.2'
+__version_tuple__ = version_tuple = (0, 0, 2)
+
+__commit_id__ = commit_id = None

fast_telemetry/integrations/fastapi.py

@@ -2,11 +2,13 @@ from typing import Iterable
 
 from fastapi import FastAPI
 from prometheus_fastapi_instrumentator import Instrumentator
+
+from .. import MetricsExporter
 from ..core import PrometheusMetrics
 
 
 def setup_fastapi_metrics(
-    app: FastAPI, metrics: PrometheusMetrics, excluded_routes: Iterable[str] | None = None
+    app: FastAPI, metrics: MetricsExporter, excluded_routes: Iterable[str] | None = None
 ) -> None:
     """
     Настраивает автоматический мониторинг HTTP запросов

fast_telemetry/integrations/faststream.py

@@ -5,11 +5,11 @@ from faststream.asgi import AsgiFastStream
 from faststream.prometheus import PrometheusMiddleware
 from prometheus_client import make_asgi_app
 
-from ..core import PrometheusMetrics
+from ..core import MetricsExporter
 
 
 class MiddlewareFactory(Protocol):
-    def __call__(self, metrics: PrometheusMetrics) -> PrometheusMiddleware: ...
+    def __call__(self, metrics: MetricsExporter) -> PrometheusMiddleware: ...
 
 
 _BROKER_MIDDLEWARE_MAP: dict[Type[BrokerUsecase], MiddlewareFactory] = {}
@@ -20,8 +20,8 @@ try:
     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})
+        def __init__(self, metrics: MetricsExporter):
+            super().__init__(registry=metrics.get_registry())
 
     _BROKER_MIDDLEWARE_MAP[RabbitBroker] = CustomRabbitMiddleware
 except ImportError:
@@ -33,8 +33,8 @@ try:
     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})
+        def __init__(self, metrics: MetricsExporter):
+            super().__init__(registry=metrics.get_registry())
 
     _BROKER_MIDDLEWARE_MAP[KafkaBroker] = CustomKafkaMiddleware
 except ImportError:
@@ -46,8 +46,8 @@ try:
     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})
+        def __init__(self, metrics: MetricsExporter):
+            super().__init__(registry=metrics.get_registry())
 
     _BROKER_MIDDLEWARE_MAP[RedisBroker] = CustomRedisMiddleware
 except ImportError:
@@ -58,8 +58,8 @@ try:
     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})
+        def __init__(self, metrics: MetricsExporter):
+            super().__init__(registry=metrics.get_registry())
 
     _BROKER_MIDDLEWARE_MAP[ConfluentBroker] = CustomConfluentPrometheusMiddleware
 except ImportError:
@@ -71,8 +71,8 @@ try:
     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})
+        def __init__(self, metrics: MetricsExporter):
+            super().__init__(registry=metrics.get_registry())
 
     _BROKER_MIDDLEWARE_MAP[NatsBroker] = CustomNatsPrometheusMiddleware
 
@@ -80,7 +80,7 @@ except ImportError:
     pass
 
 
-def setup_faststream_metrics(app: AsgiFastStream, metrics: PrometheusMetrics) -> None:
+def setup_faststream_metrics(app: AsgiFastStream, metrics: MetricsExporter) -> None:
     broker = app.broker
     broker_type = type(broker)
 

fast_telemetry-0.0.2.dist-info/METADATA

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: fast-telemetry
+Version: 0.0.2
+Summary: Internal standardized metrics library
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+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
+
+**Production-ready Prometheus integration for FastAPI, FastStream, and Python Workers.**
+
+`fast-telemetry` — это "клей", который объединяет метрики вашего микросервиса в единый стандарт. Библиотека навязывает
+правильные практики (единые метки `env`, `version`, `service`) и предоставляет удобные абстракции для HTTP-сервисов,
+обработчиков очередей и периодических задач.
+
+### 🌟 Особенности
+
+* **Единый стандарт:** Автоматически добавляет метки `service`, `env`, `version` ко всем метрикам.
+* **FastAPI:** Автоконфигурация через `Instrumentator`, исключение служебных ручек (`/metrics` и других переданных).
+* **FastStream:** Поддержка RabbitMQ, Kafka, Redis, NATS "из коробки" (автоопределение драйвера).
+* **Workers & Cron:**
+    * Поддержка Long-running процессов (daemon thread server).
+    * Поддержка Batch-jobs (Pushgateway) через **универсальный контекстный менеджер** (sync/async).
+* **Декораторы:** Удобные `@measure_task` и `@track_exception`, которые сами понимают, синхронная функция или
+  асинхронная.
+* **Безопасность типов:** Полная типизация (mypy strict).
+
+---
+
+### 📦 Установка
+
+```bash
+pip install fast-telemetry
+```
+
+---
+
+### 🚀 Quick Start
+
+#### 1. Core Concepts
+
+В основе всего лежит класс `PrometheusMetrics` (или его наследники). Вы инициализируете его один раз при старте
+приложения.
+
+```python
+from fast_telemetry import PrometheusMetrics
+
+metrics = PrometheusMetrics(
+    service_name="payment_service",
+    version="1.0.4",
+    env="production"
+)
+
+# Использование в коде
+metrics.inc_error("validation_error")
+
+with metrics.timer("db_query", long_task=False):
+    # ... logic ...
+    pass
+```
+
+#### 2. FastAPI Integration
+
+Автоматически добавляет эндпоинт `/metrics` и собирает RED-метрики (Requests, Errors, Duration).
+
+```python
+from fastapi import FastAPI
+from fast_telemetry import PrometheusMetrics, setup_fastapi_metrics
+
+app = FastAPI()
+metrics = PrometheusMetrics(service_name="api_core", env="dev", version="1.2.3")
+
+# Настройка (исключает /docs, /openapi.json + readiness)
+setup_fastapi_metrics(app, metrics, excluded_routes=["/readiness"])
+
+
+@app.get("/")
+@metrics.measure_task("root_handler", long_task=False)
+async def root():
+    return {"status": "ok"}
+```
+
+#### 3. FastStream Integration
+
+Поддерживает автоматическое определение брокера (Rabbit/Kafka/Redis/NATS) и инъекцию middleware.
+
+```python
+from faststream.asgi import AsgiFastStream, make_ping_asgi
+from faststream.rabbit import RabbitBroker
+from fast_telemetry import PrometheusMetrics, setup_faststream_metrics
+
+broker = RabbitBroker("amqp://guest:guest@localhost:5672/")
+app = AsgiFastStream(
+    broker,
+    asgi_routes=[
+        ("/health", make_ping_asgi(broker))
+    ],
+    lifespan=None,
+    asyncapi_path="/docs",
+)
+
+metrics = PrometheusMetrics(service_name="worker_core", env="dev")
+setup_faststream_metrics(app, metrics)
+```
+
+#### 4. Workers & Cron Jobs
+
+Для скриптов без веб-сервера. Поддерживает два режима:
+
+1. **Daemon Server** (для бесконечных циклов).
+2. **Push Gateway** (для скриптов, запускаемых по расписанию).
+
+```python
+import asyncio
+from fast_telemetry import WorkerMetrics
+
+metrics = WorkerMetrics(service_name="nightly_job", env="prod")
+
+
+# --- Вариант А: Long-running worker ---
+def run_worker():
+    # Запускает HTTP сервер в фоновом потоке
+    metrics.start_server(port=8000)
+    while True:
+        process_data()
+
+
+# --- Вариант Б: Batch Job (Cron) ---
+# Универсальный трекер (работает и с with, и с async with)
+async def run_batch_job():
+    # Автоматически отправит метрики в Pushgateway при выходе из блока
+    # Группирует по instance_id, чтобы воркеры не перезатирали друг друга
+    async with metrics.track_job(gateway_url="http://pushgateway:9091", timeout=5.0):
+        await do_heavy_calculation()
+        metrics.inc_error("calc_error")
+
+
+if __name__ == "__main__":
+    asyncio.run(run_batch_job())
+```
+
+---
+
+### 🛠 Декораторы
+
+Библиотека предоставляет "умные" декораторы, которые работают с sync и async функциями прозрачно.
+
+**`@track_exception()`**
+Считает количество исключений. Использует имя класса исключения как метку.
+
+```python
+@metrics.track_exception
+async def dangerous_operation():
+    raise ValueError("Oops")
+    # Увеличит счетчик fasttelemetry_business_errors_total{error_type="ValueError", ...}
+```
+
+**`@measure_task("task_name")`**
+Замеряет время выполнения функции (Histogram).
+
+```python
+@metrics.measure_task("image_processing")
+def process_image(img):
+    time.sleep(1)
+```
+
+---
+
+### 📊 Grafana & Prometheus
+
+Библиотека экспортирует следующие базовые метрики:
+
+1. **`fasttelemetry_app_info`** (Gauge) — всегда `1`. Содержит метки `version`, `env`, `service`. Используйте для
+   аннотаций деплоев на графиках.
+2. **`fasttelemetry_business_errors_total`** (Counter) — счетчик ошибок бизнес-логики.
+3. **`fasttelemetry_task_processing_seconds`** (Histogram) — время выполнения внутренних задач.
+4. **`http_requests_...`** — [fastapi.json](grafana/fastapi.json) (если используется FastAPI).
+5. **`faststream_...`** — [faststream.json](grafana/faststream.json) (если используется FastStream).
+
+---
+
+## 📈 Base Metrics & Grafana Dashboard
+
+Библиотека предоставляет "Ready-to-use" набор метрик
+
+### Metric Schema
+
+| Metric Name                                  | Type      | Labels                      | Description                                                                      |
+|----------------------------------------------|-----------|-----------------------------|----------------------------------------------------------------------------------|
+| `fasttelemetry_app_info`                     | Gauge     | `env`, `service`, `version` | Информация о запущенном инстансе. Всегда `1`.                                    |
+| `fasttelemetry_business_errors_total`        | Counter   | `error_type`                | Количество ошибок бизнес-логики (пойманных через `track_exception` или вручную). |
+| `fasttelemetry_task_processing_seconds`      | Histogram | `task_type`                 | Время выполнения задач (обернутых в `@measure_task` или `timer`).                |
+| `fasttelemetry_long_task_processing_seconds` | Histogram | `task_type`                 | Время выполнения долгих задач (обернутых в `@measure_task` или `timer`).         |
+
+### ⚙️ Configuration
+
+Вы можете передать параметры явно в `__init__` или использовать переменные окружения:
+
+| Environment Variable | Description                | Default   |
+|----------------------|----------------------------|-----------|
+| `APP_ENV`            | Окружение (prod/dev/stage) | `dev`     |
+| `APP_VERSION`        | Версия приложения          | `unknown` |
+
+### 🖥️ Grafana Dashboard JSON
+
+Дашборды можно импортировать из [папки](grafana)

fast_telemetry-0.0.2.dist-info/RECORD

@@ -0,0 +1,12 @@
+__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fast_telemetry/__init__.py,sha256=maomIZLdB92E2j9kW1caPUa-_B799ZTGEi24NY-ERZI,191
+fast_telemetry/_version.py,sha256=huLsL1iGeXWQKZ8bjwDdIWC7JOkj3wnzBh-HFMZl1PY,704
+fast_telemetry/core.py,sha256=T39rEQuM2W95S9_9ww05a6RSIRFgvo7XFagqKBXGqCk,8431
+fast_telemetry/integrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+fast_telemetry/integrations/fastapi.py,sha256=l2MQaKz8lAdwOBQPFbvzsHlS7I7SYuaHNelCLKu83I0,1082
+fast_telemetry/integrations/faststream.py,sha256=1ncNXCHk9nv1SyV_fKqwo2LpOh8rV1n8wxpLBtb7KGY,3389
+fast_telemetry/integrations/worker.py,sha256=BQCLdjxTB3PluD7Bxv-rPzOjWTkBde6ssg4KOxQENeQ,4713
+fast_telemetry-0.0.2.dist-info/METADATA,sha256=IM_4_-Rlv53La2l4vw15zBWSvmw4N4kFMKdQS6A8zEs,8875
+fast_telemetry-0.0.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+fast_telemetry-0.0.2.dist-info/top_level.txt,sha256=OvY6pUtFsIZyuDZiiIF6RFF-mfjMuvXDpUbz4XXXop0,24
+fast_telemetry-0.0.2.dist-info/RECORD,,

fast_telemetry-0.0.0.dist-info/METADATA

@@ -1,11 +0,0 @@
-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

@@ -1,11 +0,0 @@
-__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,,