sls-logger

Sends request logs to Alibaba Cloud Log Service.

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

What it does

sls-logger writes the records of the requests that reach the route or other object it is added to, into a logstore of Alibaba Cloud Log Service. It reaches the service at Host and Port, writes into the Logstore of the Project, and signs with the Access key ID and its Access key secret.

The records are collected on the gateway node and sent in batches over a connection that is always TLS. SSL verify decides only whether the service's certificate is checked against the Host.

When to use it

• The company runs its workloads on Alibaba Cloud and searches its logs in Log Service, and the request records of the orders API should join them there.
• The gateway's records belong in a logstore of their own, for example access in the project api-gateway.
• The access key ID stays out of the stored configuration and is read on each gateway node, as $env://SLS_ACCESS_KEY_ID in the example.
• Every route should write the same few fields, the client, method, path, status and time, set once in the plugin metadata.

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

Set it up

Write request records to a logstore in Alibaba Cloud Log Service

SLS_ACCESS_KEY_ID is read from the environment of every gateway node when the configuration loads.

Under Basics set Host to cn-hangzhou.log.aliyuncs.com, set Port to 10009, set Project to api-gateway, set Logstore to access, set Access key ID to $env://SLS_ACCESS_KEY_ID and set Access key secret to <secret>.

sls-logger · as the console saves it

{
  "host": "cn-hangzhou.log.aliyuncs.com",
  "port": 10009,
  "project": "api-gateway",
  "logstore": "access",
  "access_key_id": "$env://SLS_ACCESS_KEY_ID",
  "access_key_secret": "<secret>"
}

More scenarios

Shape the record every route writes to the logstoreenvironment-wide settings

Fill Log format as in the JSON below.

sls-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 — A port of 0 or above 65535 is refused when you save.
• Access key ID — Without an access key ID the plugin is refused when you save.
• Access key secret — Without the secret the plugin is refused when you save.
• Timeout — A whole number of milliseconds: a fraction, 1.5 for example, is refused when you save.
• SSL verify — The connection is always TLS. This switch only decides whether the collector's certificate is checked against the host above.
• 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.
• 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.
• AdviceKeep SSL verify on.
• AdviceTurn on the request and response bodies only on routes whose logstore 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

ProjectprojectstringRequired

LogstorelogstorestringRequired

Access key IDaccess_key_idstringRequired

Access key secretaccess_key_secretstringRequired

Stored on the engine and shown only to roles that manage this object.

Behavior

Timeouttimeoutintegerdefault 5000

at least 1 · in milliseconds

SSL verifyssl_verifybooleandefault true

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

Environment-wide settings

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