ccd-logger 0.2.0

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.

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

pip install ccd-logger

Ou diretamente do GitHub:

pip install git+https://[e-mail]/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

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:

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

Lambda

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

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

structure_logs

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

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.

Django

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

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

Veja o exemplo completo em 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