pz-cli 5.0.0__py3-none-any.whl

pz_foundation/observability/logger/telegram_bot.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import logging
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from threading import BoundedSemaphore
+from typing import Callable
+
+try:
+    import requests
+except Exception:  # pragma: no cover
+    requests = None  # type: ignore
+
+from ._bot_settings import resolve_bot_message_char_limit, resolve_bot_pending_limit, resolve_bot_worker_count
+from .bot_message import BotMessage, MessageLevel, MessageType, TelegramMessageFormatter
+from .delivery_audit import record_bot_delivery_drop, record_bot_delivery_failure, record_bot_delivery_success
+
+
+class TelegramBotHandler(logging.Handler):
+    _executor: ThreadPoolExecutor | None = None
+    _instances: dict[str, "TelegramBotHandler"] = {}
+    _pending_limit: int | None = None
+    _pending_semaphore: BoundedSemaphore | None = None
+
+    @classmethod
+    def get_instance(cls, bot_token: str | None = None, chat_id: str | None = None, handler_name: str = "default"):
+        if handler_name not in cls._instances and bot_token and chat_id:
+            cls._instances[handler_name] = cls(bot_token, chat_id, handler_name)
+        return cls._instances.get(handler_name)
+
+    def __init__(self, bot_token: str, chat_id: str, handler_name: str = "default") -> None:
+        super().__init__()
+        self.bot_token = bot_token
+        self.chat_id = chat_id
+        self.handler_name = handler_name
+        self.base_url = f"https://api.telegram.org/bot{bot_token}"
+
+    @classmethod
+    def reset(cls) -> None:
+        cls._instances.clear()
+        cls._pending_limit = None
+        cls._pending_semaphore = None
+        executor = cls._executor
+        cls._executor = None
+        if executor is not None:
+            try:
+                executor.shutdown(wait=False, cancel_futures=True)
+            except TypeError:
+                executor.shutdown(wait=False)
+
+    @classmethod
+    def _get_executor(cls) -> ThreadPoolExecutor:
+        executor = cls._executor
+        if executor is None:
+            executor = ThreadPoolExecutor(
+                max_workers=resolve_bot_worker_count("telegram"),
+                thread_name_prefix="foundation_telegram_bot",
+            )
+            cls._executor = executor
+        return executor
+
+    @classmethod
+    def _get_pending_semaphore(cls) -> BoundedSemaphore:
+        limit = resolve_bot_pending_limit("telegram")
+        semaphore = cls._pending_semaphore
+        if semaphore is None or cls._pending_limit != limit:
+            semaphore = BoundedSemaphore(limit)
+            cls._pending_semaphore = semaphore
+            cls._pending_limit = limit
+        return semaphore
+
+    def _submit(self, operation: str, fn: Callable[..., None], *args: object) -> None:
+        semaphore = self._get_pending_semaphore()
+        if not semaphore.acquire(blocking=False):
+            record_bot_delivery_drop(
+                channel="telegram",
+                handler_name=self.handler_name,
+                operation=operation,
+                reason="backpressure",
+            )
+            return
+        try:
+            future = self._get_executor().submit(fn, *args)
+        except Exception:
+            try:
+                semaphore.release()
+            except ValueError:
+                pass
+            raise
+        if future is None:
+            try:
+                semaphore.release()
+            except ValueError:
+                pass
+            return
+
+        def _release(_future) -> None:  # noqa: ANN001
+            try:
+                semaphore.release()
+            except ValueError:
+                pass
+
+        future.add_done_callback(_release)
+
+    def emit(self, record: logging.LogRecord) -> None:
+        requested_bot_type = getattr(record, "bot_type", None)
+        if requested_bot_type not in (None, "both", "telegram"):
+            return
+        self.send_bot_message(
+            BotMessage(
+                content=self.format(record),
+                level=_message_level_from_record(record),
+                title=None,
+            )
+        )
+
+    def send_bot_message(self, message: BotMessage) -> None:
+        if not self.bot_token or not self.chat_id or requests is None:
+            return
+        if message.message_type == MessageType.IMAGE and message.image_url:
+            governed = TelegramMessageFormatter.prepare_message_for_channel(
+                message,
+                max_chars=resolve_bot_message_char_limit("telegram", kind="caption"),
+            )
+            payload = {
+                "chat_id": self.chat_id,
+                "photo": governed.image_url,
+                "caption": TelegramMessageFormatter.format_message(governed, None),
+                "parse_mode": "HTML",
+            }
+            self._submit("sendPhoto", self._post_photo, payload)
+            return
+        governed = TelegramMessageFormatter.prepare_message_for_channel(
+            message,
+            max_chars=resolve_bot_message_char_limit("telegram", kind="text"),
+        )
+        payload = {
+            "chat_id": self.chat_id,
+            "text": TelegramMessageFormatter.format_message(governed, None),
+            "parse_mode": "HTML",
+            "disable_web_page_preview": True,
+        }
+        self._submit("sendMessage", self._post_text, payload)
+
+    def _post_text(self, payload: dict[str, object]) -> None:
+        try:
+            response = requests.post(f"{self.base_url}/sendMessage", json=payload, timeout=10)
+            response.raise_for_status()
+            record_bot_delivery_success(
+                channel="telegram",
+                handler_name=self.handler_name,
+                operation="sendMessage",
+            )
+        except Exception as exc:  # pragma: no cover
+            record_bot_delivery_failure(
+                channel="telegram",
+                handler_name=self.handler_name,
+                operation="sendMessage",
+                exc=exc,
+            )
+            print(f"Error sending Telegram message ({self.handler_name}): {exc}", file=sys.stderr)
+
+    def _post_photo(self, payload: dict[str, object]) -> None:
+        try:
+            response = requests.post(f"{self.base_url}/sendPhoto", json=payload, timeout=10)
+            response.raise_for_status()
+            record_bot_delivery_success(
+                channel="telegram",
+                handler_name=self.handler_name,
+                operation="sendPhoto",
+            )
+        except Exception as exc:  # pragma: no cover
+            record_bot_delivery_failure(
+                channel="telegram",
+                handler_name=self.handler_name,
+                operation="sendPhoto",
+                exc=exc,
+            )
+            print(f"Error sending Telegram photo ({self.handler_name}): {exc}", file=sys.stderr)
+
+
+def _message_level_from_record(record: logging.LogRecord) -> MessageLevel:
+    if record.levelname == "CUSTOM_EVENT":
+        return MessageLevel.CUSTOM_EVENT
+    if record.levelname == "ERROR":
+        return MessageLevel.ERROR
+    if record.levelname == "WARNING":
+        return MessageLevel.WARNING
+    if record.levelname == "DEBUG":
+        return MessageLevel.DEBUG
+    return MessageLevel.INFO
+
+
+__all__ = ["TelegramBotHandler"]

