skywalking-logger

Sends request logs to Apache SkyWalking.

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

What it does

skywalking-logger sends the records of the requests that reach the route or other object it is added to, to a SkyWalking collector at the Endpoint address. The records are collected on the gateway node and sent in batches, each one a POST to /v3/logs on that host and port.

Each entry names the Service name and the Service instance name, so the collector files the gateway's records beside the traces and logs of your other services. A Log format of your own, here or in the plugin metadata, replaces the default record with the fields you name.

When to use it

• The operations team already follows the backend services in SkyWalking, and the gateway's request records should sit there under a service of their own, api-gateway for example.
• Several gateway nodes send to one collector, and each record should say which node wrote it, with $hostname as the instance name.
• Every route should write the same few fields, the client address, the method, the path, the status and the time, set once in the plugin metadata.
• A route of the orders API should log the request body of some requests only, chosen by a condition.

Not for traces of each request rather than its record — see zipkin (Sends traces to a Zipkin collector), records sent to a collector of your own behind an HTTP endpoint — see http-logger (Sends request logs to an HTTP endpoint in batches) or records sent to a Kafka topic — see kafka-logger (Sends request logs to a Kafka topic).

Set it up

Send request records to a SkyWalking collector under your own service name

Under Basics set Endpoint address to http://skywalking.internal:12800, set Service name to api-gateway and set Service instance name to $hostname.

skywalking-logger · as the console saves it

{
  "endpoint_addr": "http://skywalking.internal:12800",
  "service_name": "api-gateway",
  "service_instance_name": "$hostname"
}

More scenarios

Shape the record every route sends to SkyWalkingenvironment-wide settings

Fill Log format as in the JSON below.

skywalking-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

• Endpoint address — The records arrive as a POST to /v3/logs on the host and port you name.
• Endpoint address — Only the host and the port are read here: the scheme is not, so https opens no TLS connection, and a path is replaced by /v3/logs.
• Endpoint address — An address without its scheme, skywalking.internal:12800 for example, is refused when you save.
• Service name — Each entry the collector receives carries this name as its service, api-gateway in the example.
• A log format in the plugin metadata reaches the records of a route whose skywalking-logger names none of its own. The collector receives that record as JSON text inside each entry, with path set to 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.
• 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, while more entries than the Pending entry limit wait to be sent, new ones are dropped rather than queued.
• 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

Endpoint addressendpoint_addrstringRequired

pattern

^[^\/]+:\/\/([\da-zA-Z.-]+|\[[\da-fA-F:]+\])(:\d+)?

· example http://skywalking.internal:12800

Service nameservice_namestringdefault APISIX

Service instance nameservice_instance_namestringdefault APISIX Instance Name

$hostname is the one value read specially: the gateway writes the host name of the node the entry came from in its place.

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

Environment-wide settings

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