argus-obs-sdk 1.0.0a3__tar.gz

argus_obs_sdk-1.0.0a3/.gitignore

@@ -0,0 +1,30 @@
+.env
+.env.*
+!.env.example
+!.env.*.example
+*.env.local
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store
+
+# Configuracion del dead man's switch: lleva credenciales de aviso.
+deadman/deadman.json
+
+# Secretos montados en contenedores. Nunca al repositorio.
+platform/secrets/
+
+# El índice se GENERA desde dist/ con scripts/construir_indice.py.
+# Versionar ruedas es versionar binarios que ya sabemos reproducir.
+platform/indice/simple/
+
+# La coordinacion con otros equipos vive FUERA del repositorio, en
+# ~/Documents/Victor/<equipo>_argus/. Aqui hay incidentes suyos, rutas de su
+# codigo y sus identificadores de backlog: es informacion de ellos y este
+# repositorio es publico. Ver docs/coordinacion.md.
+docs/solicitudes/

argus_obs_sdk-1.0.0a3/PKG-INFO

@@ -0,0 +1,132 @@
+Metadata-Version: 2.5
+Name: argus-obs-sdk
+Version: 1.0.0a3
+Summary: SDK de observabilidad de Argus. Para APLICACIONES: configura trazas, metricas y logs con una linea.
+Project-URL: Homepage, https://github.com/Root1V/argus-obs
+Project-URL: Repository, https://github.com/Root1V/argus-obs
+Project-URL: Issues, https://github.com/Root1V/argus-obs/issues
+Author: Emeric Espiritu
+License: MIT
+Keywords: genai,llm,logs,metrics,observability,opentelemetry,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: argus-obs-semconv<2,>=1.0.0a3
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc<2,>=1.30
+Requires-Dist: opentelemetry-sdk<2,>=1.30
+Provides-Extra: all
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.30; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-aiokafka>=0.51b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-asgi>=0.51b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.51b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-celery>=0.51b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.51b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.51b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-redis>=0.51b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-requests>=0.51b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.51b0; extra == 'all'
+Requires-Dist: structlog>=25.1; extra == 'all'
+Provides-Extra: asgi
+Requires-Dist: opentelemetry-instrumentation-asgi>=0.51b0; extra == 'asgi'
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.51b0; extra == 'asgi'
+Provides-Extra: celery
+Requires-Dist: opentelemetry-instrumentation-celery>=0.51b0; extra == 'celery'
+Provides-Extra: client
+Requires-Dist: opentelemetry-instrumentation-httpx>=0.51b0; extra == 'client'
+Requires-Dist: opentelemetry-instrumentation-requests>=0.51b0; extra == 'client'
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml>=6; extra == 'dev'
+Requires-Dist: starlette>=0.37; extra == 'dev'
+Provides-Extra: genai
+Requires-Dist: openlit>=1.34; extra == 'genai'
+Provides-Extra: http
+Requires-Dist: opentelemetry-exporter-otlp-proto-http<2,>=1.30; extra == 'http'
+Provides-Extra: kafka
+Requires-Dist: opentelemetry-instrumentation-aiokafka>=0.51b0; extra == 'kafka'
+Provides-Extra: logging
+Requires-Dist: structlog>=25.1; extra == 'logging'
+Provides-Extra: redis
+Requires-Dist: opentelemetry-instrumentation-redis>=0.51b0; extra == 'redis'
+Provides-Extra: sql
+Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.51b0; extra == 'sql'
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.51b0; extra == 'sql'
+Description-Content-Type: text/markdown
+
+# argus-sdk
+
+SDK de observabilidad de Argus para **aplicaciones**.
+
+```python
+import argus
+argus.init()
+```
+
+Eso configura resource, trazas, métricas, logs, propagadores y todas las
+auto-instrumentaciones disponibles, leyendo la configuración del entorno.
+
+Para servicios ASGI, una línea más:
+
+```python
+app.add_middleware(argus.middleware(app).__class__)   # o ASGIMiddleware directo
+```
+
+## Si escribes una librería, no uses este paquete
+
+Usa [`argus-semconv`](../argus-semconv), que depende solo de
+`opentelemetry-api`. Una librería que depende del SDK impone en silencio su
+versión del SDK y sus opiniones sobre exportadores a todo el que dependa de
+ella.
+
+## El contrato
+
+Verificado por tests en `tests/test_contract.py`, no por buenas intenciones:
+
+1. **Nunca tumba la aplicación.** Si el Collector está caído, la app pierde
+   telemetría, nunca latencia ni memoria.
+2. **Idempotente.** `init()` dos veces es no-op la segunda.
+3. **No-op sin configurar.** Los decoradores funcionan con coste cero.
+4. **Cero configuración en el caso normal.** Todo viene del entorno.
+5. **Superficie pública mínima**, fijada por test.
+
+## Variables de entorno
+
+El contrato es de entorno, no de API de Python: un componente Go y uno Python
+se configuran copiando el mismo bloque.
+
+| Variable | Significado | Por defecto |
+|---|---|---|
+| `ARGUS_SERVICE` | El sub-componente (`service.name`) | `unknown-service` |
+| `ARGUS_NAMESPACE` | La aplicación (`service.namespace`) | = servicio |
+| `ARGUS_ROLE` | `api`/`worker`/`scheduler`/`cli`/`model-server`/`frontend` | `api` |
+| `ARGUS_VERSION` | Versión del componente | — |
+| `ARGUS_ENVIRONMENT` | `mac-dev`, `imac`, `server-1`, `ci` | `local` |
+| `ARGUS_ENDPOINT` | Collector **agente local** | `http://localhost:4317` |
+| `ARGUS_PROTOCOL` | `grpc` \| `http/protobuf` | `grpc` |
+| `ARGUS_PROPAGATE` | `never` \| `trusted` \| `always` | `never` |
+| `ARGUS_TRUSTED_CIDRS` | CIDRs de confianza, separados por coma | — |
+| `ARGUS_CAPTURE_CONTENT` | Capturar prompts y respuestas | `false` |
+| `ARGUS_SLO_MS` | Umbral de latencia del componente | `0` (sin umbral) |
+| `ARGUS_DISABLED` | Apagar toda la telemetría | `false` |
+
+Las estándar de OpenTelemetry (`OTEL_SERVICE_NAME`,
+`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES`) también se respetan,
+para que una app que ya tiene OTel migre sin tocar código.
+
+## Por qué `localhost` y no el plano central
+
+Las aplicaciones exportan **siempre** al Collector agente de su propia máquina.
+Nunca conocen la dirección del plano central. Eso da tres propiedades:
+
+- Mover el plano central de una máquina a otra no toca ni una aplicación.
+- Si el central está suspendido, las apps no se enteran ni se ralentizan: el
+  agente local escribe a disco y envía cuando vuelve la conexión.
+- Añadir una máquina es desplegar un agente, no reconfigurar apps.

