---
name: setup_logger
kind: function
lang: py
domain: infra
version: "1.0.0"
purity: impure
signature: "def setup_logger(name: str = 'app', log_dir: str = 'logs', level: int = logging.DEBUG) -> logging.Logger"
description: "Configura un logger con dual output: archivo con rotacion por tamano (DEBUG+, 10MB, 5 backups) y consola (INFO+). Crea log_dir si no existe. Idempotente: no duplica handlers si el logger ya esta configurado."
tags: [logging, logger, rotation, file, console, infra, debug]
uses_functions: []
uses_types: []
returns: []
returns_optional: false
error_type: "error_go_core"
imports: [logging, logging.handlers, os, sys, datetime]
params:
  - name: name
    desc: "nombre del logger a configurar"
  - name: log_dir
    desc: "directorio donde guardar archivos de log (defecto 'logs')"
  - name: level
    desc: "nivel de logging (defecto logging.DEBUG)"
output: "instancia logging.Logger configurada con handlers de archivo y consola"
tested: true
tests:
  - "logger se crea con 2 handlers"
  - "segundo call no duplica handlers"
  - "archivo se crea en log_dir"
  - "get_logger retorna logger configurado"
  - "logger level es debug"
test_file_path: "python/functions/infra/setup_logger_test.py"
file_path: "python/functions/infra/setup_logger.py"
---

## Ejemplo

```python
from setup_logger import setup_logger, get_logger

# Configurar al inicio de la aplicacion
logger = setup_logger(name="mi_app", log_dir="logs", level=logging.DEBUG)
logger.info("Aplicacion iniciada")
logger.debug("Detalle de debug")

# En modulos internos: obtener logger ya configurado
log = get_logger("mi_app")
log.warning("Algo inesperado ocurrio")
```

## Notas

Funcion impura: crea el directorio `log_dir` en disco y modifica el estado global del sistema de logging de Python.

El archivo de log tiene nombre `YYYY-MM-DD.log` segun la fecha de inicio. La rotacion es por tamano (10 MB), no por tiempo — por eso el nombre es fijo para cada dia de inicio de la aplicacion.

En Windows se reconfigura `sys.stdout` a UTF-8 para evitar mojibake con caracteres no-ASCII.

La funcion companion `get_logger` es util en modulos que no controlan la inicializacion: devuelve el logger si ya fue configurado, o lo crea con defaults.