Metadata-Version: 2.4
Name: obskitpy
Version: 0.5.0
Summary: Observabilidade (OpenTelemetry + Elasticsearch + Kibana) para qualquer projeto Python, via CLI.
Author: Pedro França
License-Expression: MIT
Project-URL: Homepage, https://github.com/pedrowill-dev/obskitpy
Project-URL: Documentation, https://github.com/pedrowill-dev/obskitpy/tree/main/docs
Project-URL: Issues, https://github.com/pedrowill-dev/obskitpy/issues
Keywords: observability,opentelemetry,elasticsearch,kibana,rpa,logging,tracing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Logging
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: opentelemetry-api==1.27.0
Requires-Dist: opentelemetry-sdk==1.27.0
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc==1.27.0
Provides-Extra: requests
Requires-Dist: opentelemetry-instrumentation-requests==0.48b0; extra == "requests"
Requires-Dist: setuptools==75.6.0; extra == "requests"
Provides-Extra: portal
Requires-Dist: fastapi<0.150,>=0.115; extra == "portal"
Requires-Dist: uvicorn>=0.30; extra == "portal"
Requires-Dist: sqlalchemy>=2.0; extra == "portal"
Requires-Dist: psycopg[binary]>=3.2; extra == "portal"
Requires-Dist: cryptography>=43; extra == "portal"
Requires-Dist: httpx>=0.27; extra == "portal"
Requires-Dist: pydantic>=2.8; extra == "portal"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Dynamic: license-file

<p align="center"><img src="https://raw.githubusercontent.com/pedrowill-dev/obskitpy/main/docs/images/logo.png" alt="obskitpy" width="380"></p>

# obskitpy

Observabilidade (OpenTelemetry → Elasticsearch → Kibana) em qualquer projeto Python, via CLI.

> Documentação completa na raiz do repositório: [`docs/`](../docs/inicio-rapido.md). Este arquivo é um resumo.

## Começar (2 comandos)

```bash
uv add "obskitpy[requests]"      # ou pip install; o extra 'requests' adiciona spans HTTP automáticos
cd meu-projeto
obskitpy init                   # cria observability/ (stack + dashboard base); --service NOME opcional
obskitpy up                     # sobe ES + Kibana + Collector e cria o dashboard
```

No código:

```python
import logging, obskitpy

log = logging.getLogger(__name__)
shutdown = obskitpy.setup("meu-servico")     # logs + traces + métricas via OTLP (localhost:4317)

@obskitpy.traced()                            # um span por chamada, marca erro se a exceção propagar
def processar(item): ...

try:
    processar(x)
except Exception:
    log.exception("falhou")                 # já sai com error.type, error.origin e error.chain

shutdown()                                  # descarrega os dados pendentes
```

Métricas próprias: `obskitpy.meter().create_counter("pedidos.processados")` (API do OpenTelemetry).

## Comandos

| Comando | O que faz |
|---|---|
| `obskitpy init [--service N] [--kibana-port P ...]` | cria `observability/` (compose, collector, `dashboard.ndjson`, `.env`) |
| `obskitpy up` | sobe a stack, espera ficar saudável e **aplica o dashboard** |
| `obskitpy down [-v]` | derruba (`-v` apaga os dados) |
| `obskitpy status` / `obskitpy open` | containers + link / abre o dashboard |
| `obskitpy dashboard export` | grava no arquivo o dashboard **como está no Kibana** |
| `obskitpy dashboard apply` | importa `observability/dashboard.ndjson` no Kibana |

Todos aceitam `--dir` (padrão `observability`).

## Evoluindo o dashboard

1. `obskitpy up` já cria o dashboard `<servico>-observability` com os painéis básicos: logs, erros, execuções (traces), duração de spans, erros por tipo/origem e lista de erros com `trace_id`.
2. Edite no Kibana (adicione painéis, métricas do seu domínio, filtros).
3. `obskitpy dashboard export` e versione `observability/dashboard.ndjson` no git.
4. Em outra máquina/CI: `obskitpy up` (ou `obskitpy dashboard apply`) recria tudo.

Os painéis filtram por `resource.attributes.service.name`, então vários serviços podem compartilhar uma stack (use o mesmo `--dir`/portas) ou ter uma cada (use portas diferentes no `init`).

## Observações

- Ambiente local: segurança do Elasticsearch desligada, portas só em `127.0.0.1`.
- Os dados demoram alguns segundos para ficar pesquisáveis após o primeiro envio.
- Colima/Docker: o `docker compose` precisa enxergar a pasta do projeto (no Colima, só `$HOME` é montado por padrão).
- Requer Docker com o plugin Compose v2.