argus_obs_sdk-1.0.0a3/README.md

@@ -0,0 +1,69 @@
+# argus-sdk
+
+SDK de observabilidad de Argus para **aplicaciones**.
+
+```python
+import argus
+argus.init()
+```
+
+Eso configura resource, trazas, métricas, logs, propagadores y todas las
+auto-instrumentaciones disponibles, leyendo la configuración del entorno.
+
+Para servicios ASGI, una línea más:
+
+```python
+app.add_middleware(argus.middleware(app).__class__)   # o ASGIMiddleware directo
+```
+
+## Si escribes una librería, no uses este paquete
+
+Usa [`argus-semconv`](../argus-semconv), que depende solo de
+`opentelemetry-api`. Una librería que depende del SDK impone en silencio su
+versión del SDK y sus opiniones sobre exportadores a todo el que dependa de
+ella.
+
+## El contrato
+
+Verificado por tests en `tests/test_contract.py`, no por buenas intenciones:
+
+1. **Nunca tumba la aplicación.** Si el Collector está caído, la app pierde
+   telemetría, nunca latencia ni memoria.
+2. **Idempotente.** `init()` dos veces es no-op la segunda.
+3. **No-op sin configurar.** Los decoradores funcionan con coste cero.
+4. **Cero configuración en el caso normal.** Todo viene del entorno.
+5. **Superficie pública mínima**, fijada por test.
+
+## Variables de entorno
+
+El contrato es de entorno, no de API de Python: un componente Go y uno Python
+se configuran copiando el mismo bloque.
+
+| Variable | Significado | Por defecto |
+|---|---|---|
+| `ARGUS_SERVICE` | El sub-componente (`service.name`) | `unknown-service` |
+| `ARGUS_NAMESPACE` | La aplicación (`service.namespace`) | = servicio |
+| `ARGUS_ROLE` | `api`/`worker`/`scheduler`/`cli`/`model-server`/`frontend` | `api` |
+| `ARGUS_VERSION` | Versión del componente | — |
+| `ARGUS_ENVIRONMENT` | `mac-dev`, `imac`, `server-1`, `ci` | `local` |
+| `ARGUS_ENDPOINT` | Collector **agente local** | `http://localhost:4317` |
+| `ARGUS_PROTOCOL` | `grpc` \| `http/protobuf` | `grpc` |
+| `ARGUS_PROPAGATE` | `never` \| `trusted` \| `always` | `never` |
+| `ARGUS_TRUSTED_CIDRS` | CIDRs de confianza, separados por coma | — |
+| `ARGUS_CAPTURE_CONTENT` | Capturar prompts y respuestas | `false` |
+| `ARGUS_SLO_MS` | Umbral de latencia del componente | `0` (sin umbral) |
+| `ARGUS_DISABLED` | Apagar toda la telemetría | `false` |
+
+Las estándar de OpenTelemetry (`OTEL_SERVICE_NAME`,
+`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_RESOURCE_ATTRIBUTES`) también se respetan,
+para que una app que ya tiene OTel migre sin tocar código.
+
+## Por qué `localhost` y no el plano central
+
+Las aplicaciones exportan **siempre** al Collector agente de su propia máquina.
+Nunca conocen la dirección del plano central. Eso da tres propiedades:
+
+- Mover el plano central de una máquina a otra no toca ni una aplicación.
+- Si el central está suspendido, las apps no se enteran ni se ralentizan: el
+  agente local escribe a disco y envía cuando vuelve la conexión.
+- Añadir una máquina es desplegar un agente, no reconfigurar apps.

