Metadata-Version: 2.4
Name: ccd-logger
Version: 0.2.0
Summary: Biblioteca padrão de logging estruturado para as aplicações da Conta Comigo Digital. Oferece suporte para logs de APIs, Lambdas e outros serviços, com integração ao AWS CloudWatch e suporte a JSON para SIEMs.
Author-email: Iago Santana <iago.gomes@contacomigo.digital>
License: MIT
Keywords: logging,structured-logging,json-logger,siem,lambda,django
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-json-logger>=3.3.0
Requires-Dist: typing-extensions>=4.12.0
Dynamic: license-file

# CCD Logger

Biblioteca de **logging estruturado em formato JSON** para as aplicações da fintech **Conta Comigo Digital**.  
Compatível com `Django`, `AWS Lambda` e scripts genéricos, com foco em integração com **SIEMs** e observabilidade.

---

## Instalação

```bash
pip install ccd-logger
```

Ou diretamente do GitHub:

```bash
pip install git+https://git@github.com/conta-comigo/ccd-logger.git
```

---

## Configuração

O logger é configurado via variáveis de ambiente:

| Variável | Padrão | Descrição |
|---|---|---|
| `SERVICE_NAME` | `undefined-service` | Nome do serviço que aparece em todos os logs |
| `ENVIRONMENT` | `dev` | Ambiente (`dev`, `staging`, `prod`) |
| `LOG_LEVEL` | `INFO` | Nível de log (`DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`) |
| `LOG_FORMAT` | `json` | Formato de saída: `json` para produção, qualquer outro valor para texto simples |

---

## Uso básico

```python
from ccd_logger import get_logger

logger = get_logger(__name__)

logger.info("Operação concluída")
logger.error("Falha ao processar", extra={"cpf": "12345678900"})
```

Saída JSON:

```json
{
  "asctime": "2024-01-01 12:00:00,000",
  "levelname": "INFO",
  "name": "meu_modulo",
  "message": "Operação concluída",
  "service": "undefined-service",
  "environment": "dev",
  "filename": "meu_modulo.py",
  "lineno": 5,
  "funcName": "main"
}
```

---

## Contextos disponíveis

### Generic (padrão)

Para scripts e serviços sem framework específico. Veja o exemplo completo em [ccd_logger/samples/generic_logger.py](ccd_logger/samples/generic_logger.py).

### Lambda

Injeta automaticamente campos do contexto do Lambda (`function_name`, `memory_limit_in_mb`, `request_id`) em todos os logs da execução.

```python
logger = get_logger(__name__, context="lambda", context_data=context)
```

#### `structure_logs`

Permite adicionar campos persistentes e serializar dados complexos para todos os logs subsequentes:

```python
logger.structure_logs(
    append=True,           # False para resetar campos extras antes de adicionar
    data=meu_dict,         # kwargs são adicionados como campos extras em todos os logs
    serializer=json.dumps  # aplicado a valores dict/list antes de armazenar
)
logger.info("Processamento concluído")
# {"message": "Processamento concluído", "data": "{\"chave\": \"valor\"}", ...}
```

Veja o exemplo completo em [ccd_logger/samples/lambda_logger.py](ccd_logger/samples/lambda_logger.py).

### Django

Prepara campos específicos de requests HTTP (`path`, `method`, `status_code`, `response_time`, `user`, `user_agent`, `user_ip`).

```python
logger = get_logger(__name__, context="django")
```

Veja o exemplo completo em [ccd_logger/samples/django_logger.py](ccd_logger/samples/django_logger.py).

---

## Campos comuns em todos os logs

Independente do contexto, todo log inclui:

| Campo | Descrição |
|---|---|
| `asctime` | Timestamp do log |
| `levelname` | Nível (`INFO`, `ERROR`, etc.) |
| `name` | Nome do logger |
| `message` | Mensagem |
| `service` | Valor de `SERVICE_NAME` |
| `environment` | Valor de `ENVIRONMENT` |
| `filename` | Arquivo de origem do log |
| `lineno` | Linha de origem do log |
| `funcName` | Função/método de origem do log |
