Splunk HTTP Event Collector Stream for Bunyan

0.11.0 verified Thu Apr 23 auth: no javascript

The `splunk-bunyan-logger` package provides a Bunyan stream specifically designed to send structured log data to Splunk Enterprise or Splunk Cloud via the HTTP Event Collector (HEC). It acts as a bridge, allowing applications using the Bunyan JSON logging library to seamlessly integrate with Splunk's data ingestion capabilities. The current stable version is 0.11.0. While no explicit release cadence is provided, the recent update (0.11.0) indicates active maintenance, with the last update fixing deprecated internal dependencies. Key differentiators include its tight integration with Bunyan's streaming architecture, batching capabilities for efficient data transfer, and support for custom event formatting. It requires Node.js v4 or later (tested with v10 and v14) and Splunk Enterprise 6.3.0 or later, or Splunk Cloud.

Common errors

error TypeError: splunkBunyan.createStream is not a function ↓

cause Attempting to destructure a CommonJS module's default export when it returns an object, or an incorrect ESM named import.

fix

Use const splunkBunyan = require('splunk-bunyan-logger'); and then access splunkBunyan.createStream(config);. Do not use const { createStream } = require('splunk-bunyan-logger'); or ESM import { createStream } from 'splunk-bunyan-logger';

error Error: self signed certificate in certificate chain ↓

cause This error occurs when `strictSSL` is enabled, and the Splunk HEC endpoint uses a self-signed or otherwise untrusted SSL certificate without proper CA configuration in the Node.js environment.

fix

Either disable strictSSL (not recommended for production) by splunkStream.logger.requestOptions.strictSSL = false; or, preferably, configure Node.js to trust your self-signed certificate by setting the NODE_EXTRA_CA_CERTS environment variable to the path of your CA certificate file.

error Error: connect ECONNREFUSED <splunk-host>:<port> ↓

cause The application cannot establish a connection to the specified Splunk HTTP Event Collector URL. This could be due to an incorrect URL, wrong port, firewall blocking the connection, or the Splunk HEC service not running or configured correctly.

fix

Verify the config.url is correct (including port). Check network connectivity from your application server to the Splunk HEC host, and ensure Splunk HEC is enabled and listening on the specified port.

Warnings

gotcha SSL certificate validation is disabled by default (`strictSSL = false`). For production environments, it is crucial to explicitly enable SSL certificate validation by setting `logger.requestOptions.strictSSL = true` to prevent man-in-the-middle attacks. ↓

fix Set `splunkStream.logger.requestOptions.strictSSL = true;` after creating the stream instance if your Splunk HEC endpoint uses a valid SSL certificate.

breaking Version 0.11.0 replaced the underlying HTTP client from `request` to `needle`. If your application relied on specific `request` library options passed via `requestOptions`, these might behave differently or no longer be supported. Review `needle`'s documentation for compatibility. ↓

fix Carefully test any custom `requestOptions` after upgrading to 0.11.0. Consult `needle` library documentation for equivalent options.

gotcha The library primarily uses CommonJS `require()` syntax. While modern Node.js versions support ESM, directly using `import` statements for `splunk-bunyan-logger` may not work as expected without proper transpilation or a CJS-to-ESM wrapper. ↓

fix Stick to `require()` for importing `splunk-bunyan-logger` in your Node.js applications or ensure your build setup correctly handles CommonJS module imports within an ESM context.

gotcha The Splunk HTTP Event Collector (HEC) requires a valid token and a reachable URL. Incorrect configuration can lead to logs not being sent to Splunk, often failing silently unless an error handler is attached to the stream. ↓

fix Ensure `config.token` and `config.url` are correct. Verify network connectivity to the Splunk HEC endpoint and attach an `error` listener to your `splunkStream` instance to catch and log any transmission failures.

Install

npm install splunk-bunyan-logger

yarn add splunk-bunyan-logger

pnpm add splunk-bunyan-logger

Imports

splunkBunyan
wrong
```
import splunkBunyan from 'splunk-bunyan-logger';
```
correct
```
const splunkBunyan = require('splunk-bunyan-logger');
```
The library primarily exposes its functionality via CommonJS `require`. Direct ESM `import` is not officially supported and may lead to issues without a CJS-to-ESM wrapper.

createStream

wrong

const { createStream } = require('splunk-bunyan-logger');

correct

const splunkBunyan = require('splunk-bunyan-logger');
const splunkStream = splunkBunyan.createStream(config);

The `createStream` factory method is a property of the object exported by the `splunk-bunyan-logger` module, not a direct named export in CommonJS.

Logger

wrong

const Logger = require('bunyan').Logger;

correct

const bunyan = require('bunyan');
const Logger = bunyan.createLogger({ name: 'my logger', streams: [splunkStream] });

The `Logger` class is instantiated via `bunyan.createLogger()`, not directly accessed as a property of the `bunyan` module.

Quickstart

This example demonstrates how to configure a Bunyan logger with the `splunk-bunyan-logger` stream to send structured logs to Splunk HTTP Event Collector. It includes basic error handling and uses environment variables for sensitive configuration.

const bunyan = require("bunyan");
const splunkBunyan = require("splunk-bunyan-logger");

const config = {
    token: process.env.SPLUNK_HEC_TOKEN ?? "your-splunk-hec-token-here",
    url: process.env.SPLUNK_HEC_URL ?? "https://splunk.local:8088"
};

// Create a SplunkStream instance
const splunkStream = splunkBunyan.createStream(config);

// Optional: Add an error handler for the stream
splunkStream.on("error", (err, context) => {
    // Log error, update metric, etc.
    console.error("Splunk HEC Logger Error:", err, context);
});

// Create a Bunyan Logger instance, adding the SplunkStream
const Logger = bunyan.createLogger({
    name: "my-application-logger",
    streams: [
        { stream: process.stdout, level: "info" }, // Also log to console
        splunkStream
    ]
});

const payload = {
    // Message can be anything, doesn't have to be an object
    message: {
        temperature: "72F",
        humidity: "60%",
        sensorId: "TH-001"
    },
    // Custom metadata for Splunk (optional)
    sourcetype: "_json",
    source: "my-node-app"
};

console.log("Sending payload to Splunk HEC...");
Logger.info(payload, "Environment sensor data collected.");
Logger.warn("Potential anomaly detected in sensor readings.");
console.log("Payload sent (asynchronously).");