apibrasil-requests-monitor 0.1.0

SDK de monitoramento de requests para APIs Flask da APIBrasil

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:

pip install apibrasil-requests-monitor

Com suporte Flask:

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

3) Uso minimo

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:

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:

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

APIBRASIL_MONITOR_ENABLED=false

ou via codigo:

monitor(app, enabled=False)

9) Como testar localmente

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

10) Publicacao no PyPI/TestPyPI

Build e validacao:

python -m build
twine check dist/*

TestPyPI:

twine upload --repository testpypi dist/*

PyPI:

twine upload dist/*

Instalacao via Git (enquanto nao estiver no PyPI):

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):

{
  "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
}