Send logs with OpenTelemetry Protocol (Papertrail)
If your logs already flow through an OpenTelemetry Collector or your application uses an OpenTelemetry SDK, you can send your logs to Papertrail over HTTP or gRPC with the OpenTelemetry Protocol (OTLP).
Choose a transport
Both transports listed below use the OTLP endpoint for your region on TCP port 443, with TLS.
| Transport | Endpoint | When to use |
|---|---|---|
| OTLP/gRPC | otel.collector.<REGION>.cloud.solarwinds.com:443
|
You use the OpenTelemetry Collector or an SDK that supports gRPC and your network allows HTTP/2 to the internet. |
| OTLP/HTTP | https://otel.collector.<REGION>.cloud.solarwinds.com/v1/logs
|
A proxy or firewall allows only HTTP/1.1 or your SDK or tool supports only OTLP/HTTP. Supports |
Replace <REGION> with the data center your organization uses: na-01, eu-01, or ap-01. You can find it in the URL you use to sign in (for example, my.na-01.cloud.solarwinds.com). See Data centers and endpoint URIs.
Before you begin
-
Create an ingestion token. Go to Logs > Destinations > Create destination and create a token-based destination. The ingestion token is created together with the destination. To reuse an existing token, copy it from its destination in Logs > Destinations.
-
Allow outbound connections to
otel.collector.<REGION>.cloud.solarwinds.comon TCP port 443. -
Use TLS and keep certificate verification enabled.
Authenticate
Send the ingestion token in the authorization header (OTLP/HTTP) or authorization metadata (OTLP/gRPC) of every request:
authorization: Bearer <TOKEN>
The Bearer prefix is required. A request that sends the bare token is rejected with 400, not 401.
Configure the OpenTelemetry Collector
Add an exporter for Papertrail and use it in a logs pipeline. The examples below use the filelog receiver to read log files. You can use any receiver that produces logs.
OTLP/gRPC exporter
receivers:
filelog:
include: [/var/log/myapp/*.log]
processors:
resource:
attributes:
- key: host.name
value: web-01
action: upsert
- key: service.name
value: checkout
action: upsert
batch: {}
exporters:
otlp/swo:
endpoint: otel.collector.<REGION>.cloud.solarwinds.com:443
headers:
authorization: "Bearer ${env:SWO_INGESTION_TOKEN}"
compression: gzip
service:
pipelines:
logs:
receivers: [filelog]
processors: [resource, batch]
exporters: [otlp/swo]
OTLP/HTTP exporter
Use the same receivers, processors, and pipeline, but replace the exporter:
exporters:
otlphttp/swo:
endpoint: https://otel.collector.<REGION>.cloud.solarwinds.com
headers:
authorization: "Bearer ${env:SWO_INGESTION_TOKEN}"
compression: gzip
The otlphttp exporter adds /v1/logs to the endpoint. Do not add the path yourself. If you use logs_endpoint instead of endpoint, set the full URL, including /v1/logs.
Both examples read the token from an environment variable rather than keeping it in the configuration file. Set it before you start the collector.
-
In Windows PowerShell:
$env:SWO_INGESTION_TOKEN = "<TOKEN>" -
On Linux or macOS:
export SWO_INGESTION_TOKEN=<TOKEN>
Keep compression at gzip or zstd. Other values the Collector offers, such as deflate, are not decompressed by the endpoint. See Limits.
Keep the batch processor in the pipeline. It reduces the number of requests and keeps each request within the size limit.
Recent Collector builds log a deprecation warning for the otlp and filelog component aliases, and suggest otlp_grpc and file_log. The warning is harmless and both forms work. Use the newer names if your Collector version supports them.
Set the severity
The filelog receiver does not set a severity, so by default every event is stored with Severity INFO, even when the log line says ERROR. Severity comes from the OTLP severityNumber field. To map the level out of your log lines, add a severity parser to the receiver:
receivers:
filelog:
include: [/var/log/myapp/*.log]
operators:
- type: regex_parser
regex: '^\S+ (?P<level>[A-Z]+) '
severity:
parse_from: attributes.level
Adjust the regular expression to match where the level appears in your lines. With this operator, a line that begins 2026-10-14T16:25:17+02:00 ERROR ... is stored with Severity ERROR.
Configure an OpenTelemetry SDK
OpenTelemetry SDKs read their exporter settings from standard environment variables. Set the logs exporter to OTLP, and turn off the metrics and traces exporters. Turning them off is crucial. The endpoint also accepts /v1/metrics and /v1/traces with the same token and answers 200, so an SDK left on its defaults sends metrics and traces that Papertrail does not show, and no error is shown.
In the headers variable, encode the space after Bearer as %20.
OTLP/HTTP
In Windows PowerShell:
$env:OTEL_SERVICE_NAME = "checkout" $env:OTEL_RESOURCE_ATTRIBUTES = "host.name=web-01" $env:OTEL_LOGS_EXPORTER = "otlp" $env:OTEL_METRICS_EXPORTER = "none" $env:OTEL_TRACES_EXPORTER = "none" $env:OTEL_EXPORTER_OTLP_LOGS_PROTOCOL = "http/protobuf" $env:OTEL_EXPORTER_OTLP_LOGS_ENDPOINT = "https://otel.collector.<REGION>.cloud.solarwinds.com/v1/logs" $env:OTEL_EXPORTER_OTLP_LOGS_HEADERS = "authorization=Bearer%20<TOKEN>"
On Linux or macOS:
export OTEL_SERVICE_NAME=checkout export OTEL_RESOURCE_ATTRIBUTES=host.name=web-01 export OTEL_LOGS_EXPORTER=otlp export OTEL_METRICS_EXPORTER=none export OTEL_TRACES_EXPORTER=none export OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=http/protobuf export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://otel.collector.<REGION>.cloud.solarwinds.com/v1/logs export OTEL_EXPORTER_OTLP_LOGS_HEADERS="authorization=Bearer%20<TOKEN>"
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT must include /v1/logs. If you use the general OTEL_EXPORTER_OTLP_ENDPOINT variable instead, set it without the path. The SDK adds /v1/logs.
OTLP/gRPC
Use the same variables as for OTLP/HTTP, with the following two values:
OTEL_EXPORTER_OTLP_LOGS_PROTOCOL=grpc OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://otel.collector.<REGION>.cloud.solarwinds.com:443
Not every SDK supports both transports. Check the OpenTelemetry documentation for your language.
How OTLP fields appear in the Logs Explorer
| OTLP field | Displays in the Logs Explorer as | Search example |
|---|---|---|
host.name resource attribute |
System | host:web-01
|
service.name resource attribute |
Program | program:checkout
|
| Log record body | Message | payment failed
|
severityNumber
|
Severity | severity:ERROR
|
| Log record attributes | Searchable attributes | http.status_code:503
|
Severity comes from severityNumber, the OTLP numeric severity. severityText on its own is ignored.
Log record attributes are searchable by name and value. For example, http.status_code:503.
If the log record body is an RFC 5424 syslog message, System, Program, and Severity can be taken from the syslog header instead.
If no host.name resource attribute is set, the System column shows the IP address the request came from rather than staying empty.
Limits
| Limit | Value |
|---|---|
| Request size (OTLP/gRPC) | 6,291,456 bytes (6 MB), after decompression |
| Log record size | 1,048,576 bytes (1 MB) |
| Compression |
OTLP/gRPC also accepts |
A log record above the size limit is rejected, not truncated.
On OTLP/HTTP, only gzip and zstd are decompressed. A body sent with any other Content-Encoding, such as deflate or br, is passed through undecompressed and then fails to parse. The request is rejected with 400 and a message that looks like a malformed payload. Snappy and lz4 apply only to OTLP/gRPC. A gRPC client has to select them explicitly because the endpoint does not advertise them.
Responses
| Status | Meanings | What to do |
|---|---|---|
200 OK
|
Accepted. The body is |
N/A |
400 Bad Request
|
The payload is malformed or was compressed with an unsupported A log record is larger than 1 MB. A record timestamp is outside the allowed range. The |
Fix the payload, the compression, the timestamp, or the header. |
401 Unauthorized
|
The The token is invalid or belongs to another region. |
Copy the token again and check <REGION>. |
404 Not Found
|
Wrong path. OTLP/HTTP logs go to /v1/logs exactly once. |
See the exporter notes above. |
415 Unsupported Media Type
|
The Content-Type is neither application/x-protobuf nor application/json. |
Use one of the two. |
When a request mixes valid and rejected records, the response is 200 with a partialSuccess object, and the valid records are stored:
{"partialSuccess":{"rejectedLogRecords":"1","errorMessage":"... Log record is bigger than the maximum ..."}}
If every record in the request is rejected, the response is 400 instead.
Quick test
Replace <REGION> and <TOKEN> in the below examples. After each test, search the Logs Explorer for the message text.
OTLP/HTTP with a JSON-encoded request
In Windows PowerShell:
$ns = [DateTimeOffset]::UtcNow.ToUnixTimeMilliseconds() * 1000000
$body = @"
{"resourceLogs":[{"resource":{"attributes":[{"key":"host.name","value":{"stringValue":"test-host"}},{"key":"service.name","value":{"stringValue":"test-app"}}]},"scopeLogs":[{"logRecords":[{"timeUnixNano":"$ns","severityNumber":9,"body":{"stringValue":"Test message over OTLP"}}]}]}]}
"@
Invoke-RestMethod -Method Post -Uri "https://otel.collector.<REGION>.cloud.solarwinds.com/v1/logs" -Headers @{ authorization = "Bearer <TOKEN>" } -ContentType "application/json" -Body $body
On Linux or macOS:
ns="$(date +%s)000000000"
curl -X POST "https://otel.collector.<REGION>.cloud.solarwinds.com/v1/logs" \
-H "authorization: Bearer <TOKEN>" -H "Content-Type: application/json" \
--data-raw '{"resourceLogs":[{"resource":{"attributes":[{"key":"host.name","value":{"stringValue":"test-host"}},{"key":"service.name","value":{"stringValue":"test-app"}}]},"scopeLogs":[{"logRecords":[{"timeUnixNano":"'"$ns"'","severityNumber":9,"body":{"stringValue":"Test message over OTLP"}}]}]}]}'
A successful request returns HTTP 200 with {}. In the Logs Explorer, search for Test message over OTLP. The System column shows test-host, the Program column shows test-app, and Severity is INFO because severityNumber 9 is INFO.
OTLP/gRPC with telemetrygen
telemetrygen is an OpenTelemetry tool that sends test telemetry.
On Linux or macOS:
telemetrygen logs --otlp-endpoint otel.collector.<REGION>.cloud.solarwinds.com:443 --otlp-header 'authorization="Bearer <TOKEN>"' --service test-app --logs 1 --body "Test message over OTLP gRPC"
In the Logs Explorer, search for Test message over OTLP gRPC. The Program column shows test-app. telemetrygen does not set host.name, so the System column shows the IP address that sent the request.
You can also test OTLP/gRPC with the Collector configuration above by appending a line to a file the filelog receiver watches.
Troubleshooting
| Symptom | Likely cause | Solution |
|---|---|---|
HTTP 401 or gRPC UNAUTHENTICATED |
The token is missing, invalid, or belongs to a different region. |
Copy the token again from Logs > Destinations. Check |
HTTP 400 on every request |
The authorization value does not start with Bearer. |
Send authorization: Bearer <TOKEN>. |
SDK requests fail with 401 although the token is correct |
The space in the headers variable is not encoded. | Use authorization=Bearer%20<TOKEN> in OTEL_EXPORTER_OTLP_LOGS_HEADERS. |
HTTP 400 with a JSON or protobuf parse error, although the payload is valid |
The body was compressed with a Content-Encoding the endpoint does not decompress, such as deflate or br. The compressed bytes reached the parser. |
Use gzip or zstd or send the body uncompressed. |
HTTP 404 |
The /v1/logs path is missing or doubled. |
With the Collector With |
HTTP 400 with Log record is bigger than the maximum |
A single log record exceeds 1 MB. | Split or truncate the record before sending. Other records in the same request are still stored, and the response reports the rejected ones under partialSuccess. |
HTTP 400 with Time is not within the allowed boundaries |
The record's timeUnixNano is too far in the future or the past. A clock that is well ahead of the real time is the usual cause. |
Fix the clock on the sender. Timestamps roughly half an hour ahead and a day behind are accepted, but timestamps an hour ahead or a week behind are not. |
gRPC RESOURCE_EXHAUSTED |
The request exceeds the 6 MB gRPC limit. | Use the batch processor and reduce send_batch_size. |
A gRPC client hangs and then fails with DeadlineExceeded, with the channel stuck in CONNECTING |
gRPC resolves the endpoint with its own DNS resolver, which also issues SRV and TXT lookups. Some resolvers, such as Docker's embedded DNS, never answer those, so no address is returned. |
Run the client outside the container. Give the container a real resolver ( Prefix the endpoint with |
| gRPC connection errors through a proxy | The proxy does not support HTTP/2. | Use OTLP/HTTP. |
Every event has Severity INFO |
No severityNumber is set, which is the default for the filelog receiver. |
Add a severity parser. See Set the severity. |
| System shows an IP address | No host.name resource attribute was set. |
Set it with the Collector resource processor or with OTEL_RESOURCE_ATTRIBUTES. |
| Program is empty | No service.name resource attribute was set. |
Set it with the Collector resource processor or with OTEL_SERVICE_NAME. |
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.