Observabilidad en Fintech: Logging Estructurado y Métricas OpenTelemetry en PHP 8.4

por

Descargo de responsabilidad: Este artículo es material educativo de ingeniería de confiabilidad aplicada a entornos financieros. Las estrategias de observabilidad presentadas deben validarse con volúmenes de datos representativos antes de aplicarse en producción. El monitoreo mal configurado puede generar costos excesivos o falsos positivos que fatigan al equipo operativo. El uso de este contenido es bajo exclusiva responsabilidad del SRE u operador del sistema.

1. Por Qué el Monitoreo Tradicional Falla en Fintech

El monitoreo clásico (CPU, memoria, disco lleno) detecta problemas de infraestructura, pero no problemas de negocio financiero. Un servidor puede estar al 20% CPU mientras pierde silenciosamente transacciones por timeouts en APIs externas, errores de parsing en webhooks o lógica de idempotencia defectuosa. En fintech, necesitas saber si el sistema está generando dinero correctamente, no solo si está encendido.

La observabilidad moderna se basa en tres pilares interdependientes: logs estructurados (qué pasó), métricas (tendencias y patrones) y trazas distribuidas (dónde y por qué falló una request específica). Implementar estos tres pilares en PHP 8.4 sin introducir agentes pesados ni dependencias externas masivas es posible con OpenTelemetry nativo y logging JSON estandarizado.

2. Logging Estructurado: De Texto Plano a Datos Consultables

Logs en formato texto plano ([ERROR] Payment failed for user 123) son inútiles a escala. No se pueden filtrar, agregar ni correlacionar automáticamente. En fintech, todo log debe ser JSON estructurado con campos estandarizados que permitan consultas tipo SQL sobre eventos de negocio.

<?php
declare(strict_types=1);

namespace App\Observability;

use JsonException;

class StructuredLogger 
{
    private string $service;
    private string $environment;
    private ?string $requestId;

    public function __construct(string $service, string $environment = 'production') 
    {
        $this->service = $service;
        $this->environment = $environment;
        // Propagar Request ID desde header entrante o generar nuevo
        $this->requestId = $_SERVER['HTTP_X_REQUEST_ID'] 
                           ?? bin2hex(random_bytes(8));
    }

    /**
     * Log estructurado JSON con contexto financiero
     */
    public function log(string $level, string $message, array $context = []): void 
    {
        $entry = [
            'timestamp'   => date('c'),
            'level'       => strtoupper($level),
            'service'     => $this->service,
            'environment' => $this->environment,
            'request_id'  => $this->requestId,
            'message'     => $message,
            // Campos financieros estandarizados
            'merchant_id' => $context['merchant_id'] ?? null,
            'transaction_id' => $context['transaction_id'] ?? null,
            'amount_cents'   => $context['amount_cents'] ?? null,
            'currency'       => $context['currency'] ?? null,
            'error_code'     => $context['error_code'] ?? null,
            'duration_ms'    => $context['duration_ms'] ?? null,
            // Metadata adicional (sanitizada)
            'extra' => $this->sanitize($context['extra'] ?? [])
        ];

        try {
            $json = json_encode($entry, JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES);
            error_log($json); // stdout/stderr → capturado por orquestador
        } catch (JsonException $e) {
            error_log(json_encode([
                'timestamp' => date('c'),
                'level' => 'ERROR',
                'message' => 'LOG_SERIALIZATION_FAILED',
                'error' => $e->getMessage()
            ]));
        }
    }

    /**
     * Sanitizar datos sensibles ANTES de loguear
     */
    private function sanitize(array $data): array 
    {
        $sensitiveKeys = ['password', 'secret', 'token', 'cvv', 'pan', 'card_number', 'api_key'];
        
        array_walk_recursive($data, function (&$value, $key) use ($sensitiveKeys) {
            if (is_string($key) && in_array(strtolower($key), $sensitiveKeys, true)) {
                $value = '[REDACTED]';
            }
        });
        
        return $data;
    }

    // Métodos convenience
    public function info(string $msg, array $ctx = []): void { $this->log('info', $msg, $ctx); }
    public function warn(string $msg, array $ctx = []): void { $this->log('warn', $msg, $ctx); }
    public function error(string $msg, array $ctx = []): void { $this->log('error', $msg, $ctx); }
}
Campo EstandarizadoTipoPropósito en Auditoría Financiera
request_idUUIDCorrelacionar logs a través de múltiples servicios/microservicios
merchant_idStringFiltrar eventos por cliente para soporte y auditoría
transaction_idStringRastrear ciclo de vida completo de una transacción
amount_centsIntegerAgregaciones monetarias sin errores de punto flotante
error_codeStringClasificación de fallos para alertas y SLAs
duration_msIntegerDetección de degradación de rendimiento progresiva

3. OpenTelemetry en PHP 8.4: Trazas Sin Overhead

OpenTelemetry (OTel) es el estándar abierto para instrumentación. En PHP 8.4, la extensión opentelemetry permite auto-instrumentación de frameworks y librerías comunes (PDO, cURL, Redis) con overhead <3% en producción. Para fintech, esto significa visibilidad completa de cadenas de requests sin modificar código de negocio.

# Instalación extensión OTel para PHP 8.4 (Alpine/Docker)
RUN apk add --no-cache $PHPIZE_DEPS protobuf-c-dev \
    && pecl install opentelemetry \
    && docker-php-ext-enable opentelemetry

# Configuración vía variables de entorno (no código)
ENV OTEL_SERVICE_NAME=payment-api
ENV OTEL_EXPORTER_OTLP_ENDPOINT=https://otel-collector.internal:4318
ENV OTEL_TRACES_EXPORTER=otlp
ENV OTEL_METRICS_EXPORTER=otlp
ENV OTEL_LOGS_EXPORTER=otlp
ENV OTEL_PROPAGATORS=tracecontext,baggage
ENV OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production,service.version=2026.10.15

