udp-logger

Sends request logs to a UDP server.

Category ObservabilityAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin udp-loggerPriority 400

What it does

udp-logger sends the records of the requests that reach the route or other object it is added to, as UDP datagrams to a server at Host and Port. The records are collected on the gateway node and sent in batches, so one send can carry several records.

The datagrams travel in plain text, and the form offers no encryption. For records that must travel encrypted, choose tcp-logger with TLS on, or http-logger with an HTTPS address.

When to use it

• A log collector of the operations team listens on a UDP port inside the gateway network, for example logs.internal on port 5140.
• The records of a busy route, the orders API for example, should leave the gateway without a connection to keep open.
• Every route should send the same few fields, the client, method, path, status and time, set once in the plugin metadata.

Not for records sent over a TCP connection, encrypted if needed — see tcp-logger (Sends request logs to a TCP server), records sent to a syslog server — see syslog (Sends request logs to a syslog server) or records sent to an HTTP collector — see http-logger (Sends request logs to an HTTP endpoint in batches).

Set it up

Send request records to a UDP collector

Under Basics set Host to logs.internal and set Port to 5140. Under Behavior set Timeout to 2 seconds.

udp-logger · as the console saves it

{
  "host": "logs.internal",
  "port": 5140,
  "timeout": 2
}

More scenarios

Shape the record every route sends to the UDP collectorenvironment-wide settings

Fill Log format as in the JSON below.

udp-logger environment-wide settings · as the console saves it

{
  "log_format": {
    "client": "$remote_addr",
    "method": "$request_method",
    "path": "$uri",
    "status": "$status",
    "at": "$time_iso8601"
  }
}

Things to know

• Port — The records arrive as UDP datagrams on this port, 5140 in the example.
• Port — A port of 0 or above 65535 is refused when you save.
• A Log format in the plugin metadata shapes the record of every route whose udp-logger names no Log format of its own. In the example each record carries path with the path the client asked for.
• 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.
• Timeout — A whole number of seconds: a fraction, 1.5 for example, is refused when you save.
• Include request body when — Not checked at save: an expression the engine cannot read is stored, and the body is then never logged. Only the gateway's error log says so.
• Include response body when — Not checked at save: an expression the engine cannot read is stored, and the body is then never logged. Only the gateway's error log says so.
• 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, Pending entry limit caps the backlog. While more entries than this wait to be sent, new ones are dropped rather than queued.
• AdviceSend records over UDP only to a collector inside your own network.
• AdviceTurn on the request and response bodies only on routes whose collector is meant to hold what clients and the backend send.

Settings

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

Basics

HosthoststringRequired

PortportintegerRequired

1 to 65535

Behavior

Timeouttimeoutintegerdefault 3

at least 1 · in seconds

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 udp logger

Environment-wide settings

Set once per environment, under Plugins › udp-logger. Every udp-logger in the environment uses these.

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

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