ECS Winston Format

@elastic/ecs-winston-format is a formatter for the winston logging library that transforms your Node.js application logs into structured JSON conforming to the Elastic Common Schema (ECS). It plugs into winston as a format, so existing logger.info() / logger.error() calls automatically produce ECS-compliant records with a consistent field taxonomy.

Combined with filebeat, these logs can be shipped straight to Elasticsearch and explored in Kibana’s Logs app. The formatter also detects a running Elastic APM agent and injects trace, transaction, and service correlation fields, letting you pivot between logs and traces for the same request.

What You Get

• A drop-in winston format (ecsFormat) that produces ECS-compliant JSON with no changes to your log call sites
• Automatic conversion of err, req, and res fields into ECS error, HTTP, URL, and user-agent fields
• Built-in Elastic APM integration that injects trace.id, transaction.id, span.id, and service.* correlation fields
• TypeScript type declarations for the formatter and its configuration options
• Composable ecsFields and ecsStringify formats for building custom winston format pipelines

Common Use Cases

• Shipping structured Node.js logs to Elasticsearch via filebeat for centralized search in Kibana
• Correlating application logs with distributed traces captured by the Elastic APM agent
• Standardizing log field names across microservices using the Elastic Common Schema
• Adding ECS-compliant HTTP request/response logging to Express and other Node.js servers

Under The Hood

Architecture - The formatter is implemented in packages/ecs-winston-format/index.js as a winston-compatible transform. It reads winston’s LEVEL, MESSAGE, and SPLAT symbols from triple-beam, restructures each info object into the ECS field layout, delegates HTTP and error field mapping to @elastic/ecs-helpers, and serializes with safe-stable-stringify. The public API composes as three winston formats: ecsFields (the field transform), ecsStringify (the serializer), and ecsFormat (the combined convenience format).

Tech Stack - Pure JavaScript targeting Node.js >=10 with no build step. Runtime dependencies are minimal: @elastic/ecs-helpers for shared field mapping, safe-stable-stringify for deterministic JSON, and triple-beam for winston’s symbols. It optionally requires elastic-apm-node at runtime for trace correlation, loaded defensively in a try/catch. Development uses tap for tests, standard for linting, and test-all-versions for compatibility matrices.

Code Quality - The package ships a focused test suite (basic, errors, and apm test files) run under tap, hand-written TypeScript declarations in index.d.ts, and enforces the standard style guide. Error handling is deliberate, with special-cased logic for winston’s several ways of passing Error objects, and the optional APM dependency is wrapped so its absence never throws.

API Design - The developer experience is intentionally minimal: install, import ecsFormat, and pass it as the winston format. A single options object toggles error conversion, HTTP req/res conversion, and APM integration, with sensible defaults. Documentation is strong, backed by both a package README with runnable examples and Elastic’s dedicated ECS logging docs site.