# Auto-instrumentación PDO/cURL/Redis (sin modificar código app)
ENV OTEL_PHP_AUTO_INSTRUMENTATION=pdo,curl,redis

La auto-instrumentación captura automáticamente: queries SQL (con parámetros sanitizados), llamadas HTTP outbound (status, duración), operaciones Redis (comando, clave). Para operaciones de negocio específicas (procesar pago, validar webhook), crea spans manuales:

<?php
use OpenTelemetry\API\Globals;
use OpenTelemetry\API\Trace\SpanKind;

$tracer = Globals::tracerProvider()->getTracer('payment-service');

$span = $tracer->spanBuilder('process_payment')
    ->setSpanKind(SpanKind::KIND_SERVER)
    ->setAttribute('merchant.id', $merchantId)
    ->setAttribute('payment.amount_cents', $amountCents)
    ->setAttribute('payment.currency', $currency)
    ->startSpan();

try {
    // Lógica de negocio...
    $result = $paymentGateway->charge($amountCents, $currency);
    
    $span->setAttribute('payment.status', $result['status']);
    $span->setAttribute('payment.gateway_response_time_ms', $result['latency_ms']);
    $span->setStatus(\OpenTelemetry\API\Trace\StatusCode::STATUS_OK);
    
} catch (\Throwable $e) {
    $span->recordException($e);
    $span->setStatus(\OpenTelemetry\API\Trace\StatusCode::STATUS_ERROR, $e->getMessage());
    throw $e;
} finally {
    $span->end();
}

4. Métricas RED y USE: Lo Que Realmente Importa

Métricas genéricas (CPU, RAM) no predicen fallos de negocio. En fintech, usa dos modelos complementarios:

  • RED (para servicios/APIs): Rate (requests/s), Errors (tasa de error %), Duration (latencia P50/P95/P99). Alerta cuando Error Rate >1% o P99 >SLA definido.
  • USE (para infraestructura): Utilization (% capacidad usada), Saturation (cola/trabajo pendiente), Errors (fallos de recurso). Alerta cuando Saturation >80% sostenido.
<?php
// Exportar métricas RED vía OTel Metrics API
$meter = Globals::meterProvider()->getMeter('payment-api');

// Counter: total requests por endpoint y status
$requestCounter = $meter->createCounter(
    'http.server.request.count',
    'requests',
    'Total HTTP requests processed'
);

// Histogram: latencia de requests
$latencyHistogram = $meter->createHistogram(
    'http.server.request.duration',
    'ms',
    'Request processing duration',
    advice: ['ExplicitBucketBoundaries' => [5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000]]
);

// Uso en middleware post-response
register_shutdown_function(function () use ($requestCounter, $latencyHistogram) {
    $duration = (microtime(true) - $_SERVER['REQUEST_TIME_FLOAT']) * 1000;
    $attributes = [
        'http.method' => $_SERVER['REQUEST_METHOD'],
        'http.route' => $_SERVER['REQUEST_URI'],
        'http.status_code' => http_response_code()
    ];
    
    $requestCounter->add(1, $attributes);
    $latencyHistogram->record($duration, $attributes);
});

5. Correlación: Unir Logs, Métricas y Trazas

Los tres pilares son inútiles si no están correlacionados. La clave es propagar trace_id y span_id en cada log entry y etiqueta de métrica:

  • Logs → Trazas: Incluir trace_id y span_id en cada entrada JSON. Al ver un error en logs, clickear trace_id lleva directamente al span en Jaeger/Tempo.
  • Métricas → Trazas: Etiquetar histogramas con trace_id sampleado. Cuando P99 sube, examinar trazas de requests lentas para identificar bottleneck.
  • Trazas → Logs: Desde UI de tracing, ver todos los logs asociados a un span específico. Contexto completo sin grep manual.

En PHP 8.4 + OTel, esta correlación es automática si usas la extensión y el logger estructurado mostrado arriba. El request_id del logger se mapea a trace_id de OTel mediante propagadores W3C TraceContext.

6. Costos y Retención: Evitar Sorpresas en Factura Cloud

Observabilidad mal dimensionada puede costar más que la propia aplicación. Reglas para fintech LATAM:

  • Sampling adaptativo: 100% de traces para errores y latencia >P95. 1-10% sampling para requests exitosas normales. Reduce volumen 90% sin perder señal de problemas.
  • Retención diferenciada: Métricas agregadas: 1 año. Logs estructurados: 90 días hot + 1 año cold (S3/R2). Traces completas: 7-30 días según regulación local.
  • Cardinalidad controlada: Nunca usar IDs de usuario/transacción como etiquetas de métricas (explosión de series temporales). Usar solo dimensiones de baja cardinalidad: endpoint, status, merchant_tier.
  • Backend open-source: Grafana Stack (Loki + Tempo + Mimir) self-hosted evita vendor lock-in y costos impredecibles de Datadog/NewRelic a escala.

7. Conclusión y Recursos Oficiales

La observabilidad en fintech no es lujo: es requisito operativo y regulatorio. Logging estructurado JSON, trazas OpenTelemetry y métricas RED/USE forman el sistema nervioso que permite detectar anomalías financieras antes de que impacten clientes o generen pérdidas. Implementar estos pilares en PHP 8.4 con overhead mínimo es viable usando estándares abiertos y evitando dependencias propietarias.

Referencias oficiales:

Nota técnica: Este artículo utiliza marcado Schema.org Article coexistente con el nodo FinancialService corporativo. Los metadatos semánticos se indexan automáticamente vía The SEO Framework.

Deja un comentario