Documentation forSolarWinds Observability SaaS

Send Node.js application logs (Papertrail)

You can ship Node.js application logs directly to SolarWinds Papertrail using either of the following methods:

  1. Syslog (TLS)

  2. HTTPS bulk

To get a destination and token in Papertrail, add a new log destination. The ingestion token is generated along with the destination. Use the collector endpoints for your account's region:

  • Syslog (TLS): syslog.collector.<REGION>.cloud.solarwinds.com:6514

  • HTTPS: https://logs.collector.<REGION>.cloud.solarwinds.com/v1/logs/bulk

Replace <REGION> with the data center your organization uses: na-01, eu-01, or ap-01.

Ship logs with Syslog (TLS)

Severity and host/program are carried per log record, the ingestion token is sent as structured data.

To ship Node.js application logs directly with Syslog (TLS), install the following package:

npm install winston

No additional packages are required. The transport uses Node's built-in tls module.

Save this file alongside your application: 

'use strict';
const tls     = require('tls');
const winston = require('winston');

const FACILITY_USER = 1;
const SEVERITY = {
  emerg: 0, alert: 1, crit: 2, error: 3,
  warning: 4, notice: 5, info: 6, debug: 7,
};

class SwoSyslogTransport extends winston.Transport {
  constructor(opts) {
    super(opts);
    this._token  = opts.token;
    this._host   = opts.host;
    this._port   = opts.port || 6514;
    this._hname  = opts.hostname;
    this._app    = opts.appName;
    this._queue  = [];
    this._ready  = false;
    this._connect();
  }

  _connect() {
    this._ready = false;
    this._socket = tls.connect({ host: this._host, port: this._port }, () => {
      this._ready = true;
      this._queue.splice(0).forEach(m => this._socket.write(m));
    });
    this._socket.on('error', () => setTimeout(() => this._connect(), 1000));
  }

  log(info, callback) {
    const sev  = SEVERITY[info[Symbol.for('level')]] ?? 6;
    const pri  = FACILITY_USER * 8 + sev;
    const ts   = new Date().toISOString().replace(/(\.\d{3})Z$/, '$1Z');
    const msg  = (info.message ?? '').toString().replace(/
/g, ' | ');
    const line = `<${pri}>1 ${ts} ${this._hname} ${this._app} - - [solarwinds@41058 token="${this._token}"] ${msg}
`;
    if (this._ready) {
      this._socket.write(line);
    } else {
      this._queue.push(line);
    }
    callback();
  }
}

module.exports = SwoSyslogTransport;

Now, configure and initialize the logger in your application.

const os      = require('os');
const winston = require('winston');
const SwoSyslogTransport = require('./swo-syslog-transport');

const logger = winston.createLogger({
  levels: winston.config.syslog.levels,
  level:  'debug',
  transports: [
    new SwoSyslogTransport({
      host:     `syslog.collector.${process.env.REGION}.cloud.solarwinds.com`,
      token:    process.env.SWO_TOKEN,
      hostname: os.hostname(),
      appName:  'my-service',
    }),
  ],
});

logger.info('Application started');
logger.error('Something went wrong', { detail: 'context here' });
Winston's syslog levels must be set on the logger (winston.config.syslog.levels). The standard warn alias is not available. You must use logger.warning(...) instead.

TLS certificates

No manual trust store configuration is required. The Papertrail collector certificate (*.cloud.solarwinds.com) is issued by Amazon RSA 2048 M04, which is included in Node.js's default CA bundle. The tls.connect() call verifies the certificate against the system trust store automatically.

Additional info

  • Severity mapping (according to RFC 5424): debug → 7, info → 6, notice → 5, warning → 4, error → 3, crit → 2, alert → 1, emerg → 0.

  • The transport opens one persistent TLS connection and queues messages sent before the handshake completes. On write error it reconnects automatically after 1 second.

  • Newlines in the message body are replaced with | to keep each log event on a single syslog line.

  • No external libraries beyond winston.

Ship logs with HTTPS bulk

When shipping logs with HTTPS bulk, the host/program is found in the X-Otel-Resource-Attr header, and the ingestion token is in the Authorization: Bearer header. The severity can be set as a field in the payload and arrives as a searchable json.* field only.

To ship Node.js application logs directly with HTTPS bulk, install the following package:

npm install winston

No additional packages are required. The transport uses the built-in fetch API (available from Node.js 18).

Save this file alongside your application: 

'use strict';
const winston = require('winston');

class SwoHttpTransport extends winston.Transport {
  constructor(opts) {
    super(opts);
    this._url     = `https://logs.collector.${opts.region}.cloud.solarwinds.com/v1/logs/bulk`;
    this._headers = {
      'Content-Type':         'application/x-ndjson',
      'Authorization':        `Bearer ${opts.token}`,
      'X-Otel-Resource-Attr': `host.name=${opts.hostname},service.name=${opts.appName}`,
    };
  }

  log(info, callback) {
    const record = {
      timestamp: new Date().toISOString(),
      severity:  info[Symbol.for('level')],
      message:   (info.message ?? '').toString(),
    };
    fetch(this._url, {
      method:  'POST',
      headers: this._headers,
      body:    JSON.stringify(record) + '
',
    }).catch(err => this.emit('error', err));
    callback();
  }
}

module.exports = SwoHttpTransport;

Now, configure and initialize the logger in your application.

const os      = require('os');
const winston = require('winston');
const SwoHttpTransport = require('./swo-http-transport');

const logger = winston.createLogger({
  levels: winston.config.syslog.levels,
  level:  'debug',
  transports: [
    new SwoHttpTransport({
      region:   process.env.REGION,
      token:    process.env.SWO_TOKEN,
      hostname: os.hostname(),
      appName:  'my-service',
    }),
  ],
});

logger.info('Application started');

Additional info

  • host.name and service.name are set from the X-Otel-Resource-Attr header and apply to the whole request batch — they are not per-record.

  • The /v1/logs/bulk endpoint assigns a fixed severity of info to all records in the Logs Explorer. The actual level is stored in json.severity and is searchable.

  • This transport sends one HTTP request per log event. For high-throughput applications, add batching logic to collect records over a short interval before flushing.

  • fetch is built into Node.js 18 and later. For older versions, install a polyfill such as node-fetch.

Pino Logs

Pino logs to standard output by default and delegates transport to external processes. To send logs to Papertrail from a Pino application:

  • HTTPS (simplest): pipe Pino's JSON output to a small worker that reads standard input and posts each line to the bulk endpoint. Or, use pino/file with a custom destination stream backed by SwoHttpTransport.

  • Syslog (TLS): chain pino-syslog (RFC 5424 formatter) with pino-socket (TCP/TLS sender). pino-syslog does not inject RFC 5424 structured data natively, so a custom formatter is needed to add the [solarwinds@41058 token="..."] SD element.

For most Pino applications, the HTTPS path is the lowest-friction option.

Fallback: Forward via a syslog daemon

If your application cannot connect directly to the Papertrail collector — for example, a strict outbound firewall blocks ports 6514 and 443 — write logs to a local file and use the host's syslog daemon to forward them to Papertrail over TLS. SolarWinds Observability supports rsyslog on Linux and NXlog on Windows for this purpose. See Send logs using syslog (Papertrail) for configuration instructions.

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.