file-logger

Writes request logs to a file on the engine's node.

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

What it does

file-logger writes a record of each request that reaches the route or other object it is added to, to a file on the gateway node named under Path. Each line of the file is one record, written as JSON.

The path is relative to the gateway's own directory, logs/orders-access.log for example, and its folder has to exist already. A path the gateway cannot open is saved without complaint, and every line is lost.

When to use it

• The orders API should keep its records in a file of its own on the gateway node, logs/orders-access.log.
• The operations team already collects the log files of the gateway nodes with an agent of its own.
• Every route that carries the plugin should write to one shared file, named once in the plugin metadata.
• A route under test should leave a trace of each request without a collector to send it to.

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

Set it up

Write a record of each request to a file with the fields you choose

The path is relative to the gateway's own directory, and its directory must already exist.

Under Basics set Path to logs/orders-access.log. Under Behavior fill Log format as in the JSON below.

file-logger · as the console saves it

{
  "path": "logs/orders-access.log",
  "log_format": {
    "host": "$host",
    "client": "$remote_addr",
    "method": "$request_method",
    "uri": "$uri",
    "status": "$status",
    "at": "$time_iso8601"
  }
}

More scenarios

Write the records of every route that carries the plugin to one file unless the route names its ownenvironment-wide settings

The path is relative to the gateway's own directory, and its directory must already exist.

Fill Log format as in the JSON below and set Path to logs/requests.log.

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

{
  "path": "logs/requests.log",
  "log_format": {
    "host": "$host",
    "client": "$remote_addr",
    "status": "$status",
    "at": "$time_iso8601"
  }
}

Things to know

• Log format — With the fields of the example, a GET answered 200 is written with method set to GET and status set to 200. The line also carries the route's id under route_id.
• Path — A path the gateway cannot open, whether empty or in a missing folder, is saved without complaint and every line is lost. The environment-wide path in this plugin's metadata is used only when this box is removed through Raw JSON.
• A route whose file-logger carries no path of its own writes to the path in the plugin metadata: the example sends the records of such a route to logs/requests.log.
• Path — Every route carrying this plugin without a path of its own writes here. An empty path is accepted and never opened, and every line those routes would have written is lost.
• Path — A file-logger without a path, here or in the plugin metadata, is refused when you save.
• Match — The console’s form draws one level of conditions; a value that nests deeper is kept as it is and edited in Raw JSON.
• Match — More than twenty groups are 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 — 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.
• AdviceRotate the file with a tool on the gateway node, and where the gateway runs on several nodes, prefer a logger that sends the records to one place.

Settings

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

Basics

PathpathstringRequired

A file the gateway can write to, such as logs/access.log, which is relative to the gateway's own directory.

Behavior

Log formatlog_formatobject

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

Matchmatcharray

up to 20 items · lists of conditions on request variables: see Conditions on request variables

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

Environment-wide settings

Set once per environment, under Plugins › file-logger. Every file-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"}

Pathpathstring

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