loggly

Sends request logs to Loggly.

Category ObservabilityAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin logglyPriority 411

What it does

loggly sends the records of the requests that reach the route or other object it is added to, to a Loggly account named by its Customer token. How they travel is set once in the plugin metadata. Under Protocol, syslog sends each entry to the Host and Port over UDP, while http and https post the records in bulk.

Every entry carries a Severity, INFO unless you change it. The Severity map gives one exact upstream status, 503 for example, a level of its own, and every other status keeps the level above.

When to use it

• The operations team already reads its logs in Loggly, and the request records of the orders API should join them there.
• Records of server errors should stand out: a 500, 502, 503 or 504 from the backend is sent at ERR, every other request at INFO.
• Records should be found by tag, for example gateway and production, beside the logs of other systems in the same account.
• The network lets no syslog traffic out, and the records should travel over HTTPS instead.

Not for records sent to a syslog server you run — see syslog (Sends request logs to a syslog server), records sent to an HTTP collector of your own — see http-logger (Sends request logs to an HTTP endpoint in batches) or records kept in Elasticsearch — see elasticsearch-logger (Sends request logs to an Elasticsearch index).

Set it up

Send tagged records over syslog and raise the severity of server errors

The severity is written into the syslog frame only; over the http or https transport the record goes as plain JSON without it.

Under Basics set Customer token to <secret>. Under Behavior leave Severity at INFO, fill Tags as in the JSON below and fill Severity map as in the JSON below.

loggly · as the console saves it

{
  "customer_token": "<secret>",
  "tags": [
    "gateway",
    "production"
  ],
  "severity": "INFO",
  "severity_map": {
    "500": "ERR",
    "502": "ERR",
    "503": "ERR",
    "504": "ERR"
  }
}

More scenarios

Send the records over HTTPS instead of syslogenvironment-wide settings

Set Protocol to https and leave Timeout at 5000 milliseconds.

loggly environment-wide settings · as the console saves it

{
  "protocol": "https",
  "timeout": 5000
}

Things to know

• Customer token — The token is also part of the address the http and https transports post to.
• Customer token — A token is required: a loggly without one is refused when you save.
• Tags — An empty list of tags is refused when you save.
• Severity map — Each key is one exact upstream status, such as 503, and ranges like 5xx are refused. Other statuses keep the level above.
• Severity map — A status outside the range of HTTP statuses, 600 for example, is refused when you save.
• Severity map — A level that Severity does not offer, FATAL for example, is refused when you save.
• Log format extra — Added to the default record only: while a log format is set, on this object or in the plugin's metadata, the engine writes that format alone and reads nothing here.
• Include request body when — The console’s form draws one level of conditions; a value that nests deeper is kept as it is and edited in Raw JSON.
• Include response body when — The console’s form draws one level of conditions; a value that nests deeper is kept as it is and edited in Raw JSON.
• Batch size — A batch goes out when it holds Batch size records, when its first record has waited Buffer duration, or when nothing new arrived for Inactive timeout.
• In the plugin metadata, Protocol accepts only http, https and syslog; tcp is refused when you save.
• Protocol — Syslog sends each entry to the host and port over UDP; http and https post a bulk batch to an address built from the host and the customer token.
• In the plugin metadata, Pending entry limit caps the backlog. While more entries than this wait to be sent, new ones are dropped rather than queued.
• AdviceChoose https in the plugin metadata when the records leave your network, as the second example does.
• AdviceTurn on the request and response bodies only on routes whose records may hold what clients and the backend send.

Settings

The fields as the console shows them, section by section.

Basics

Customer tokencustomer_tokenstringRequired

The customer token of your Loggly account. It is also part of the address the http and https transports post to. Stored on the engine and shown only to roles that manage this object.

Behavior

Severityseveritystringdefault INFO

The level every entry carries, in upper or lower case. Mixed case such as Info is refused.

one of ALERT, CRIT, DEBUG, EMEGR, ERR, INFO, NOTICE, WARNING, alert, crit, debug, emegr, err, info, notice, warning

Tagstagsarray of stringsdefault ["apisix"]

A tag may not begin with tag=, which is the prefix the syslog frame writes around each one itself.

at least 1 item

Severity mapseverity_mapobject

The values are the same level names as above, read in either case. An object whose keys are a name matching ^[1-5][0-9]{2}$, each with a string as its value.

SSL verifyssl_verifybooleandefault true

Checked only on the https transport. Over syslog nothing is verified.

Log formatlog_formatobject

example {"host":"$host","client":"$remote_addr","status":"$status","at":"$time_iso8601"}

Log format extralog_format_extraobject

example {"zone":"eu-west","gateway":"$hostname"}

Include request bodyinclude_req_bodybooleandefault false

Include request body wheninclude_req_body_exprarray

at least 1 item · conditions on request variables: see Conditions on request variables

Include response bodyinclude_resp_bodybooleandefault false

Include response body wheninclude_resp_body_exprarray

at least 1 item · conditions on request variables: see Conditions on request variables

Request body limitmax_req_body_bytesintegerdefault 524288

at least 1

Response body limitmax_resp_body_bytesintegerdefault 524288

at least 1

Advanced

Batch sizebatch_max_sizeintegerdefault 1000

at least 1

Buffer durationbuffer_durationintegerdefault 60

at least 1 · in seconds

Inactive timeoutinactive_timeoutintegerdefault 5

at least 1 · in seconds

Retriesmax_retry_countintegerdefault 0

at least 0

Retry delayretry_delayintegerdefault 1

at least 0 · in seconds

Namenamestringdefault loggly

Environment-wide settings

Set once per environment, under Plugins › loggly. Every loggly in the environment uses these.

Hosthoststringdefault logs-01.loggly.com

Over syslog the host of the receiver; over http and https the account host the bulk address is built from, with or without a scheme.

Log formatlog_formatobject

example {"host":"$host","client":"$remote_addr","status":"$status","at":"$time_iso8601"}

Log format extralog_format_extraobject

example {"zone":"eu-west","gateway":"$hostname"}

Pending entry limitmax_pending_entriesintegerdefault 8192

How many log entries may wait to be sent. While the backlog is above this number, new entries are dropped rather than queued.

at least 1

Portportintegerdefault 514

Read on the syslog transport alone; a bulk address carries its own port.

Protocolprotocolstringdefault syslog

one of http, https, syslog

Timeouttimeoutintegerdefault 5000

One timeout, applied to the syslog socket and to the bulk request alike.

at least 1 · in milliseconds

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.