@gatewaystack/explicabl

Explicabl is GatewayStack’s explainability & audit layer.
It emits a structured JSON event for every request flowing through the GatewayStack pipeline, enabling:

• request-level audit trails
• debugging & developer visibility
• future SIEM / OTEL / Cloud Logging sinks
• full traceability across Identifiabl → Proxyabl → Explicabl

This is the MVP implementation, focused on being simple, predictable, and production-safe.

Features

• Single structured JSON event per request
• Includes HTTP metadata (method, path, status, latency), request ID, and context (identity, routing, limits)
• Safe — logging failures never break responses
• Zero dependencies beyond Express
• Pluggable logger function with built-in console logger (createConsoleLogger)
• Compatible with @gatewaystack/request-context, @gatewaystack/identifiabl, @gatewaystack/proxyabl

Installation

npm install @gatewaystack/explicabl

Quick Start

1. Create a logger

import { createConsoleLogger } from "@gatewaystack/explicabl";

const logger = createConsoleLogger({
  serviceName: "gateway-server",
  environment: process.env.NODE_ENV,
});

2. Add the middleware after you create request context

import { explicablLoggingMiddleware } from "@gatewaystack/explicabl";

app.use(explicablLoggingMiddleware(logger));

Explicabl will now emit one event for every request:

[explicabl] {"ts":"2025-01-01T00:00:00.000Z","kind":"gateway.request", ...}

API

createConsoleLogger(config)

Creates a logger that writes one JSON line per event to stdout.

const logger = createConsoleLogger({
  serviceName?: string;
  environment?: string;
});

explicablLoggingMiddleware(logger)

Express middleware that emits one ExplicablEvent after every response.

app.use(explicablLoggingMiddleware(logger));

explicablRouter(env)

Optional router that exposes:

• /health endpoints
• /webhooks/auth0 for ingesting Auth0 log events

app.use("/explicabl", explicablRouter(process.env));

Event Format (ExplicablEvent)

interface ExplicablEvent {
  ts: string;               // timestamp
  kind: "gateway.request";
  serviceName?: string;
  environment?: string;
  requestId?: string;

  http: {
    method: string;
    path: string;
    status: number;
    latencyMs?: number;
  };

  context?: unknown; // identity, authz, limits, routing...
}

Future versions will expand this with:

• token usage
• policy decisions
• rate-limit metadata
• model/tool routing info
• richer sinks (OTEL, Cloud Logging, ClickHouse, etc.)

Testing

Explicabl ships with full unit tests:

• logger enrichment
• middleware events
• error handling
• context propagation

Run:

npm test

Roadmap

• explicabl-core package with shared event schema (non-Express)
• OTEL/trace/span support
• Token usage + cost attribution
• Policy explainability integration (Validatabl)
• ClickHouse / BigQuery / Cloud Logging sinks
• GatewayStack UI integration for audit trails
• “Replay this request” developer tools

License

MIT © GatewayStack