Send Node.js application logs (Papertrail)
You can ship Node.js application logs directly to SolarWinds Papertrail using either of the following methods:
-
Syslog (TLS)
-
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.
Determining your method
| Syslog (TLS) | HTTPS bulk | |
|---|---|---|
| Log record carries per-record severity | Yes | No (always "info"; actual level in json.severity) |
| Carries system and program | Yes | Yes, from request header (for whole batch) |
| Setup effort | One transport file + logger config | One transport file + logger config |
| Extra dependencies | None beyond winston |
None (fetch built-in from Node 18) |
| Outbound port | 6514 (TLS) | 443 (HTTPS) |
| Node.js version | Any | 18+ (or polyfill) |
How Papertrail fills system and program
The Papertrail Logs Explorer is syslog-shaped and fills two key columns:
-
System (host/source)
-
Program (application)
How these columns are populated depends on the transport. Over syslog, the source is the RFC 5424 HOSTNAME and APP-NAME fields. Each record carries its own values. Over HTTPS bulk, the host.name and service.name attributes come from an HTTP header. The header applies to the whole request batch, so they are not read from the log body.
Ship logs with Syslog (TLS)
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.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.nameandservice.nameare set from theX-Otel-Resource-Attrheader and apply to the whole request batch — they are not per-record. -
The
/v1/logs/bulkendpoint assigns a fixed severity of info to all records in the Logs Explorer. The actual level is stored injson.severityand 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.
-
fetchis built into Node.js 18 and later. For older versions, install a polyfill such asnode-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/filewith a custom destination stream backed bySwoHttpTransport. -
Syslog (TLS): chain
pino-syslog(RFC 5424 formatter) withpino-socket(TCP/TLS sender).pino-syslogdoes 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.