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.