pz_foundation/observability/metrics.py

@@ -0,0 +1,365 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass, field
+from threading import RLock
+from typing import Any, Literal
+
+
+PrometheusMetricType = Literal["counter", "gauge", "histogram", "summary", "untyped"]
+PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
+
+
+def _label_key(labels: dict[str, Any]) -> tuple[tuple[str, str], ...]:
+    return tuple(sorted((str(key), str(value)) for key, value in labels.items()))
+
+
+@dataclass(slots=True)
+class _CounterMetric:
+    name: str
+    samples: dict[tuple[tuple[str, str], ...], float] = field(default_factory=dict)
+    _lock: RLock = field(default_factory=RLock, repr=False)
+
+    def labels(self, **labels: Any):
+        return _BoundCounter(self, _label_key(labels))
+
+    def inc(self, amount: float = 1.0) -> None:
+        with self._lock:
+            self.samples[()] = float(self.samples.get((), 0.0) + amount)
+
+
+@dataclass(slots=True)
+class _BoundCounter:
+    metric: _CounterMetric
+    labels_key: tuple[tuple[str, str], ...]
+
+    def inc(self, amount: float = 1.0) -> None:
+        with self.metric._lock:
+            self.metric.samples[self.labels_key] = float(self.metric.samples.get(self.labels_key, 0.0) + amount)
+
+
+@dataclass(slots=True)
+class _GaugeMetric:
+    name: str
+    samples: dict[tuple[tuple[str, str], ...], float] = field(default_factory=dict)
+    _lock: RLock = field(default_factory=RLock, repr=False)
+
+    def labels(self, **labels: Any):
+        return _BoundGauge(self, _label_key(labels))
+
+    def set(self, value: float) -> None:
+        with self._lock:
+            self.samples[()] = float(value)
+
+
+@dataclass(slots=True)
+class _BoundGauge:
+    metric: _GaugeMetric
+    labels_key: tuple[tuple[str, str], ...]
+
+    def set(self, value: float) -> None:
+        with self.metric._lock:
+            self.metric.samples[self.labels_key] = float(value)
+
+
+@dataclass(slots=True)
+class _HistogramMetric:
+    name: str
+    samples: dict[tuple[tuple[str, str], ...], list[float]] = field(default_factory=dict)
+    _lock: RLock = field(default_factory=RLock, repr=False)
+
+    def labels(self, **labels: Any):
+        return _BoundHistogram(self, _label_key(labels))
+
+    def observe(self, value: float) -> None:
+        with self._lock:
+            self.samples.setdefault((), []).append(float(value))
+
+
+@dataclass(slots=True)
+class _BoundHistogram:
+    metric: _HistogramMetric
+    labels_key: tuple[tuple[str, str], ...]
+
+    def observe(self, value: float) -> None:
+        with self.metric._lock:
+            self.metric.samples.setdefault(self.labels_key, []).append(float(value))
+
+
+class MetricsRegistry:
+    def __init__(self) -> None:
+        self.http_requests_total = _CounterMetric("http_requests_total")
+        self.http_request_duration_seconds = _HistogramMetric("http_request_duration_seconds")
+        self.db_reconnects_total = _CounterMetric("db_reconnects_total")
+        self.db_retries_total = _CounterMetric("db_retries_total")
+        self.foundation_bot_delivery_total = _CounterMetric("foundation_bot_delivery_total")
+        self.foundation_storage_probes_total = _CounterMetric("foundation_storage_probes_total")
+        self.foundation_mail_probes_total = _CounterMetric("foundation_mail_probes_total")
+        self.foundation_health_checks_total = _CounterMetric("foundation_health_checks_total")
+        self.foundation_runtime_ready = _GaugeMetric("foundation_runtime_ready")
+
+    @property
+    def enabled(self) -> bool:
+        return True
+
+    def snapshot(self) -> dict[str, Any]:
+        return {
+            "http_requests_total": dict(self.http_requests_total.samples),
+            "http_request_duration_seconds": {key: list(values) for key, values in self.http_request_duration_seconds.samples.items()},
+            "db_reconnects_total": dict(self.db_reconnects_total.samples),
+            "db_retries_total": dict(self.db_retries_total.samples),
+            "foundation_bot_delivery_total": dict(self.foundation_bot_delivery_total.samples),
+            "foundation_storage_probes_total": dict(self.foundation_storage_probes_total.samples),
+            "foundation_mail_probes_total": dict(self.foundation_mail_probes_total.samples),
+            "foundation_health_checks_total": dict(self.foundation_health_checks_total.samples),
+            "foundation_runtime_ready": dict(self.foundation_runtime_ready.samples),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class PrometheusSample:
+    value: float
+    labels: Mapping[str, str] = field(default_factory=dict)
+    suffix: str = ""
+
+
+@dataclass(frozen=True, slots=True)
+class PrometheusMetricFamily:
+    name: str
+    metric_type: PrometheusMetricType
+    samples: tuple[PrometheusSample, ...]
+    help: str = ""
+
+
+PrometheusCollector = Callable[[], Iterable[PrometheusMetricFamily]]
+
+
+_prometheus_collectors: dict[str, PrometheusCollector] = {}
+_prometheus_collector_errors: dict[str, float] = {}
+_prometheus_collectors_lock = RLock()
+
+
+def register_prometheus_collector(name: str, collector: PrometheusCollector) -> None:
+    normalized = _normalize_collector_name(name)
+    if not callable(collector):
+        raise TypeError("prometheus collector must be callable")
+    with _prometheus_collectors_lock:
+        _prometheus_collectors[normalized] = collector
+
+
+def unregister_prometheus_collector(name: str) -> None:
+    normalized = _normalize_collector_name(name)
+    with _prometheus_collectors_lock:
+        _prometheus_collectors.pop(normalized, None)
+        _prometheus_collector_errors.pop(normalized, None)
+
+
+def render_prometheus_text(*, namespace: str = "pz") -> str:
+    families = [
+        *_registry_prometheus_families(get_metrics_registry()),
+        *_collector_prometheus_families(),
+    ]
+    rendered = _render_prometheus_families(families, namespace=namespace)
+    return rendered if rendered.endswith("\n") else f"{rendered}\n"
+
+
+def _normalize_collector_name(name: str) -> str:
+    normalized = str(name or "").strip()
+    if not normalized:
+        raise ValueError("prometheus collector name is required")
+    return normalized
+
+
+def _registry_prometheus_families(registry: MetricsRegistry) -> tuple[PrometheusMetricFamily, ...]:
+    families: list[PrometheusMetricFamily] = []
+    for value in vars(registry).values():
+        if isinstance(value, _CounterMetric):
+            families.append(
+                PrometheusMetricFamily(
+                    name=value.name,
+                    metric_type="counter",
+                    help=f"{value.name} counter",
+                    samples=tuple(
+                        PrometheusSample(value=sample_value, labels=dict(label_key))
+                        for label_key, sample_value in value.samples.items()
+                    ),
+                )
+            )
+        elif isinstance(value, _GaugeMetric):
+            families.append(
+                PrometheusMetricFamily(
+                    name=value.name,
+                    metric_type="gauge",
+                    help=f"{value.name} gauge",
+                    samples=tuple(
+                        PrometheusSample(value=sample_value, labels=dict(label_key))
+                        for label_key, sample_value in value.samples.items()
+                    ),
+                )
+            )
+        elif isinstance(value, _HistogramMetric):
+            samples: list[PrometheusSample] = []
+            for label_key, observed_values in value.samples.items():
+                labels = dict(label_key)
+                samples.append(PrometheusSample(value=float(len(observed_values)), labels=labels, suffix="_count"))
+                samples.append(PrometheusSample(value=float(sum(observed_values)), labels=labels, suffix="_sum"))
+            families.append(
+                PrometheusMetricFamily(
+                    name=value.name,
+                    metric_type="summary",
+                    help=f"{value.name} summary",
+                    samples=tuple(samples),
+                )
+            )
+    return tuple(families)
+
+
+def _collector_prometheus_families() -> tuple[PrometheusMetricFamily, ...]:
+    with _prometheus_collectors_lock:
+        collectors = tuple(_prometheus_collectors.items())
+    families: list[PrometheusMetricFamily] = []
+    for collector_name, collector in collectors:
+        try:
+            families.extend(tuple(collector()))
+        except Exception:
+            with _prometheus_collectors_lock:
+                _prometheus_collector_errors[collector_name] = (
+                    _prometheus_collector_errors.get(collector_name, 0.0) + 1.0
+                )
+                error_count = _prometheus_collector_errors[collector_name]
+            families.append(
+                PrometheusMetricFamily(
+                    name="metrics_collector_errors_total",
+                    metric_type="counter",
+                    help="Metrics collector failures during scrape.",
+                    samples=(PrometheusSample(value=error_count, labels={"collector": collector_name}),),
+                )
+            )
+    return tuple(families)
+
+
+def _render_prometheus_families(
+    families: Iterable[PrometheusMetricFamily],
+    *,
+    namespace: str,
+) -> str:
+    normalized_namespace = _normalize_metric_part(namespace)
+    lines: list[str] = []
+    emitted_meta: set[str] = set()
+    for family in sorted(tuple(families), key=lambda item: item.name):
+        if not family.samples:
+            continue
+        metric_name = _namespaced_metric_name(family.name, normalized_namespace)
+        if metric_name not in emitted_meta:
+            lines.append(f"# HELP {metric_name} {_escape_help(family.help or family.name)}")
+            lines.append(f"# TYPE {metric_name} {family.metric_type}")
+            emitted_meta.add(metric_name)
+        for sample in family.samples:
+            lines.append(
+                _render_sample(
+                    f"{metric_name}{sample.suffix}",
+                    value=sample.value,
+                    labels=sample.labels,
+                )
+            )
+    return "\n".join(lines)
+
+
+def _render_sample(name: str, *, value: float, labels: Mapping[str, str]) -> str:
+    if labels:
+        label_text = ",".join(
+            f'{_normalize_metric_part(key)}="{_escape_label_value(value)}"'
+            for key, value in sorted(labels.items())
+        )
+        return f"{name}{{{label_text}}} {_format_prometheus_float(float(value))}"
+    return f"{name} {_format_prometheus_float(float(value))}"
+
+
+def _namespaced_metric_name(name: str, namespace: str) -> str:
+    normalized = _normalize_metric_part(name)
+    if not namespace or normalized.startswith(f"{namespace}_"):
+        return normalized
+    return f"{namespace}_{normalized}"
+
+
+def _normalize_metric_part(value: object) -> str:
+    text = str(value or "").strip()
+    chars = [ch if ch.isalnum() or ch == "_" else "_" for ch in text]
+    normalized = "".join(chars).strip("_")
+    if not normalized:
+        return "metric"
+    if normalized[0].isdigit():
+        normalized = f"_{normalized}"
+    return normalized
+
+
+def _escape_help(value: object) -> str:
+    return str(value or "").replace("\\", "\\\\").replace("\n", "\\n")
+
+
+def _escape_label_value(value: object) -> str:
+    return (
+        str(value or "")
+        .replace("\\", "\\\\")
+        .replace("\n", "\\n")
+        .replace('"', '\\"')
+    )
+
+
+def _format_prometheus_float(value: float) -> str:
+    if value == float("inf"):
+        return "+Inf"
+    if value == float("-inf"):
+        return "-Inf"
+    if value != value:
+        return "NaN"
+    return format(value, ".15g")
+
+
+@dataclass(slots=True)
+class _LazyAccessor:
+    factory: Callable[[], MetricsRegistry]
+    _instance: MetricsRegistry | None = None
+
+    def _get_instance(self) -> MetricsRegistry:
+        if self._instance is None:
+            self._instance = self.factory()
+        return self._instance
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._get_instance(), name)
+
+
+_metrics_registry_instance: MetricsRegistry | None = None
+
+
+def get_metrics_registry() -> MetricsRegistry:
+    global _metrics_registry_instance
+    if _metrics_registry_instance is None:
+        _metrics_registry_instance = MetricsRegistry()
+    return _metrics_registry_instance
+
+
+def reset_metrics_registry() -> None:
+    global _metrics_registry_instance
+    _metrics_registry_instance = None
+    metrics._instance = None
+
+
+metrics = _LazyAccessor(get_metrics_registry)
+
+
+__all__ = [
+    "MetricsRegistry",
+    "PROMETHEUS_CONTENT_TYPE",
+    "PrometheusCollector",
+    "PrometheusMetricFamily",
+    "PrometheusMetricType",
+    "PrometheusSample",
+    "get_metrics_registry",
+    "metrics",
+    "register_prometheus_collector",
+    "render_prometheus_text",
+    "reset_metrics_registry",
+    "unregister_prometheus_collector",
+]

