Documentation forSolarWinds Observability SaaS

Ingesting logs from Java (Papertrail)

You can ship Java 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 Java application logs directly with Syslog (TLS), install the following packages:

Maven
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-api</artifactId>
  <version>2.0.17</version>
</dependency>
<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-core</artifactId>
  <version>2.26.0</version>
</dependency>
<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-slf4j2-impl</artifactId>
  <version>2.26.0</version>
</dependency>	
Gradle
implementation 'org.slf4j:slf4j-api:2.0.17'
implementation 'org.apache.logging.log4j:log4j-core:2.26.0'
implementation 'org.apache.logging.log4j:log4j-slf4j2-impl:2.26.0'

Then, configure log4j2.xml in your application classpath.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn">
  <Appenders>
    <Syslog name="SWO"
            host="syslog.collector.${env:REGION}.cloud.solarwinds.com"
            port="6514"
            protocol="SSL"
            facility="USER"
            format="RFC5424"
            appName="my-service"
            mdcId="solarwinds"
            enterpriseNumber="41058"
            includeMDC="true"
            mdcIncludes="token"
            newLine="true">
      <Ssl/>
    </Syslog>
  </Appenders>
  <Loggers>
    <Root level="INFO">
      <AppenderRef ref="SWO"/>
    </Root>
  </Loggers>
</Configuration>	

At application startup, enter the ingestion token into the MDC: 

MDC.put("token", System.getenv("SWO_TOKEN"));

Log4j2 includes this entry as the [solarwinds@41058 token="..."] SD element in every outgoing syslog message. mdcIncludes="token" ensures no other MDC entries leak into the SD element. The <Ssl> element instructs Log4j2 to use the JVM's default trust store so no manual keystore configuration is needed.

Logback users

Logback's built-in SyslogAppender produces only BSD syslog (RFC 3164) and has no RFC 5424 structured-data support. Logback users need a custom appender that formats the [solarwinds@41058 token="..."] SD element directly and sends over TLS using the JDK's built-in SSL.

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 Java's default cacerts on JDK 8u401+ and all JDK 11+. The <Ssl/> element uses the JVM's default trust store automatically.

Additional info

  • Severity mapping (according to RFC 5424): TRACE/DEBUG → 7, INFO → 6, WARN → 4, ERROR → 3, FATAL → 2.

  • Log4j2 manages a single persistent TCP+TLS connection and reconnects automatically on write error.

  • There are no external libraries beyond log4j-core.

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 Java application logs direct with HTTPS bulk, install the following packages:

Maven
<dependency>
  <groupId>org.slf4j</groupId>
  <artifactId>slf4j-api</artifactId>
  <version>2.0.17</version>
</dependency>
<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-core</artifactId>
  <version>2.26.0</version>
</dependency>
<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-slf4j2-impl</artifactId>
  <version>2.26.0</version>
</dependency>
<dependency>
  <groupId>org.apache.logging.log4j</groupId>
  <artifactId>log4j-layout-template-json</artifactId>
  <version>2.26.0</version>
</dependency>
Gradle
implementation 'org.slf4j:slf4j-api:2.0.17'
implementation 'org.apache.logging.log4j:log4j-core:2.26.0'
implementation 'org.apache.logging.log4j:log4j-slf4j2-impl:2.26.0'
implementation 'org.apache.logging.log4j:log4j-layout-template-json:2.26.0'

Then, configure log4j2.xml in your application classpath.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="warn">
  <Appenders>
    <Http name="SWO_HTTP"
          url="https://logs.collector.${env:REGION}.cloud.solarwinds.com/v1/logs/bulk"
          method="POST">
      <Property name="Authorization"       value="Bearer ${env:SWO_TOKEN}"/>
      <Property name="X-Otel-Resource-Attr"
                value="host.name=${env:HOSTNAME:-localhost},service.name=my-service"/>
      <JsonTemplateLayout eventTemplateUri="classpath:EcsLayout.json"/>
    </Http>
  </Appenders>
  <Loggers>
    <Root level="INFO">
      <AppenderRef ref="SWO_HTTP"/>
    </Root>
  </Loggers>
</Configuration>

The EcsLayout.json template is bundled in log4j-layout-template-json. It produces @timestamp, message, log.level, log.logger, and other ECS fields. All JSON fields are searchable in Logs Explorer as json.*.

Additional info

  • HttpAppender sends one HTTP request per log event. For high-throughput apps, wrap it in AsyncAppender to avoid blocking the calling thread.

  • 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.

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 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.