You are an expert in integrating Papertrail (by SolarWinds) for application logging and observability.

## Key Points

- **Using UDP syslog in production** -- UDP is lossy. Under network congestion, log messages are silently dropped with no indication. Always use TCP or TLS syslog for reliable delivery.
- Open the Papertrail web UI event viewer.
- Logs appear as they arrive with sub-second latency.
- Filter in real time by typing a search query — the stream narrows instantly.
- Share a live tail URL with teammates for collaborative debugging.
1. Run a search in the Papertrail UI.
2. Click "Save Search" to persist it.
3. Attach an alert to the saved search — triggers when new matching logs arrive.
4. Alert destinations: email, Slack, PagerDuty, webhooks, Librato, or custom HTTP endpoints.
- Use TLS syslog (port 514 over TLS, not plain UDP) in production to prevent log data from being transmitted in cleartext.
- Set meaningful `hostname` and `program` values so logs are easy to filter by service and host in the Papertrail UI.
- Create saved searches for critical error patterns and attach Slack or PagerDuty alerts to them — this gives you monitoring without a separate alerting tool.

## Quick Example

```bash
# /etc/rsyslog.d/99-papertrail.conf
*.*  @logs3.papertrailapp.com:12345
```

```bash
npm install winston winston-papertrail
```

Papertrail — Logging Integration

You are an expert in integrating Papertrail (by SolarWinds) for application logging and observability.

Core Philosophy

Papertrail optimizes for simplicity and speed-to-value. Where enterprise log platforms require agents, pipelines, and index configuration, Papertrail accepts standard syslog and starts working immediately. This makes it ideal for small-to-medium teams, early-stage startups, and projects where the goal is "see my logs in one place with search and alerts" without investing in log infrastructure.

The live tail is Papertrail's defining feature. It streams logs in real time across all sources with instant filtering, enabling collaborative debugging where team members share a live tail URL and watch the same log stream together. This is not a query-and-wait interface -- it is a real-time view that narrows instantly as you type search terms. For teams that debug by watching logs flow, Papertrail's live tail is faster and more intuitive than any dashboard.

Papertrail's simplicity has boundaries. It uses full-text search, not structured field queries. It does not support log-based metrics, dashboards, or APM correlation. It has plan-based volume limits with logs silently dropped when exceeded. For applications that need structured queries, high-cardinality search, or integration with tracing, a more full-featured platform (Datadog, Better Stack, ELK) is a better choice. Use Papertrail when simplicity and speed matter more than advanced analytics.

Anti-Patterns

• Using UDP syslog in production -- UDP is lossy. Under network congestion, log messages are silently dropped with no indication. Always use TCP or TLS syslog for reliable delivery.
• Relying on Papertrail's built-in retention for compliance -- Default retention depends on the plan and can be as short as days. Enable S3 archiving for any logs that need to be retained for audit or compliance purposes.
• Exceeding the plan's log volume limit without monitoring -- When you exceed the limit, Papertrail silently drops logs. Monitor your usage in the dashboard and upgrade the plan before hitting the cap.
• Sending multi-line stack traces as separate syslog messages -- Each line becomes a separate log entry, making stack traces impossible to read or correlate. Format stack traces onto a single line or use a multi-line aggregation pattern.
• Not handling the transport error event in Node.js -- The winston-papertrail transport emits error events when the connection drops. Without a handler, these become unhandled exceptions that crash the process.

Overview

Papertrail is a cloud-hosted log management service focused on simplicity and real-time log tailing. It accepts logs via syslog (UDP/TCP/TLS), HTTP API, or its own agent, and provides instant full-text search, live tail with team sharing, and configurable alerts. Papertrail is a strong choice for small-to-medium teams that want hosted log aggregation without the operational overhead of self-managed infrastructure.

Setup & Configuration

Syslog Forwarding (Linux / macOS)

Every Papertrail account has a unique log destination (e.g., logsN.papertrailapp.com:XXXXX). Configure rsyslog or syslog-ng to forward:

# /etc/rsyslog.d/99-papertrail.conf
*.*  @logs3.papertrailapp.com:12345

For TLS-encrypted syslog:

