Structured Logging — esencia, formatos de datos y principio de funcionamiento en aplicaciones

Qué es Structured Logging

Structured Logging es un método de registro de logs en el que cada mensaje contiene campos con nombre y valores tipados. En lugar de una cadena como User 42 logged in from device ABC, un log estructurado se ve como un conjunto de campos: user_id=42, event=login, device_id=ABC, timestamp=2026-07-04T10:30:00Z.

La principal ventaja de los logs estructurados sobre los textuales es la capacidad de procesamiento programático. Analizar logs textuales requiere expresiones regulares y suposiciones sobre el formato de la cadena. Los logs estructurados se analizan sin pérdidas: cada campo tiene un tipo y nombre conocidos, lo que permite construir consultas como encontrar todos los errores de autenticación de la última hora para el usuario 42 sin procesamiento adicional.

Según Honeycomb.io (2023), los equipos que usan structured logging en producción detectan incidentes en promedio 4 veces más rápido en comparación con los equipos que dependen de logs textuales y grep.

Formatos de logs estructurados

Structured Logging admite varios formatos de serialización. La elección del formato depende de la infraestructura: JSON es conveniente para la integración con Elasticsearch y sistemas en la nube, logfmt para visualización en consola mediante tail y grep, Protocol Buffers para sistemas de alto rendimiento con limitaciones de ancho de banda.

JSON — formato universal

JSON es el formato más común para logs estructurados. Es compatible de forma nativa con todos los sistemas de recopilación: Logstash, Fluentd, Amazon CloudWatch, Google Cloud Logging. Los logs JSON son fáciles de leer por humanos y de analizar por cualquier lenguaje de programación sin bibliotecas adicionales. El principal inconveniente es la verbosidad: cada par clave-valor requiere comillas y dos puntos, lo que aumenta el volumen de datos almacenados en un 30–50% en comparación con logfmt.

Logfmt — formato compacto

Logfmt fue desarrollado en Heroku para visibilidad en consola. Es más compacto que JSON, conserva la legibilidad humana y se puede procesar fácilmente con cut y awk. Ejemplo: ts=2026-07-04T10:30:00Z level=error module=api status=500. Logfmt no requiere escape de la mayoría de los caracteres y es adecuado para el logging en stdout en contenedores.

Por qué necesitas Structured Logging en desarrollo móvil

En aplicaciones móviles, Structured Logging resuelve tres problemas clave: encontrar causas de fallos sin reproducirlos en un dispositivo, rastrear sesiones de usuario y analizar el rendimiento por versiones de la aplicación.

Los logs textuales en dispositivos móviles son casi inútiles — un desarrollador no puede aplicar grep a los logs en el dispositivo del usuario. Los logs estructurados se envían a sistemas en la nube (Firebase, Sentry, Datadog) y se indexan allí. Se puede construir una consulta como mostrar todos los crashes con iOS 17.4, versión de la app 3.2, en el módulo de pagos y obtener una selección precisa en segundos.

Según Sentry (2024), las aplicaciones que usan breadcrumbs estructurados tienen un 60% más de contexto en cada informe de crash en comparación con las aplicaciones que registran solo el texto del error. Esto afecta directamente a la velocidad de corrección de errores.

Herramientas de recopilación y análisis

ELK Stack — Elasticsearch, Logstash, Kibana — sigue siendo la infraestructura estándar para trabajar con logs estructurados. Logstash recibe logs en JSON, los transforma y los envía a Elasticsearch para indexación, Kibana proporciona una interfaz visual para consultas y paneles.

Para aplicaciones móviles, las soluciones en la nube son populares: Firebase Crashlytics con logs personalizados, Sentry con breadcrumbs, Datadog con seguimiento APM. Aceptan logs estructurados directamente del SDK móvil y no requieren implementar un backend propio. Firebase ofrece un paquete gratuito para informes de crashes, Sentry añade trazado distribuido y Datadog se integra con APM para rastrear el rendimiento de las solicitudes tanto en el cliente como en el servidor simultáneamente.

