Splunk Logging for JavaScript

0.11.1 · active · verified Wed Apr 22

The `splunk-logging` package provides a straightforward JavaScript interface for Node.js applications to send log data to Splunk Enterprise or Splunk Cloud via the HTTP Event Collector (HEC). The current stable version is 0.11.1, with releases occurring periodically to address dependencies and minor enhancements rather than a fixed cadence. This library simplifies the process of sending events by handling connection details, batching, and retries automatically. Key features include configurable batching settings (interval, maximum count, and maximum size), support for custom event formatting, and options for SSL certificate validation. While primarily community-supported, it is an official Splunk project designed for seamless integration with Splunk HEC endpoints, making it a robust choice for Node.js-based logging into the Splunk ecosystem.

Common errors

```
UNABLE_TO_VERIFY_LEAF_SIGNATURE
```
cause Node.js could not verify the SSL certificate of the Splunk HEC endpoint, often due to self-signed certificates, an expired certificate, or a missing Certificate Authority (CA) bundle.

fix Either disable SSL validation (`Logger.requestOptions.strictSSL = false` - *not recommended for production*) or ensure that the Splunk HEC endpoint's SSL certificate chain is valid and trusted by your Node.js environment. You might need to add custom CA certificates to your system's trust store or configure Node.js to use them.
```
connect ECONNREFUSED <splunk-host>:<port>
```
cause The Splunk HTTP Event Collector endpoint is unreachable, not running, or a firewall is blocking the connection from your application's host to the Splunk instance.

fix Verify that the `url` configuration in your `SplunkLogger` instance is correct, ensure the Splunk HEC service is running and configured to listen on the specified port, and check network connectivity and firewall rules between your application server and the Splunk host.
```
{ text: 'Invalid token', code: 4 }
```
cause The HTTP Event Collector token provided in the logger configuration is invalid, expired, or not correctly configured on the Splunk instance.

fix Double-check the HEC token in your `Logger` configuration against the token configured in your Splunk Enterprise or Splunk Cloud instance. Ensure the token is enabled and has the necessary permissions to receive events.

Warnings

gotcha By default, SSL certificate validation is disabled (`Logger.requestOptions.strictSSL = false`). This poses a significant security risk, especially in production environments where secure communication is critical.
Fix: To enable SSL validation, set `Logger.requestOptions.strictSSL = true` immediately after initializing your SplunkLogger instance. Ensure your Node.js environment trusts the certificate authority for your Splunk instance.
breaking In version 0.11.0, the underlying HTTP client implementation was switched from the deprecated 'request' library to 'needle'. While designed for compatibility, users relying on specific behaviors, undocumented options, or advanced configurations of the 'request' library might encounter subtle changes or unexpected behavior.
Fix: Review your logger configuration, especially custom `requestOptions`, if upgrading from versions prior to 0.11.0. Thoroughly test network interactions to ensure continued compatibility.
gotcha The library does not automatically handle all possible Node.js versions. While tested with v10 and v14, newer Node.js LTS versions may introduce subtle breaking changes in core modules (e.g., `http`, `https`) that could affect the underlying `needle` client.
Fix: Refer to the official project's GitHub page for the latest tested Node.js versions. If encountering network-related issues, try testing with the Node.js versions explicitly stated as supported.

Install

npm install splunk-logging npm
yarn add splunk-logging yarn
pnpm add splunk-logging pnpm

Imports

Logger
wrong:
```
import SplunkLogger from 'splunk-logging';
```
correct:
```
import { Logger } from 'splunk-logging';
```
For ESM modules in Node.js, the `Logger` class is a named export.

Logger

wrong:

const Logger = require('splunk-logging');

correct:

const { Logger } = require('splunk-logging');

Modern CommonJS destructuring for the `Logger` class.

Logger

wrong:

var Logger = require('splunk-logging');

correct:

var SplunkLogger = require('splunk-logging').Logger;

Traditional CommonJS import as shown in older examples.

Quickstart

Demonstrates configuring a Splunk logger with environment variables for token and URL, then sending a structured JSON payload to the HTTP Event Collector, and logging the Splunk response.

import { Logger } from 'splunk-logging';

const config = {
    token: process.env.SPLUNK_HEC_TOKEN ?? '',
    url: process.env.SPLUNK_HEC_URL ?? 'https://splunk.local:8088'
};

const splunkLogger = new Logger(config);

// Optionally enable SSL certificate validation (highly recommended for production)
// splunkLogger.requestOptions.strictSSL = true;

const payload = {
    // Message can be anything; doesn't have to be an object
    message: {
        service: 'my-node-app',
        level: 'info',
        event_id: Math.floor(Math.random() * 1000000),
        details: 'User activity logged successfully.',
        timestamp: new Date().toISOString()
    },
    // Optional metadata
    metadata: {
        source: 'my-node-app',
        sourcetype: 'node:json',
        host: 'my-server'
    }
};

console.log('Sending payload', JSON.stringify(payload, null, 2));
splunkLogger.send(payload, function(err, resp, body) {
    if (err) {
        console.error('Error sending data to Splunk:', err);
        return;
    }
    // If successful, body will be { text: 'Success', code: 0 }
    console.log('Response from Splunk:', body);
});

view raw JSON →