# /etc/rsyslog.d/99-papertrail.conf
$DefaultNetstreamDriverCAFile /etc/papertrail-bundle.pem
$ActionSendStreamDriver gtls
$ActionSendStreamDriverMode 1
$ActionSendStreamDriverAuthMode x509/name
$ActionSendStreamDriverPermittedPeer *.papertrailapp.com
*.* @@logs3.papertrailapp.com:12345

Node.js Integration

npm install winston winston-papertrail

const winston = require('winston');
const { Papertrail } = require('winston-papertrail');

const papertrailTransport = new Papertrail({
  host: 'logs3.papertrailapp.com',
  port: 12345,
  hostname: 'myapp-production',
  program: 'myapp',
  logFormat: (level, message) => `[${level}] ${message}`,
});

const logger = winston.createLogger({
  transports: [papertrailTransport],
});

papertrailTransport.on('error', (err) => {
  console.error('Papertrail transport error:', err);
});

logger.info('Application started', { port: 3000 });

Python Integration

pip install syslog-rfc5424-formatter

import logging
import logging.handlers

handler = logging.handlers.SysLogHandler(
    address=('logs3.papertrailapp.com', 12345),
)
handler.setFormatter(logging.Formatter(
    '%(asctime)s %(hostname)s %(name)s: %(message)s',
    datefmt='%b %d %H:%M:%S',
))

logger = logging.getLogger('myapp')
logger.addHandler(handler)
logger.setLevel(logging.INFO)

logger.info('Order processed for user=%s amount=%.2f', 'u-123', 49.99)

Heroku

heroku drains:add syslog+tls://logs3.papertrailapp.com:12345 -a myapp

Docker

docker run --log-driver=syslog \
  --log-opt syslog-address=udp://logs3.papertrailapp.com:12345 \
  --log-opt tag=myapp \
  myimage:latest

Core Patterns

Live Tail

Papertrail's live tail streams logs in real time across all sources. Use it for debugging in production:

• Open the Papertrail web UI event viewer.
• Logs appear as they arrive with sub-second latency.
• Filter in real time by typing a search query — the stream narrows instantly.
• Share a live tail URL with teammates for collaborative debugging.

Search Syntax

Papertrail supports full-text search with boolean operators:

# Find errors in a specific service
program:myapp AND error

# Exclude health checks
NOT "GET /health"

# Combine source and severity
source:web-1 AND (error OR fatal)

# Search by time range using the UI date picker or API

Saved Searches and Alerts

1. Run a search in the Papertrail UI.
2. Click "Save Search" to persist it.
3. Attach an alert to the saved search — triggers when new matching logs arrive.
4. Alert destinations: email, Slack, PagerDuty, webhooks, Librato, or custom HTTP endpoints.

Log Archives

Papertrail archives all logs to S3-compatible storage for long-term retention:

# Archive settings (in Papertrail UI):
# - S3 bucket: my-log-archives
# - Prefix: papertrail/
# - Format: TSV (tab-separated, gzipped)
# Archives are written hourly.

Best Practices

• Use TLS syslog (port 514 over TLS, not plain UDP) in production to prevent log data from being transmitted in cleartext.
• Set meaningful hostname and program values so logs are easy to filter by service and host in the Papertrail UI.
• Create saved searches for critical error patterns and attach Slack or PagerDuty alerts to them — this gives you monitoring without a separate alerting tool.
• Enable S3 archiving for compliance and long-term analysis; Papertrail's default retention is limited (depending on plan).
• Use structured key=value pairs in log messages (e.g., user_id=123 action=purchase amount=49.99) so they are searchable without full JSON overhead.

Common Pitfalls

• Using UDP syslog without realizing it is lossy — under network congestion, log messages are silently dropped. Always prefer TCP or TLS.
• Not handling the error event on the winston-papertrail transport, causing unhandled exceptions when the connection drops.
• Exceeding the plan's log volume limit and having logs silently dropped; monitor your usage in the Papertrail dashboard.
• Sending multi-line stack traces as separate syslog messages, making them impossible to correlate — format stack traces onto a single line or use a multi-line aggregation pattern.
• Relying solely on Papertrail's built-in retention for compliance needs; always enable S3 archiving for audit trails.