Grafana Loki — una alternativa a Elasticsearch optimizada para logs. Loki no indexa el contenido de los mensajes por defecto, sino que utiliza etiquetas (labels) para el filtrado. Esto es significativamente más barato de almacenar y más rápido para consultas sobre un conjunto fijo de campos.

// Logging estructurado a través de Swift Logger en JSON
struct StructuredLog {
    let event: String
    let attributes: [String: Any]
    let level: String

    func serialize() -> String {
        var base = "event=\(event) level=\(level)"
        for (key, value) in attributes {
            base += " \(key)=\(value)"
        }
        return base
    }
}

Mejores prácticas de Structured Logging

La primera regla del logging estructurado: cada mensaje debe contener un identificador de solicitud o sesión. Sin contexto, un log individual es inútil — es imposible saber a qué usuario o solicitud pertenece. Añade un correlation ID al inicio de la sesión y pásalo a través de todas las capas de la aplicación.

La segunda regla: tipado de campos. Los campos numéricos (duration_ms, status_code, retry_count) deben enviarse como números, no como cadenas. Elasticsearch y sistemas similares indexan números y cadenas de forma diferente: los números pueden agregarse (promedio, mediana, percentil), las cadenas admiten búsqueda de texto completo. Un tipado incorrecto impide construir paneles analíticos.

La tercera regla: evita objetos anidados. Los logs JSON con una profundidad de anidamiento superior a 2 niveles son difíciles de filtrar y visualizar. En lugar de {"user": {"name": "Alice", "role": "admin"}}, usa claves planas: user_name=Alice user_role=admin.

// Logging estructurado en Android mediante Timber + logfmt
class StructuredTree : Timber.Tree() {
    override fun log(priority: Int, tag: String?,
                  message: String?, t: Throwable?) {
        val level = priorityToLevel(priority)
        val logfmt = "level=$level tag=$tag message=$message"
        sendToRemote(logfmt)
    }
}

Campos obligatorios

El conjunto mínimo de campos para cada mensaje estructurado: timestamp en ISO 8601, level (debug/info/warn/error/fatal), logger (nombre del módulo o clase), message (descripción legible del evento). Adicionalmente: correlation_id, user_id (si se conoce), version (versión de la app), platform (iOS/Android), environment (dev/staging/prod).

Sin correlation_id, los logs estructurados se convierten en un conjunto de registros inconexos que no pueden vincularse en un escenario de usuario único. Genera un UUID en cada inicio de la aplicación y añádelo a todos los logs de la sesión. En la práctica, el correlation_id debe transmitirse a través de todas las capas: desde eventos de UI hasta solicitudes de red y tareas en segundo plano — de lo contrario, algunos logs se quedarán sin contexto y no participarán en el análisis. Con el seguimiento de extremo a extremo, un solo UUID permite recopilar la imagen completa del recorrido del usuario.

Ejemplos de logging estructurado en Swift y Kotlin

En iOS, el logging estructurado se puede implementar mediante un envoltorio sobre os_log que serializa los campos en formato logfmt. En Android, mediante Timber con un Tree personalizado que convierte los mensajes a JSON o logfmt antes de enviarlos al servidor.

import OSLog

struct StructuredLogger {
    let subsystem: String
    let category: String

    func log(level: OSLogType,
              event: String,
              context: [String: Any]) {
        let oslogger = Logger(
            subsystem: subsystem,
            category: category
        )
        let fields = context.map {
            "\($0.key)=\($0.value)"
        }.joined(separator: " ")
        oslogger.log(level: level,
                     "\(event) \(fields)")
    }
}

Structured vs Unstructured: comparación de enfoques

La elección entre logs estructurados y textuales depende de la etapa del proyecto. En las primeras fases del desarrollo, los logs textuales son más simples y rápidos — el desarrollador escribe un mensaje directamente sin envoltorios adicionales. Pero una vez que el proyecto supera los límites de un solo equipo o servidor, los logs estructurados se vuelven obligatorios.