Send logs with an HTTPS POST request (Papertrail)
When your application, script, or log shipper can make HTTPS requests or when only port 443 is open outbound, use an HTTPS POST request to send logs to Papertrail.
Choose an endpoint
All endpoints use the HTTPS logs collector for your region: https://logs.collector.<REGION>.cloud.solarwinds.com.
| Endpoint | When to use | Body | Authentication |
|---|---|---|---|
POST /v1/logs
|
You send one event per request, such as from a script or a webhook. |
One event. Line breaks inside the body are kept, so a multiline stack trace stays one event. |
Authorization: Bearer <TOKEN> header |
POST /v1/logs/bulk
|
You send many events at once, such as from a log shipper or a file. Recommended for production volumes. |
One event per line. | Authorization: Bearer <TOKEN> header, or the token in the path: /v1/logs/bulk/<TOKEN> |
POST /v1/logs/logplex/<TOKEN>
|
A platform or log shipper sends its log drain in the Logplex format (application/logplex-1). |
One or more octet-counted frames ( Requires |
Token in the path |
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 generated together with the destination. To reuse an existing token, copy it from its destination in Logs > Destinations.
-
Allow outbound connections to
logs.collector.<REGION>.cloud.solarwinds.comon TCP port 443. -
Use HTTPS and keep TLS certificate verification enabled.
Authenticate
Add the ingestion token to every request:
Authorization: Bearer <TOKEN>
If your client cannot set request headers, put the token in the URL path instead. This is supported on the bulk and Logplex endpoints only:
-
Bulk:
POST /v1/logs/bulk/<TOKEN> -
Logplex:
POST /v1/logs/logplex/<TOKEN>
Anyone who can see a URL that contains the token can send logs with it. Where you can, use the Authorization header to prevent the token from appearing in proxy logs or shipper configuration exports.
Single-event endpoint
POST /v1/logs stores the request body as one event. This endpoint supports the following Content-Type values: text/plain, application/octet-stream, or application/json. Line breaks inside the body are kept, while trailing whitespace and line breaks at the end of the body are removed. The body must not be empty and must be smaller than 1 MB.
Bulk endpoint
POST /v1/logs/bulk splits the body into lines and stores each line as a separate event. Use it to reduce the number of requests when you send more than a few events per second.
The bulk endpoint supports the following Content-Type values: text/plain, application/octet-stream, application/json, and application/x-ndjson. Each line feed (LF), carriage return (CR), or CRLF ends an event. Trailing whitespace is removed from each line. Each line must be smaller than 1 MB, and the whole request must be smaller than 5 MB. If any line or whole request is too large, the entire request is rejected with 413. Split it into smaller requests. For JSON, send newline-delimited JSON (NDJSON): one complete JSON object per line, not a JSON array.
Because every LF, CR, and CRLF ends an event, a multiline event such as a stack trace arrives as several events. You have three options:
-
Replace the line breaks in the message before you send it, with a literal
\nor a separator such as|. -
Send each multiline event on its own to
POST /v1/logs, which keeps the line breaks. -
Send octet-counted syslog frames (application/syslog-frames), which keep the line breaks and still let you batch.
Logplex endpoint
POST /v1/logs/logplex/<TOKEN> accepts batches of octet-counted frames with Content-Type: application/logplex-1. Use it when a platform or log shipper sends its log drain in this format.
Drain URL:
https://logs.collector.<REGION>.cloud.solarwinds.com/v1/logs/logplex/<TOKEN>?hostname=<NAME>
-
hostname(optional) sets the System name for every event in the request. If you omit it, the System shows the IP address that sent the request.An X-Otel-Resource-Attr: host.name=<NAME>header takes precedence over this parameter. -
The Program name comes from an
X-Otel-Resource-Attr: service.name=<NAME>header. Without it, the Program column is empty.
Logplex format
Each request body contains one or more octet-counted frames. A frame is the message length in bytes, a space, and the message:
MSG-LEN SP MESSAGE
Frames are concatenated without separators. For example, a body with two frames:
16 First event text17 Second event text
The message can be any text, and it is stored as the event text. Because the length is counted in bytes, a message may contain line breaks and still be one event. Set the System and Program names with the ?hostname= parameter or the X-Otel-Resource-Attr header rather than relying on the content of the message.
The body must always be framed. Unlike /v1/logs, an unframed body is not accepted. If it does not start with a number followed by a space, the request is rejected with 413.
MSG-LEN is the length of the message in UTF-8 bytes, not characters, excluding the space after the number. An incorrect length does not produce an error, so it is worth computing carefully:
-
A length smaller than the message silently truncates the event, and the bytes left over are discarded.
-
A length larger than the rest of the body is accepted, and the event is stored in full.
In shell examples, count bytes with printf '%s' "$m" | wc -c. Avoid ${#m}, which counts characters and is only correct for ASCII text.
Set the System and Program names
Add the optional X-Otel-Resource-Attr header to requests on any of the endpoints. The values apply to every event in the request.
| Attribute | Example header | Effect |
|---|---|---|
host.name
|
X-Otel-Resource-Attr: host.name=web-01 |
Sets the System name shown in the Logs Explorer. Search for it with host:web-01. |
service.name
|
X-Otel-Resource-Attr: service.name=checkout
|
Sets the Program name shown in the Logs Explorer. Search for it with program:checkout. |
To set both, separate the values with commas in one header, for example X-Otel-Resource-Attr: host.name=web-01, service.name=checkout, or repeat the header. Use the comma-separated form with shippers that cannot set the same header twice, such as Fluent Bit and Fluentd.
If the body is an RFC 5424 syslog message sent to /v1/logs or /v1/logs/bulk, System, Program, and Severity are taken from the syslog header instead. A host.name attribute in X-Otel-Resource-Attr overrides the syslog HOSTNAME.
Responses
| Status | Meaning | What to do |
|---|---|---|
202 Accepted
|
The request was accepted. | N/A |
401 Unauthorized
|
The token is missing or invalid. | Check the token and the region in the endpoint URL. |
413 Payload Too Large
|
An event or the request is too large. A Logplex frame does not start with a valid length. |
Split the request or fix the frame lengths. |
415 Unsupported Media Type
|
The Content-Type is not supported by the endpoint. |
Use a Content-Type listed for the endpoint. |
500 Internal Server Error
|
Temporary server error, including a failed token check when the token is in the path. | Retry with backoff. |
A 202 means the request was accepted, not that every event was stored as you intended. A Logplex frame whose declared length does not match its content is still accepted. See Logplex format.
Quick test
In the examples below, replace <REGION> and <TOKEN>. After each test, search the Logs Explorer for your message text.
Single event
Windows PowerShell:
curl.exe -X POST "https://logs.collector.<REGION>.cloud.solarwinds.com/v1/logs" -H "Authorization: Bearer <TOKEN>" -H "Content-Type: text/plain" -H "X-Otel-Resource-Attr: host.name=test-host, service.name=test-app" --data-raw "Test message over HTTPS"
Linux or macOS:
curl -X POST "https://logs.collector.<REGION>.cloud.solarwinds.com/v1/logs" -H "Authorization: Bearer <TOKEN>" -H "Content-Type: text/plain" -H "X-Otel-Resource-Attr: host.name=test-host, service.name=test-app" --data-raw "Test message over HTTPS"
In the Logs Explorer, search for Test message over HTTPS. The System column shows test-host and the Program column shows test-app.
Bulk
Send two events in one request.
Windows PowerShell:
Invoke-RestMethod -Method Post -Uri "https://logs.collector.<REGION>.cloud.solarwinds.com/v1/logs/bulk" -Headers @{ Authorization = "Bearer <TOKEN>"; "X-Otel-Resource-Attr" = "host.name=test-host" } -ContentType "text/plain" -Body "Bulk test line 1`nBulk test line 2"
Linux or macOS:
printf 'Bulk test line 1\nBulk test line 2\n' | curl -X POST "https://logs.collector.<REGION>.cloud.solarwinds.com/v1/logs/bulk" -H "Authorization: Bearer <TOKEN>" -H "Content-Type: text/plain" -H "X-Otel-Resource-Attr: host.name=test-host" --data-binary @-
To send a file, use --data-binary "@app.log". Do not use -d or --data. These remove line breaks from files, and the entire file would arrive as a single line.
In the Logs Explorer, search for Bulk test. You will see two events.
NDJSON
Linux or macOS:
printf '{"level":"info","msg":"NDJSON test 1"}\n{"level":"error","msg":"NDJSON test 2"}\n' | curl -X POST "https://logs.collector.<REGION>.cloud.solarwinds.com/v1/logs/bulk" -H "Authorization: Bearer <TOKEN>" -H "Content-Type: application/x-ndjson" --data-binary @-
Logplex
Windows PowerShell:
$m = "Logplex test message" curl.exe -X POST "https://logs.collector.<REGION>.cloud.solarwinds.com/v1/logs/logplex/<TOKEN>" -H "Content-Type: application/logplex-1" -H "X-Otel-Resource-Attr: host.name=test-host, service.name=test-app" --data-raw "$([Text.Encoding]::UTF8.GetByteCount($m)) $m"
Linux or macOS:
m="Logplex test message" printf '%s %s' "$(printf '%s' "$m" | wc -c)" "$m" | curl -X POST "https://logs.collector.<REGION>.cloud.solarwinds.com/v1/logs/logplex/<TOKEN>" -H "Content-Type: application/logplex-1" -H "X-Otel-Resource-Attr: host.name=test-host, service.name=test-app" --data-binary @-
In the Logs Explorer, search for Logplex test message. The System column shows test-host and the Program column shows test-app.
Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
401 on every request |
Wrong token, or the token belongs to a different region. | Copy the token again from Logs > Destinations, and check <REGION> in the URL. |
413 on bulk requests |
A line is 1 MB or larger, or the request is 5 MB or larger. | Send smaller batches. |
413 on Logplex requests |
The body is not framed, or a frame does not start with a number followed by a space. | Prefix every message with its length in UTF-8 bytes and a space. |
| A Logplex event is missing characters from the end. | The frame length was smaller than the message in UTF-8 bytes, so the event was truncated and the rest of the body discarded. | Compute MSG-LEN in bytes, not characters. |
| A Logplex event shows the message together with its syslog header, and System shows an IP address. | The message was sent in syslog format, which this endpoint stores as plain text. |
Send the message text on its own, and set the names with To send syslog over HTTPS, use |
415
|
Unsupported Content-Type for the endpoint. (For example, application/logplex-1 sent to /v1/logs/bulk, or application/x-ndjson sent to /v1/logs.) |
Use the Content-Type listed for the endpoint. |
| A whole file arrives as one event. | The file was sent to /v1/logs, or with curl -d. |
Send the file to /v1/logs/bulk with --data-binary. |
| Stack traces split into many events | Multiline events were sent to /v1/logs/bulk, where every LF and CR ends an event. |
Replace the line breaks in the message, send each multiline event to /v1/logs, or use application/syslog-frames. See Bulk endpoint. |
| System shows an unexpected value. | No host.name was set. |
Add X-Otel-Resource-Attr: host.name=<NAME>, or ?hostname=<NAME> on the Logplex endpoint. |
| Program is empty. | No service.name was set. |
Add X-Otel-Resource-Attr: service.name=<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.