fast-telemetry 0.0.0__tar.gz

fast_telemetry-0.0.0/.gitignore

@@ -0,0 +1,10 @@
+dist
+fast_telemetry.egg-info
+.venv
+*__pycharm__
+src/test.py
+.pytest_cache
+*__pycache__
+.idea
+.DS_Store
+.env

fast_telemetry-0.0.0/.gitlab-ci.yml

@@ -0,0 +1,33 @@
+stages:
+  - build
+  - deploy
+
+variables:
+  PIP_CACHE_DIR: "$CI_PROJECT_DIR/.cache/pip"
+
+cache:
+  paths:
+    - .cache/pip
+
+build_package:
+  stage: build
+  image: python:3.11
+  script:
+    - pip install build
+    - python -m build
+  artifacts:
+    paths:
+      - dist/
+    expire_in: 3 hour
+  only:
+    - tags
+
+upload_to_pypi:
+  stage: deploy
+  image: python:3.11
+  needs: ["build_package"]
+  script:
+    - pip install twine
+    - twine upload dist/*
+  only:
+    - tags

fast_telemetry-0.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,199 @@
+# 📊 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.0/examples/.gitignore

@@ -0,0 +1 @@
+

fast_telemetry-0.0.0/examples/app_example/.gitignore

@@ -0,0 +1,2 @@
+_prometheus_data
+_rabbitmq_data

fast_telemetry-0.0.0/examples/app_example/apps/fastapi/.dockerignore

@@ -0,0 +1 @@
+Dockerfile

fast_telemetry-0.0.0/examples/app_example/apps/fastapi/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.11-alpine
+WORKDIR /app
+RUN apk add --update helm && \
+    adduser -D -u 1000 appuser
+
+COPY --chown=appuser:appuser . .
+RUN pip install --upgrade pip \
+    && pip install --root-user-action=ignore --no-cache-dir -r requirements.txt
+USER appuser
+CMD ["python", "-m", "main"]

fast_telemetry-0.0.0/examples/app_example/apps/fastapi/main.py

@@ -0,0 +1,73 @@
+import asyncio
+import random
+from contextlib import asynccontextmanager
+
+import uvicorn
+from fastapi import FastAPI
+from fast_telemetry.core import PrometheusMetrics
+from fast_telemetry.integrations.fastapi import setup_fastapi_metrics
+from starlette import status
+
+service_name = "demo_service"
+env = "production"
+version = "1.0.0"
+
+metrics = PrometheusMetrics(service_name=service_name, env=env, version=version)
+
+
+@metrics.measure_task("heavy_calculation", long_task=True)
+async def heavy_task():
+    await asyncio.sleep(random.uniform(1, 5))
+
+
+@metrics.track_exception
+async def risky_task():
+    if random.random() < 0.3:
+        raise PaymentError("Payment declined")
+    if random.random() < 0.1:
+        raise DatabaseError("Connection lost")
+    await asyncio.sleep(0.05)
+
+
+async def traffic_generator():
+    print("🚀 Traffic generator started...")
+    while True:
+        try:
+            await heavy_task()
+            await risky_task()
+        except Exception as ex:
+            print(f"Error: {ex}")
+        await asyncio.sleep(5)
+
+
+@asynccontextmanager
+async def lifespan(_: FastAPI):
+    asyncio.create_task(traffic_generator())
+    yield
+
+
+app = FastAPI(title=service_name, lifespan=lifespan, version=version)
+
+setup_fastapi_metrics(app, metrics)
+
+
+class PaymentError(Exception):
+    pass
+
+
+class DatabaseError(Exception):
+    pass
+
+
+@app.post("/foo")
+async def foo(message: dict) -> None:
+    print(f"Incoming message: {message}")
+
+
+@app.get("/health", status_code=status.HTTP_204_NO_CONTENT)
+async def health() -> None:
+    return None
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)

fast_telemetry-0.0.0/examples/app_example/apps/fastapi/requirements.txt

@@ -0,0 +1,6 @@
+fastapi>=0.115.0
+prometheus-client>=0.21.0
+prometheus-fastapi-instrumentator>=6.1.0
+uvicorn>=0.40.0
+
+./fast_telemetry-0.1.0-py3-none-any.whl[web]

fast_telemetry-0.0.0/examples/app_example/apps/faststream/.dockerignore

@@ -0,0 +1 @@
+Dockerfile

fast_telemetry-0.0.0/examples/app_example/apps/faststream/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.11-alpine
+WORKDIR /app
+RUN apk add --update helm && \
+    adduser -D -u 1000 appuser
+
+COPY --chown=appuser:appuser . .
+RUN pip install --upgrade pip \
+    && pip install --root-user-action=ignore --no-cache-dir -r requirements.txt
+USER appuser
+CMD ["python", "-m", "main"]

fast_telemetry-0.0.0/examples/app_example/apps/faststream/main.py

@@ -0,0 +1,81 @@
+import asyncio
+import os
+import random
+from contextlib import asynccontextmanager
+
+import uvicorn
+from faststream.asgi import make_ping_asgi, AsgiFastStream
+from faststream.rabbit import RabbitBroker
+
+from fast_telemetry.core import PrometheusMetrics
+from fast_telemetry.integrations.faststream import setup_faststream_metrics
+
+service_name = "foo_service"
+env = "dev"
+version = "1.2.3"
+queue = "foo"
+metrics = PrometheusMetrics(service_name=service_name, version=version, env=env)
+
+url = (
+    f"amqp://{os.getenv('RABBITMQ_DEFAULT_USER')}:{os.getenv('RABBITMQ_DEFAULT_PASS')}"
+    f"@{os.getenv('RABBITMQ_DEFAULT_HOST')}:{os.getenv('RABBITMQ_DEFAULT_PORT')}/"
+)
+broker = RabbitBroker(url)
+
+
+@metrics.measure_task("heavy_calculation")
+async def heavy_task():
+    await asyncio.sleep(random.uniform(0.1, 0.5))
+
+
+@metrics.track_exception
+async def risky_task():
+    if random.random() < 0.3:
+        raise PaymentError("Payment declined")
+    if random.random() < 0.1:
+        raise DatabaseError("Connection lost")
+    await asyncio.sleep(0.05)
+
+
+async def traffic_generator():
+    print("🚀 Traffic generator started...")
+    while True:
+        try:
+            await heavy_task()
+            await risky_task()
+        except Exception as ex:
+            print(f"Error: {ex}")
+        await asyncio.sleep(5)
+
+
+@asynccontextmanager
+async def lifespan():
+    asyncio.create_task(traffic_generator())
+    yield
+
+
+app = AsgiFastStream(
+    broker, asgi_routes=[("/health", make_ping_asgi(broker))], asyncapi_path="/docs", lifespan=lifespan
+)
+
+
+setup_faststream_metrics(app, metrics)
+
+
+class PaymentError(Exception):
+    pass
+
+
+class DatabaseError(Exception):
+    pass
+
+
+@broker.subscriber(queue)
+async def foo(msg: dict) -> dict:
+    print("incoming message:", msg)
+    await broker.publish({"some_number": random.randint(1, 100)}, "delete_me")
+    return {"message": msg}
+
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="0.0.0.0", port=8000)

fast_telemetry-0.0.0/examples/app_example/apps/faststream/requirements.txt

@@ -0,0 +1,5 @@
+prometheus-client>=0.21.0
+faststream[rabbit]>=0.6.5
+uvicorn>=0.40.0
+
+./fast_telemetry-0.1.0-py3-none-any.whl[stream]

fast_telemetry-0.0.0/examples/app_example/apps/post_init/.dockerignore

@@ -0,0 +1 @@
+Dockerfile

fast_telemetry-0.0.0/examples/app_example/apps/post_init/Dockerfile

@@ -0,0 +1,11 @@
+FROM python:3.11-alpine
+WORKDIR /app
+RUN apk add --update helm && \
+    adduser -D -u 1000 appuser
+
+COPY --chown=appuser:appuser requirements.txt .
+RUN pip install --upgrade pip \
+    && pip install --root-user-action=ignore --no-cache-dir -r requirements.txt
+COPY --chown=appuser:appuser . .
+USER appuser
+CMD ["python", "-m", "main"]

fast_telemetry-0.0.0/examples/app_example/apps/post_init/main.py

@@ -0,0 +1,31 @@
+import asyncio
+import os
+
+from faststream.rabbit import RabbitBroker
+from httpx import AsyncClient
+
+
+async def main():
+    queue = "foo"
+    broker_url = (
+        f"amqp://{os.getenv('RABBITMQ_DEFAULT_USER')}:{os.getenv('RABBITMQ_DEFAULT_PASS')}"
+        f"@{os.getenv('RABBITMQ_DEFAULT_HOST')}:{os.getenv('RABBITMQ_DEFAULT_PORT')}/"
+    )
+    broker = RabbitBroker(broker_url)
+    fastapi_url = os.getenv("FASTAPI_URL")
+    async with AsyncClient(base_url=fastapi_url) as client:
+        async with broker:
+            await broker.start()
+            i = 0
+            while True:
+                message = {"Hello": "World", "message_number": i}
+                print("Send message", message)
+                await client.post("/foo", json=message)
+                await broker.publish(message, queue)
+                i += 1
+                print("Sleep...")
+                await asyncio.sleep(1)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

fast_telemetry-0.0.0/examples/app_example/apps/post_init/requirements.txt

@@ -0,0 +1,2 @@
+faststream[rabbit]~=0.6.5
+httpx~=0.28.1

fast_telemetry-0.0.0/examples/app_example/apps/worker/.dockerignore

@@ -0,0 +1 @@
+Dockerfile

fast_telemetry-0.0.0/examples/app_example/apps/worker/Dockerfile

@@ -0,0 +1,10 @@
+FROM python:3.11-alpine
+WORKDIR /app
+RUN apk add --update helm && \
+    adduser -D -u 1000 appuser
+
+COPY --chown=appuser:appuser . .
+RUN pip install --upgrade pip \
+    && pip install --root-user-action=ignore --no-cache-dir -r requirements.txt
+USER appuser
+CMD ["python", "-m", "main"]

fast_telemetry-0.0.0/examples/app_example/apps/worker/main.py

@@ -0,0 +1,46 @@
+import asyncio
+import random
+
+from fast_telemetry.integrations.worker import WorkerMetrics
+
+metrics = WorkerMetrics(service_name="nightly_job", env="prod")
+
+
+class PaymentError(Exception):
+    pass
+
+
+class DatabaseError(Exception):
+    pass
+
+
+@metrics.measure_task("heavy_calculation")
+async def heavy_task():
+    await asyncio.sleep(random.uniform(0.1, 0.5))
+
+
+@metrics.track_exception
+async def risky_task():
+    if random.random() < 0.3:
+        raise PaymentError("Payment declined")
+    if random.random() < 0.1:
+        raise DatabaseError("Connection lost")
+    await asyncio.sleep(0.05)
+
+
+async def run_worker():
+    metrics.start_server(port=8000)
+    while True:
+        await risky_task()
+        await heavy_task()
+        await asyncio.sleep(5)
+
+
+# async def run_batch_job():
+#     async with metrics.track_job(gateway_url="http://pushgateway:9091"):
+#         await do_heavy_calculation()
+#         metrics.inc_error("calc_error")
+
+
+if __name__ == "__main__":
+    asyncio.run(run_worker())

fast_telemetry-0.0.0/examples/app_example/apps/worker/requirements.txt

@@ -0,0 +1,3 @@
+prometheus-client>=0.21.0
+
+./fast_telemetry-0.1.0-py3-none-any.whl