Metadata-Version: 2.4
Name: apibrasil-requests-monitor
Version: 0.1.0
Summary: SDK de monitoramento de requests para APIs Flask da APIBrasil
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Provides-Extra: flask
Requires-Dist: flask>=2.3; extra == "flask"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Dynamic: license-file

# apibrasil-requests-monitor

SDK Python para monitorar automaticamente requests em APIs Flask da APIBrasil, com envio assíncrono de eventos para um collector externo.

## 1) O que e

- Captura metadata de cada request Flask (metodo, rota, status, duracao, tipo e homolog).
- Envia evento em background para nao impactar a latencia da API.
- Nao envia body completo por padrao e evita vazamento de dados sensiveis.

## 2) Instalacao

Instalacao basica:

```bash
pip install apibrasil-requests-monitor
```

Com suporte Flask:

```bash
pip install "apibrasil-requests-monitor[flask]"
```

## 3) Uso minimo

```python
from flask import Flask
from apibrasil_requests_monitor import monitor

app = Flask(__name__)
monitor(app)
```

## 4) Configuracao por .env / ambiente

Variaveis suportadas:

- `APIBRASIL_MONITOR_ENABLED` (default: `true`)
- `APIBRASIL_MONITOR_KEY`
- `APIBRASIL_MONITOR_PROJECT_KEY`
- `APIBRASIL_MONITOR_ENDPOINT`
- `APIBRASIL_MONITOR_FIELDS` (default: `tipo,homolog`)
- `APIBRASIL_MONITOR_MASK_FIELDS`
- `APIBRASIL_MONITOR_SERVICE_NAME`
- `APIBRASIL_MONITOR_ENVIRONMENT` (default: `production`)
- `APIBRASIL_MONITOR_TIMEOUT_SECONDS` (default: `2`)
- `APIBRASIL_MONITOR_QUEUE_SIZE` (default: `1000`)
- `APIBRASIL_MONITOR_IGNORED_PATHS` (default: `/health,/metrics`)
- `APIBRASIL_MONITOR_SAMPLE_RATE` (default: `1.0`)

Exemplo:

```env
APIBRASIL_MONITOR_PROJECT_KEY=api-cpf
APIBRASIL_MONITOR_KEY=sua-chave
APIBRASIL_MONITOR_ENDPOINT=https://manager.exemplo.com/api/monitor/events
APIBRASIL_MONITOR_FIELDS=tipo,homolog
```

Se `APIBRASIL_MONITOR_KEY` ou `APIBRASIL_MONITOR_ENDPOINT` nao existirem, o SDK fica desativado automaticamente (fail-safe).

## 5) Exemplo Flask

Veja `examples/flask_basic.py`.

## 6) Campos capturados

Por padrao, somente:

- `tipo`
- `homolog`

Com configuracao explicita:

```python
from apibrasil_requests_monitor import monitor

monitor(
    app,
    project_key="api-cpf",
    endpoint="https://manager.exemplo.com/api/monitor/events",
    capture_fields=["tipo", "homolog"],
    mask_fields=["cpf", "cnpj", "placa", "token", "api_key", "api_secret"],
)
```

## 7) Seguranca e privacidade

- Nao envia body completo por padrao.
- Extrai apenas campos permitidos (`capture_fields`).
- Campos sensiveis em `mask_fields` sao mascarados quando capturados.
- Nao faz `print`.
- Nao loga monitor key/token.

## 8) Como desativar

```env
APIBRASIL_MONITOR_ENABLED=false
```

ou via codigo:

```python
monitor(app, enabled=False)
```

## 9) Como testar localmente

```bash
python -m pip install -e ".[dev,flask]"
pytest
```

## 10) Publicacao no PyPI/TestPyPI

Build e validacao:

```bash
python -m build
twine check dist/*
```

TestPyPI:

```bash
twine upload --repository testpypi dist/*
```

PyPI:

```bash
twine upload dist/*
```

Instalacao via Git (enquanto nao estiver no PyPI):

```bash
pip install "apibrasil-requests-monitor @ git+https://github.com/APIBrasil/apibrasil-requests-monitor.git@v0.1.0"
```

## 11) Troubleshooting

- **Nao envia eventos**: valide `APIBRASIL_MONITOR_KEY` e `APIBRASIL_MONITOR_ENDPOINT`.
- **Queue cheia**: aumente `APIBRASIL_MONITOR_QUEUE_SIZE` ou ajuste `APIBRASIL_MONITOR_SAMPLE_RATE`.
- **Campos ausentes**: revise `APIBRASIL_MONITOR_FIELDS` e payload JSON.
- **Dependencia Flask faltando**: instale com extra `[flask]`.

## Contrato HTTP enviado ao collector

Headers:

- `Content-Type: application/json`
- `X-APIBrasil-Monitor-Key: <APIBRASIL_MONITOR_KEY>`
- `X-APIBrasil-Monitor-SDK: python`
- `X-APIBrasil-Monitor-Version: 0.1.0`

Payload (exemplo):

```json
{
  "sdk": {
    "name": "apibrasil-requests-monitor",
    "version": "0.1.0"
  },
  "project_key": "api-cpf",
  "service_name": "api-cpf",
  "environment": "production",
  "request_id": "uuid",
  "timestamp": "2026-01-01T10:00:00Z",
  "method": "POST",
  "path": "/consulta",
  "status_code": 200,
  "duration_ms": 123,
  "content_type": "application/json",
  "remote_addr": "127.0.0.1",
  "user_agent": "python-requests/2.31",
  "metrics": {
    "tipo": "cpf",
    "homolog": false
  },
  "error": null
}
```