argus_obs_sdk-1.0.0a3/pyproject.toml

@@ -0,0 +1,59 @@
+[project]
+name = "argus-obs-sdk"
+version = "1.0.0a3"
+description = "SDK de observabilidad de Argus. Para APLICACIONES: configura trazas, metricas y logs con una linea."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Emeric Espiritu" }]
+keywords = ["observability", "opentelemetry", "tracing", "metrics", "logs", "genai", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Monitoring",
+    "Typing :: Typed",
+]
+
+# Nucleo deliberadamente pequeño. Un Temporal activity o un CLI no deben
+# arrastrar Starlette, y una app que no habla con Kafka no debe instalar su
+# instrumentacion. Todo lo demas va en extras.
+dependencies = [
+    "argus-obs-semconv>=1.0.0a3,<2",
+    "opentelemetry-sdk>=1.30,<2",
+    "opentelemetry-exporter-otlp-proto-grpc>=1.30,<2",
+]
+
+[project.optional-dependencies]
+http     = ["opentelemetry-exporter-otlp-proto-http>=1.30,<2"]
+asgi     = ["opentelemetry-instrumentation-asgi>=0.51b0", "opentelemetry-instrumentation-fastapi>=0.51b0"]
+client   = ["opentelemetry-instrumentation-httpx>=0.51b0", "opentelemetry-instrumentation-requests>=0.51b0"]
+sql      = ["opentelemetry-instrumentation-sqlalchemy>=0.51b0", "opentelemetry-instrumentation-asyncpg>=0.51b0"]
+redis    = ["opentelemetry-instrumentation-redis>=0.51b0"]
+celery   = ["opentelemetry-instrumentation-celery>=0.51b0"]
+kafka    = ["opentelemetry-instrumentation-aiokafka>=0.51b0"]
+logging  = ["structlog>=25.1"]
+genai    = ["openlit>=1.34"]
+all      = ["argus-obs-sdk[http,asgi,client,sql,redis,celery,kafka,logging]"]
+dev      = ["pytest>=8", "pytest-asyncio>=0.24", "httpx>=0.27", "starlette>=0.37", "pyyaml>=6"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/argus"]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+# Quien encuentre esto en PyPI tiene derecho a saber de donde sale y donde
+# reportar. Un paquete sin origen publico es la misma opacidad de cadena de
+# suministro que nos objeto un equipo consumidor (D-075).
+[project.urls]
+Homepage = "https://github.com/Root1V/argus-obs"
+Repository = "https://github.com/Root1V/argus-obs"
+Issues = "https://github.com/Root1V/argus-obs/issues"

argus_obs_sdk-1.0.0a3/src/argus/__init__.py

@@ -0,0 +1,251 @@
+"""Argus SDK — observabilidad para APLICACIONES.
+
+    import argus
+    argus.init()
+
+Eso configura resource, trazas, metricas, logs, propagadores y todas las
+auto-instrumentaciones disponibles, leyendo la configuracion del entorno.
+
+Si escribes una LIBRERIA y no una aplicacion, no uses este paquete: usa
+`argus-semconv`, que depende solo de la API de OpenTelemetry y por tanto no
+impone un SDK ni exportadores a quien te importe.
+
+CONTRATO DE DISENO (verificado por tests, no por buenas intenciones):
+
+1. Nunca tumba la aplicacion. Si algo falla al inicializar, se degrada a no-op
+   con un aviso. Las colas son acotadas y descartan al llenarse: si el Collector
+   cae, la app pierde telemetria, nunca latencia ni memoria.
+2. Idempotente. `init()` dos veces es no-op la segunda.
+3. No-op si no esta configurada. Los decoradores funcionan con coste cero.
+4. Cero configuracion en el caso normal. Los argumentos son para sobrescribir.
+5. Superficie publica minima, fijada por test.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import warnings
+from dataclasses import dataclass
+from typing import Any
+
+# Re-exportamos la superficie de convenciones para que una aplicacion solo
+# tenga que importar `argus`.
+from argus_semconv import (
+    GenAISpan,
+    Step,
+    agent,
+    attributes,
+    capture_enabled,
+    documents,
+    genai,
+    instrument,
+    mask,
+    retrieval,
+    step,
+    tool,
+)
+
+from . import autoinst, propagate
+from ._config import Config, TrustMode
+from ._logging import configure_logging, emit_wide_event
+from ._metrics import GenAIMetrics, configure_metrics
+from ._resource import build_resource
+from ._tracing import configure_tracing
+from .asgi import ASGIMiddleware
+
+# De los metadatos del paquete instalado, no de una constante: una constante se
+# queda obsoleta en cuanto se publica una version y nadie se entera.
+try:
+    from importlib.metadata import version as _version
+
+    __version__ = _version("argus-obs-sdk")
+except Exception:  # noqa: BLE001 - sin instalar (ejecucion desde el arbol)
+    __version__ = "0.0.0.dev0"
+
+_HANDLE: Argus | None = None
+_log = logging.getLogger("argus")
+
+
+@dataclass(slots=True)
+class Argus:
+    """Handle devuelto por `init()`.
+
+    Devolver un handle en vez de `None` no es un capricho: los procesos cortos
+    (CLIs, activities, trabajos por lotes) necesitan `force_flush()` antes de
+    salir, o la telemetria muere con el proceso sin exportarse.
+    """
+
+    config: Config
+    tracer_provider: Any = None
+    meter_provider: Any = None
+    instrumented: tuple[str, ...] = ()
+    genai_metrics: GenAIMetrics | None = None
+
+    def force_flush(self, timeout_millis: int = 5_000) -> None:
+        for provider in (self.tracer_provider, self.meter_provider):
+            if provider is None:
+                continue
+            try:
+                provider.force_flush(timeout_millis)
+            except Exception:  # noqa: BLE001
+                pass
+
+    def shutdown(self) -> None:
+        self.force_flush()
+        for provider in (self.tracer_provider, self.meter_provider):
+            if provider is None:
+                continue
+            try:
+                provider.shutdown()
+            except Exception:  # noqa: BLE001
+                pass
+
+
+def init(
+    service: str | None = None,
+    *,
+    namespace: str | None = None,
+    version: str | None = None,
+    role: str | None = None,
+    environment: str | None = None,
+    endpoint: str | None = None,
+    propagate_mode: TrustMode | None = None,
+    slo_ms: int | None = None,
+    resource_attributes: dict[str, object] | None = None,
+    logging_level: int | str | None = None,
+    json_logs: bool = True,
+    auto_instrument: bool = True,
+    skip_instrumentation: frozenset[str] = frozenset(),
+    disabled: bool | None = None,
+) -> Argus:
+    """Inicializa la telemetria. Idempotente y a prueba de fallos.
+
+    Todos los argumentos son opcionales: el caso normal es `argus.init()` y que
+    la configuracion venga del entorno, que es lo que permite configurar un
+    componente Python y uno Go copiando el mismo bloque de variables.
+    """
+    global _HANDLE
+
+    if _HANDLE is not None:
+        warnings.warn(
+            "argus.init() ya se habia llamado en este proceso. La segunda "
+            "llamada es un no-op.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+        return _HANDLE
+
+    try:
+        cfg = Config.from_env(
+            service,
+            namespace=namespace,
+            version=version,
+            role=role,
+            environment=environment,
+            endpoint=endpoint,
+            propagate=propagate_mode,
+            slo_ms=slo_ms,
+            disabled=disabled,
+        )
+    except Exception as exc:  # noqa: BLE001
+        warnings.warn(f"Argus: configuracion invalida ({exc}). Telemetria desactivada.", RuntimeWarning, stacklevel=2)
+        _HANDLE = Argus(config=Config(service=service or "unknown-service", disabled=True))
+        return _HANDLE
+
+    handle = Argus(config=cfg)
+
+    try:
+        resource = build_resource(cfg, resource_attributes)
+        handle.tracer_provider = configure_tracing(cfg, resource)
+        handle.meter_provider = configure_metrics(cfg, resource)
+        configure_logging(cfg, level=logging_level, force_json=json_logs)
+
+        if handle.meter_provider is not None:
+            handle.genai_metrics = GenAIMetrics()
+
+        if auto_instrument:
+            activated = autoinst.activate(skip=skip_instrumentation)
+            activated += autoinst.activate_genai(skip=skip_instrumentation)
+            autoinst.run_hooks()
+            handle.instrumented = tuple(activated)
+
+    except Exception as exc:  # noqa: BLE001 - regla 1: nunca tumbar la app
+        warnings.warn(
+            f"Argus: la inicializacion fallo ({exc}). La aplicacion continua "
+            "sin telemetria.",
+            RuntimeWarning,
+            stacklevel=2,
+        )
+
+    atexit.register(handle.shutdown)
+    _HANDLE = handle
+
+    _log.info(
+        "argus.init",
+        extra={
+            "app": cfg.namespace,
+            "service": cfg.service,
+            "role": cfg.role,
+            "environment": cfg.environment,
+            "endpoint": cfg.endpoint if not cfg.disabled else "disabled",
+            "propagate": cfg.propagate,
+            "instrumented": ",".join(handle.instrumented),
+        },
+    )
+    return handle
+
+
+def handle() -> Argus | None:
+    """El handle actual, si `init()` ya se llamo."""
+    return _HANDLE
+
+
+def middleware(app: Any, **kwargs: Any) -> ASGIMiddleware:
+    """Envuelve una app ASGI heredando la configuracion de `init()`."""
+    cfg = _HANDLE.config if _HANDLE else Config.from_env()
+    kwargs.setdefault("service", cfg.service)
+    kwargs.setdefault("propagate_mode", cfg.propagate)
+    kwargs.setdefault("trusted_cidrs", cfg.trusted_cidrs)
+    kwargs.setdefault("slo_ms", cfg.slo_ms)
+    return ASGIMiddleware(app, **kwargs)
+
+
+def _reset_for_tests() -> None:
+    global _HANDLE
+    from . import _logging
+
+    _logging.reset_for_tests()
+    _HANDLE = None
+
+
+__all__ = [
+    # Arranque
+    "init",
+    "handle",
+    "Argus",
+    "Config",
+    # ASGI
+    "ASGIMiddleware",
+    "middleware",
+    # Convenciones (re-exportadas de argus-semconv)
+    "genai",
+    "retrieval",
+    "tool",
+    "agent",
+    "documents",
+    "step",
+    "instrument",
+    "GenAISpan",
+    "Step",
+    "attributes",
+    "capture_enabled",
+    "mask",
+    # Propagacion fuera de HTTP
+    "propagate",
+    "autoinst",
+    # Utilidades
+    "emit_wide_event",
+    "GenAIMetrics",
+    "__version__",
+]