HTTP Configuration

Your log data must not contain any personal data, such as names, email addresses, etc. It is your responsibility to ensure this data is filtered out before being sent to AppSignal, and when identifying a person is necessary that your application uses alternative forms of identification such as a user ID, hash, or pseudonym.

Supported Formats

You can POST logs to AppSignal in several formats.

When writing your own integrations, we recommend that you POST your logs to AppSignal in NDJSON format. This will give you total control over your log attributes, allowing you to set all log fields.

If your service provider limits your log formatting options, if you are, for example, using Heroku or Vercel, you can send your logs formatted in JSON, Logfmt, Plaintext or Syslog instead:

You can find more detailed information about each format in the Log Formatting documentation.

AppSignal will silently drop any message that does not contain the expected format, fields, or incorrect values.

HTTP Configuration for NDJSON

You can POST logs to AppSignal. Your logs must be formatted in NDJSON and sent to the following endpoint:

shell
https://appsignal-endpoint.net/logs/json?api_key=YOUR_LOG_SOURCE_API_KEY

Replacing YOUR_LOG_SOURCE_API_KEY with the key provided when creating a log source.

Required Data

Below is an example of a NDJSON message. You can read more about the data AppSignal requires in the Required Fields section.

Example message

json
{ "timestamp": "2022-06-02T04:17:25.783Z", "group": "organisations", "severity": "warn", "message": "This is a test message", "hostname": "frontend1", "attributes": { "org": "appsignal", "step": 1, "seen_terms": true, "entries": 10.01 } }

Required Fields

AppSignal will silently drop any message that does not contain the fields below or any incorrect values.

The NDJSON payload you send to AppSignal must contain the following fields:

timestamp

A RFC 3339 formatted timestamp with a 3-digit nanosecond precision. RFC stands for Request For Comment and is formatted identically to ISO 8601:

shell
YYYY-MM-DDThh:mm:ss.sss 2022-01-12T07:20:50.52Z

Unlike ISO 8601, T can be replaced with a space: 2022-01-12 07:20:50.52Z.

group

One-word string that allows the user to separate log lines by a certain context (e.g., logs for a specific part of your application, group could be "admin" or "payments").

severity

The severity field accepts the following values: unknown, trace, debug, info, notice, warn, error, critical, alert and fatal.

message

Plaintext message.

hostname

Hostname of the server sending the message.

attributes

Attributes that can be used to filter or search the message, with the following rules:

  • Attributes cannot be nested or contain arrays
  • The following primitives are accepted as values:
    • String: ideally used as "tags," e.g. one-word values
    • Integer: 10
    • Double: 0.01
    • Boolean: true/false

HTTP Configuration for JSON, Logfmt and Plaintext

You can POST logs to AppSignal. Your logs must be formatted in JSON, Logfmt or Plaintext and sent to the following endpoint:

shell
https://appsignal-endpoint.net/logs?api_key=YOUR_LOG_SOURCE_API_KEY

ReplaceYOUR_LOG_SOURCE_API_KEY with the key provided when creating a log source.

We will use the time our servers receive the POST request as the log timestamp. The default severity will be INFO. You can send the hostname, severity and group/appname parameters by appending them to the URL, for example:

shell
https://appsignal-endpoint.net/logs?group=app&hostname=frontend1&severity=debug&api_key=YOUR_LOG_SOURCE_API_KEY

ReplaceYOUR_LOG_SOURCE_API_KEY with the key provided when creating a log source.

You can send multiple log lines by separating each log line with a-formatted message overrides the hostname newline character: \n

Overriding values within a message

When parsing your logs in JSON or Logfmt, you can override your log's hostname, group, and severity fields, as shown in the example below:

shell
hostname=frontend2 group=admin severity=warn this is the rest of the log message

HTTP Configuration for Syslog

You can POST logs to AppSignal. Your logs must be formatted in Syslog and sent to the following endpoint:

shell
https://appsignal-endpoint.net/logs/syslog?api_key=YOUR_LOG_SOURCE_API_KEY

ReplaceYOUR_LOG_SOURCE_API_KEY with the key provided when creating a log source.

The Syslog lines should be separated by a newline character: \n. The log line should be sent in the syslog RFC 5424 (Request For Comment) format:

shell
<%pri%>%protocol-version% %timestamp:::date-rfc3339% %HOSTNAME% %app-name% %procid% %msgid% %msg%\n"