@alex-michaud/pino-graylog-transport 1.0.2

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Alexandre Michaud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,489 @@
+# pino-graylog-transport
+
+A Pino transport module that sends log messages to Graylog using the GELF (Graylog Extended Log Format) protocol over TCP, TLS, or UDP.
+
+## Features
+
+- 🚀 Full support for Pino transports API
+- 📦 GELF (Graylog Extended Log Format) message formatting
+- 🔒 TLS, TCP, and UDP protocol support (TLS secure by default)
+- 🔧 Configurable facility, host, and port
+- 📊 Automatic log level conversion (Pino → Syslog)
+- 🏷️ Custom field support with GELF underscore prefix
+- ⚡ High-performance async message sending with buffering and reconnection logic
+
+## Installation
+
+```bash
+npm install @alex-michaud/pino-graylog-transport pino
+```
+
+## Publishing & Installation
+
+This package is published under the scope `@alex-michaud`. To install, use the following command:
+
+```bash
+npm install @alex-michaud/pino-graylog-transport
+```
+
+If you encounter permissions issues, you may need to add `--access public` to the install command:
+
+```bash
+npm install @alex-michaud/pino-graylog-transport --access public
+```
+
+## Quick Start
+
+```javascript
+const pino = require('pino');
+const transport = require('@alex-michaud/pino-graylog-transport');
+
+const transportInstance = transport({
+  host: 'graylog.example.com',
+  port: 12201,
+  // TLS is the default for secure transmission over networks
+  // Use protocol: 'tcp' only for local development (localhost)
+  protocol: 'tls',
+  facility: 'my-app',
+  staticMeta: {
+    environment: 'production',
+    service: 'api',
+    version: '1.0.0'
+  }
+});
+
+const logger = pino(transportInstance);
+
+logger.info('Hello Graylog!');
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `host` | string | `'localhost'` | Graylog server hostname |
+| `port` | number | `12201` | Graylog GELF input port (standard GELF TCP port) |
+| `protocol` | string | `'tls'` | Protocol to use (`'tcp'`, `'tls'`, or `'udp'`). **Default is `'tls'` for security** - uses encrypted connection to prevent exposure of sensitive data. Use `'tcp'` only for local development. Use `'udp'` for high-throughput scenarios where delivery guarantees are not required. |
+| `facility` | string | `hostname` | **Application/service identifier** sent with every message. Used to categorize logs by application in Graylog (e.g., `'api-gateway'`, `'auth-service'`). Sent as `_facility` additional field per [GELF spec](https://go2docs.graylog.org/current/getting_in_log_data/gelf.html). |
+| `hostname` | string | `os.hostname()` | Host field in GELF messages (the machine/server name) |
+| `staticMeta` | object | `{}` | Static fields included in **every** log message (e.g., auth tokens, environment, datacenter). These are sent as GELF custom fields with underscore prefix. |
+| `maxQueueSize` | number | `1000` | Max messages to queue when disconnected |
+| `onError` | function | `console.error` | Custom error handler |
+| `onReady` | function | `undefined` | Callback when connection is established |
+| `autoConnect` | boolean | `true` | If `false`, don't establish connection on initialization. Only applies to TCP/TLS; UDP always initializes immediately since it's connectionless. |
+
+### ⚠️ Security Note
+
+The default protocol is **`tls`** to ensure logs are transmitted securely over encrypted connections. This is important when:
+- Sending logs over untrusted networks (internet, shared corporate networks)
+- Including authentication tokens in `staticMeta` (e.g., `'X-OVH-TOKEN'`)
+- Logging sensitive data (PII, API keys, internal URLs)
+
+Only use `protocol: 'tcp'` for local development when Graylog is running on `localhost`.
+
+## Using with Authentication Tokens
+
+Some Graylog services require authentication tokens to be sent with every log message. Use `staticMeta` to include these tokens and any other metadata that should be sent with **all** log messages:
+
+```javascript
+const transport = require('@alex-michaud/pino-graylog-transport');
+
+// Example: OVH Logs Data Platform
+const stream = transport({
+  host: 'bhs1.logs.ovh.com',
+  port: 12202,
+  protocol: 'tls',
+  staticMeta: {
+    'X-OVH-TOKEN': 'your-ovh-token-here'
+  }
+});
+
+// Example: Generic cloud provider with token
+const stream = transport({
+  host: 'graylog.example.com',
+  port: 12201,
+  protocol: 'tls',
+  staticMeta: {
+    token: 'your-auth-token',
+    environment: 'production',
+    datacenter: 'us-east-1'
+  }
+});
+```
+
+All fields in `staticMeta` will be included in every GELF message with an underscore prefix (e.g., `_X-OVH-TOKEN`, `_token`, `_environment`).
+
+## Understanding Configuration Fields
+
+### `facility` vs `hostname` vs `staticMeta`
+
+These three configuration options serve different purposes:
+
+| Field | Purpose | Example | GELF Field | When to Use |
+|-------|---------|---------|------------|-------------|
+| `facility` | **Application/service identifier** | `'api-gateway'`, `'auth-service'` | `_facility` | Identify which application/microservice sent the log |
+| `hostname` | **Machine/server identifier** | `'web-server-01'`, `'us-east-1a'` | `host` | Identify which machine/container/pod sent the log |
+| `staticMeta` | **Context metadata** | `{ token: 'abc', env: 'prod' }` | `_token`, `_env` | Add authentication tokens or contextual info |
+
+### Example: Microservices Architecture
+
+```javascript
+// API Gateway service running on server 1
+transport({
+  facility: 'api-gateway',        // What service?
+  hostname: 'web-server-01',      // Which machine?
+  staticMeta: {
+    environment: 'production',    // Extra context
+    region: 'us-east-1',
+    version: '2.1.0'
+  }
+});
+
+// Auth Service running on server 2
+transport({
+  facility: 'auth-service',       // What service?
+  hostname: 'web-server-02',      // Which machine?
+  staticMeta: {
+    environment: 'production',
+    region: 'us-east-1',
+    version: '1.5.3'
+  }
+});
+```
+
+In Graylog, you can then:
+- Filter by `_facility:api-gateway` to see all API gateway logs
+- Filter by `host:web-server-01` to see all logs from that server
+- Filter by `_environment:production` to see production logs across all services
+
+## Local Development with Docker
+
+This repository includes a Docker Compose configuration to run Graylog locally for testing.
+
+### Start Graylog
+
+```bash
+npm run docker:up
+# or
+docker compose up -d
+```
+
+Wait about 30 seconds for Graylog to fully start, then run the setup script to create the GELF inputs:
+
+```bash
+npm run docker:setup
+```
+
+Then access the web interface at:
+- URL: http://localhost:9005
+- Username: `admin`
+- Password: `admin`
+
+### Stop Graylog
+
+```bash
+npm run docker:down
+# or
+docker compose down
+```
+
+## Usage Examples
+
+### Basic Logging
+
+```javascript
+const pino = require('pino');
+const transport = require('@alex-michaud/pino-graylog-transport');
+
+// For local development (localhost)
+const logger = pino(transport({
+  host: 'localhost',
+  port: 12201,
+  protocol: 'tcp'  // Safe to use TCP for localhost
+}));
+
+logger.info('Application started');
+logger.warn('Warning message');
+logger.error('Error message');
+```
+
+### Logging with Custom Fields
+
+```javascript
+logger.info({
+  userId: 123,
+  action: 'login',
+  ip: '192.168.1.1'
+}, 'User logged in');
+
+// In Graylog, these will appear as: _userId, _action, _ip
+```
+
+### Error Logging with Stack Traces
+
+```javascript
+try {
+  throw new Error('Something went wrong!');
+} catch (err) {
+  logger.error({ err }, 'An error occurred');
+  // Stack trace will be sent as full_message in GELF
+}
+```
+
+### TCP Protocol
+
+```javascript
+const logger = pino(await transport({
+  host: 'localhost',
+  port: 12201,
+  protocol: 'tcp'  // Use TCP instead of TLS
+}));
+```
+
+### UDP Protocol
+
+```javascript
+const logger = pino(await transport({
+  host: 'localhost',
+  port: 12201,
+  protocol: 'udp'  // Use UDP for high-throughput, fire-and-forget logging
+}));
+```
+
+**Note:** UDP is connectionless and does not guarantee message delivery. Use it when:
+- You need maximum throughput
+- Occasional message loss is acceptable
+- You're logging to a local Graylog instance
+- Network reliability is high
+
+**UDP Limitations:**
+- Messages are limited to **8KB (8192 bytes)** per GELF UDP specification
+- Messages exceeding this size are **rejected** (not sent)
+- For large messages, use TCP or TLS protocols instead
+- No delivery guarantees (fire-and-forget)
+
+**Bun Runtime:** When running under [Bun](https://bun.sh/), the UDP transport automatically uses Bun's native `Bun.udpSocket()` API for better performance. Falls back to Node's `dgram` module if unavailable.
+
+### Run the Example
+
+```bash
+# Start Graylog first
+npm run docker:up
+
+# Run the example (after installing dependencies)
+npm install
+node examples/basic.js
+
+# View logs at http://localhost:9005
+```
+
+## Testing
+
+### Install Dependencies
+
+```bash
+npm install
+```
+
+### Unit Tests
+
+Run the library functionality tests (no external dependencies required):
+
+```bash
+npm test
+# or
+npm run test:unit
+```
+
+### Integration Tests
+
+Integration tests require a running Graylog instance:
+
+```bash
+# Start Graylog first
+npm run docker:up
+npm run docker:setup
+
+# Run integration tests
+npm run test:integration
+```
+
+### Run All Tests
+
+Run both unit and integration tests:
+
+```bash
+npm run test:all
+```
+
+### Load Tests with k6
+
+Load tests use [k6](https://k6.io) to simulate high-volume logging scenarios.
+
+#### Install k6
+
+```bash
+# macOS
+brew install k6
+```
+```bash
+# Linux
+sudo gpg -k
+sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
+echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
+sudo apt-get update
+sudo apt-get install k6
+```
+
+```bash
+# Windows
+choco install k6
+```
+
+#### Run Load Tests
+
+```bash
+# Start Graylog
+npm run docker:up
+
+# Setup Graylog inputs (wait for Graylog to be ready first)
+npm run docker:setup
+
+# Start the load test server
+npm run start:load-server
+
+# In another terminal, run the k6 load test
+npm run test:load
+
+# Or run a quick smoke test (20 seconds)
+npm run test:smoke
+```
+
+The load test will:
+- Ramp up from 0 to 50 virtual users
+- Send thousands of log messages
+- Measure throughput and latency
+- Verify 95% success rate
+
+## Project Structure
+
+```
+pino-graylog-transport/
+├── lib/                    # Source code
+│   ├── index.ts           # Main transport entry point
+│   ├── gelf-formatter.ts  # GELF message formatter
+│   └── graylog-transport.ts # TCP/TLS transport
+├── test/                  # Tests
+│   ├── unit/             # Unit tests
+│   │   ├── gelf-formatter.test.ts
+│   │   ├── graylog-transport.test.ts
+│   │   └── integration.test.ts
+│   ├── load/             # Load tests
+│   │   ├── load-test.ts  # k6 load test script
+│   │   ├── smoke-test.ts # k6 smoke test script
+│   │   └── server.ts     # Test server for load testing
+│   └── benchmark/        # Performance benchmarks
+│       ├── benchmark.ts            # Microbenchmark (formatting)
+│       ├── comparison-server.ts    # Server for pino vs winston test
+│       └── comparison-load-test.ts # k6 comparison load test
+├── examples/             # Usage examples
+│   └── basic.js
+├── docker-compose.yml    # Graylog local setup
+└── package.json
+```
+
+## Log Level Mapping
+
+Pino log levels are automatically converted to Syslog severity levels for Graylog:
+
+| Pino Level | Numeric | Syslog Level | Numeric |
+|------------|---------|--------------|---------|
+| fatal      | 60      | Critical     | 2       |
+| error      | 50      | Error        | 3       |
+| warn       | 40      | Warning      | 4       |
+| info       | 30      | Informational| 6       |
+| debug      | 20      | Debug        | 7       |
+| trace      | 10      | Debug        | 7       |
+
+## GELF Message Format
+
+The transport converts Pino log objects to GELF format:
+
+- `short_message`: The log message
+- `full_message`: Stack trace (if present)
+- `level`: Syslog severity level
+- `timestamp`: Unix timestamp
+- `host`: Hostname
+- `facility`: Application/service name
+- `_*`: Custom fields (all Pino log object properties)
+
+## Performance
+
+The GELF formatting logic is optimized for speed. Benchmarks were run using [mitata](https://github.com/evanwashere/mitata) to measure the overhead of message transformation (excluding network I/O).
+
+### Benchmark Results
+
+| Benchmark | Time | Description |
+|-----------|------|-------------|
+| JSON.stringify (Raw) | 614 ns | Baseline - just serialization, no transformation |
+| **pino-graylog-transport** | **1.87 µs** | Our GELF formatter |
+| Manual GELF Construction | 2.21 µs | Simulated naive implementation |
+
+### Key Takeaways
+
+- ✅ **18% faster** than a naive manual GELF construction approach
+- ✅ **~535,000 messages/second** theoretical formatting throughput (single-threaded)
+- ✅ **Negligible overhead**: The ~1.25 µs formatting overhead is 500-50,000x smaller than typical network latency
+
+### Run Benchmarks
+
+```bash
+# Run formatting microbenchmark (no network)
+npm run benchmark
+```
+
+### Comparison Load Test (pino vs winston)
+
+This test compares the real-world performance of `@alex-michaud/pino-graylog-transport` against `winston + winston-log2gelf`:
+
+```bash
+# Start Graylog
+npm run docker:up
+npm run docker:setup
+
+# Start the comparison server (in one terminal)
+npm run start:comparison-server
+
+# Run the comparison load test (in another terminal)
+npm run benchmark:load
+```
+
+The test runs three scenarios in parallel:
+- **Baseline**: No logging (measures pure HTTP overhead)
+- **Pino**: Using @alex-michaud/pino-graylog-transport
+- **Winston**: Using winston + winston-log2gelf
+
+Compare the `*_duration` metrics to see the logging overhead for each library.
+
+## License
+
+MIT — see the [LICENSE](./LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Requirements
+
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](https://nodejs.org/)
+
+This package requires Node.js >= 22 (declared in package.json `engines`). The CI and release workflows prefer the latest Node LTS. If your local Node version is older, upgrade Node (for example, using nvm):
+
+```bash
+# Install nvm (if not present)
+# https://github.com/nvm-sh/nvm#installing-and-updating
+
+# Use latest LTS
+nvm install --lts
+nvm use --lts
+```

package/dist/gelf-formatter.d.ts

@@ -0,0 +1,11 @@
+export interface GelfMessage {
+    version: '1.1';
+    host: string;
+    short_message: string;
+    full_message?: string;
+    timestamp: number;
+    level: number;
+    [key: string]: unknown;
+}
+export declare const mapPinoLevelToGelf: (pinoLevel: number | undefined) => number;
+export declare function formatGelfMessage(chunk: unknown, hostname: string, facility: string, staticMeta?: Record<string, unknown>): string;

package/dist/gelf-formatter.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapPinoLevelToGelf = void 0;
+exports.formatGelfMessage = formatGelfMessage;
+// OPTIMIZATION: Hoist constant outside the hot path and use Set for O(1) lookup
+const EXCLUDED_FIELDS = new Set([
+    'msg',
+    'message',
+    'level',
+    'time',
+    'pid',
+    'hostname',
+    'stack',
+    'v',
+    'err',
+]);
+const mapPinoLevelToGelf = (pinoLevel) => {
+    // Pino levels: 10 trace, 20 debug, 30 info, 40 warn, 50 error, 60 fatal
+    // GELF levels: 0 emergency, 1 alert, 2 critical, 3 error, 4 warning, 5 notice, 6 info, 7 debug
+    if (!pinoLevel)
+        return 6; // default to info
+    if (pinoLevel >= 60)
+        return 2; // fatal -> critical
+    if (pinoLevel >= 50)
+        return 3; // error
+    if (pinoLevel >= 40)
+        return 4; // warning
+    if (pinoLevel >= 30)
+        return 6; // info
+    if (pinoLevel >= 20)
+        return 7; // debug
+    return 7; // trace -> debug
+};
+exports.mapPinoLevelToGelf = mapPinoLevelToGelf;
+function parseChunk(chunk) {
+    // OPTIMIZATION: Check object type first (most common case from Pino)
+    if (typeof chunk === 'object' && chunk !== null) {
+        return chunk;
+    }
+    // Handle strings and buffers
+    let str = '';
+    if (typeof chunk === 'string') {
+        str = chunk;
+    }
+    else if (Buffer.isBuffer(chunk)) {
+        str = chunk.toString();
+    }
+    // OPTIMIZATION: Heuristic check - only try parsing if it looks like JSON
+    // This avoids expensive try-catch throws on plain text logs
+    const firstChar = str.trim()[0];
+    if (firstChar === '{' || firstChar === '[') {
+        try {
+            return JSON.parse(str);
+        }
+        catch (_a) {
+            // If parse fails despite looking like JSON, fall back to wrapping it
+        }
+    }
+    return { msg: str };
+}
+function extractMessage(obj) {
+    // OPTIMIZATION: Use explicit type checks (slightly faster than truthiness)
+    if (typeof obj.msg === 'string')
+        return obj.msg;
+    if (typeof obj.message === 'string')
+        return obj.message;
+    if (typeof obj.short_message === 'string')
+        return obj.short_message;
+    return JSON.stringify(obj);
+}
+function addStaticMetadata(gelfMessage, staticMeta) {
+    // OPTIMIZATION: Use for...in to avoid allocating Object.entries array
+    for (const key in staticMeta) {
+        const value = staticMeta[key];
+        if (value !== undefined && value !== null) {
+            // OPTIMIZATION: Use charCodeAt for underscore check (95 is '_')
+            const fieldName = key.charCodeAt(0) === 95 ? key : `_${key}`;
+            gelfMessage[fieldName] =
+                typeof value === 'object' ? JSON.stringify(value) : value;
+        }
+    }
+}
+function addStackTrace(gelfMessage, obj) {
+    // Check for direct stack
+    if (typeof obj.stack === 'string') {
+        gelfMessage.full_message = obj.stack;
+        return;
+    }
+    // Check for nested err.stack using optional chaining
+    const err = obj.err;
+    if (typeof (err === null || err === void 0 ? void 0 : err.stack) === 'string') {
+        gelfMessage.full_message = err.stack;
+    }
+}
+function addCustomFields(gelfMessage, obj) {
+    // OPTIMIZATION: Use for...in loop instead of Object.entries
+    for (const key in obj) {
+        // OPTIMIZATION: O(1) lookup in Set instead of Array.includes
+        if (EXCLUDED_FIELDS.has(key))
+            continue;
+        const value = obj[key];
+        if (value === undefined || value === null)
+            continue;
+        // OPTIMIZATION: Use charCodeAt for underscore check
+        const fieldName = key.charCodeAt(0) === 95 ? key : `_${key}`;
+        // Avoid overwriting standard fields or static meta
+        if (fieldName in gelfMessage)
+            continue;
+        // GELF doesn't support nested objects well, stringify them
+        gelfMessage[fieldName] =
+            typeof value === 'object' ? JSON.stringify(value) : value;
+    }
+    // Add process info
+    if (obj.pid) {
+        gelfMessage._pid = obj.pid;
+    }
+}
+function formatGelfMessage(chunk, hostname, facility, staticMeta = {}) {
+    const obj = parseChunk(chunk);
+    // Pino adds 'time' field automatically (milliseconds since epoch)
+    // We preserve it to maintain accurate event timing even if messages are queued
+    // Fallback to current time for non-Pino messages
+    // OPTIMIZATION: Use typeof check and multiplication (faster than division)
+    const timestamp = typeof obj.time === 'number' ? obj.time * 1e-3 : Date.now() * 1e-3;
+    // Build GELF 1.1 message
+    const gelfMessage = {
+        version: '1.1',
+        host: hostname,
+        short_message: extractMessage(obj),
+        timestamp,
+        level: (0, exports.mapPinoLevelToGelf)(obj.level),
+    };
+    // Add facility as additional field (deprecated in GELF spec, now sent as custom field)
+    if (facility) {
+        gelfMessage._facility = facility;
+    }
+    addStaticMetadata(gelfMessage, staticMeta);
+    addStackTrace(gelfMessage, obj);
+    addCustomFields(gelfMessage, obj);
+    return JSON.stringify(gelfMessage);
+}