pz_foundation/observability/runtime.py

@@ -0,0 +1,68 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import pz_settings_center.public as settings_center
+from .logger.core import configure_logging
+from .metrics import get_metrics_registry
+
+
+def _resolved_settings(*, project_dir: str | os.PathLike[str] | None = None):
+    if project_dir is None:
+        return settings_center.settings
+    return settings_center.resolve_settings(project_dir=str(Path(project_dir).resolve()))
+
+
+def _project_settings(*, project_dir: str | os.PathLike[str] | None = None):
+    try:
+        return _resolved_settings(project_dir=project_dir).project
+    except Exception:
+        return None
+
+
+def _foundation_settings_section(
+    name: str,
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+):
+    try:
+        return getattr(getattr(_resolved_settings(project_dir=project_dir), "pz_foundation"), str(name or "").strip())
+    except Exception:
+        return {}
+
+
+def probe_observability(
+    *,
+    project_dir: str | os.PathLike[str] | None = None,
+) -> dict[str, Any]:
+    try:
+        project = _project_settings(project_dir=project_dir)
+        observability = _foundation_settings_section("observability", project_dir=project_dir)
+    except Exception:
+        project = None
+        observability = {}
+    metrics_cfg = getattr(observability, "metrics", {})
+    project_root = Path(str(getattr(project, "project_dir", ".") or ".")).resolve()
+    log_dir = project_root / ".runtime" / "logs" / "foundation"
+    status: dict[str, Any] = {
+        "enabled": True,
+        "configured": True,
+        "ready": False,
+        "error": None,
+        "log_dir": str(log_dir),
+        "pz_env": str(settings_center.current_pz_env(project_dir=project_dir, default="develop") or "develop"),
+        "metrics_enabled": bool(metrics_cfg.get("enabled", False)) if isinstance(metrics_cfg, dict) else bool(getattr(metrics_cfg, "enabled", False)),
+        "metrics_registry_enabled": bool(get_metrics_registry().enabled),
+    }
+    try:
+        log_dir.mkdir(parents=True, exist_ok=True)
+        configure_logging(log_dir=log_dir, pz_env=status["pz_env"])
+        probe = log_dir / ".probe"
+        probe.write_text("ok", encoding="utf-8")
+        probe.unlink()
+        status["ready"] = True
+    except Exception as exc:
+        status["error"] = f"{type(exc).__name__}: {exc}"
+    return status
+__all__ = ["probe_observability"]