google-cloud-logging
Sends request logs to Google Cloud Logging.
google-cloud-loggingPriority 407What it does
google-cloud-logging sends the records of the requests that reach the route or other object it is added to, to Google Cloud Logging, under the log named in Log ID. The records are collected on the gateway node and sent in batches. The gateway signs in as a Google service account, written here under Written here or read from the host under Read from a file.
A Log format of your own, here or in the plugin metadata, replaces the default record with the fields you name. Log format extra adds fields to the default record only, and is not read while a Log format is set.
When to use it
- The operations team reads the logs of every service in Google Cloud Logging, and the records of the orders API should sit there beside them.
- The gateway's records should stay apart from the backend's, under a log of their own,
gateway-accessfor example. - The service account file is already placed on every gateway host, at
/etc/gateway/google/orders-prod.jsonfor example, and its key should not sit in the route's configuration. - Every route should write the same few fields, the host, the client address, the method, the path, the status and the time, set once in the plugin metadata.
Not for records sent to a collector of your own behind an HTTP endpoint — see http-logger (Sends request logs to an HTTP endpoint in batches), records sent to a Kafka topic — see kafka-logger (Sends request logs to a Kafka topic) or records kept in Tencent Cloud's log service — see tencent-cloud-cls (Sends request logs to Tencent Cloud Log Service).
Set it up
Send request records to Cloud Logging with a service account written here
Under Basics choose Written here and fill Auth config as in the JSON below. Under Behavior set Log ID to gateway-access and fill Resource as in the JSON below.
{
"auth_config": {
"client_email": "gateway-logger@orders-prod.iam.gserviceaccount.com",
"private_key": "<private key PEM>",
"project_id": "orders-prod",
"token_uri": "https://oauth2.googleapis.com/token"
},
"log_id": "gateway-access",
"resource": {
"type": "global"
}
}
More scenarios
Send request records to Cloud Logging with a service account file on the gateway host
Under Basics choose Read from a file and set Auth file to /etc/gateway/google/orders-prod.json. Under Behavior set Log ID to gateway-access.
{
"auth_file": "/etc/gateway/google/orders-prod.json",
"log_id": "gateway-access"
}
Choose the fields every route that carries the plugin writes into its recordenvironment-wide settings
Fill Log format as in the JSON below.
{
"log_format": {
"host": "$host",
"client": "$remote_addr",
"method": "$request_method",
"uri": "$uri",
"status": "$status",
"at": "$time_iso8601"
}
}
Things to know
- Auth file — Auth file and Auth config never go together: a configuration that carries both is refused when you save.
- A configuration that names no service account, with only a Log ID for example, is refused when you save.
- Project ID — A service account written here without its Project ID is refused when you save.
- Scopes — A list that names the same scope twice is refused when you save.
- Resource — A Resource with Labels and no Type 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.
- 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.
- AdviceWhere every gateway host can hold the service account file, choose Read from a file, so the private key stays out of the configuration.
Settings
The fields as the console shows them, section by section.
Basics
Choose one:
Written here
auth_configobjectRequiredauth_config.client_emailstringRequiredauth_config.private_keystringRequiredSent to the engine and never shown again.
auth_config.project_idstringRequiredauth_config.token_uristringRequiredRequired here: a service account written without it is refused. The usual value is https://oauth2.googleapis.com/token.
auth_config.entries_uristringdefault https://logging.googleapis.com/v2/entries:writeauth_config.scopearray of stringsdefault ["https://www.googleapis.com/auth/logging.read","https://www.googleapis.com/auth/logging.write","https://www.googleapis.com/auth/logging.admin","https://www.googleapis.com/auth/cloud-platform"]Read only while Scopes above is absent.
auth_config.scopesarray of stringsWhen both lists are written this one is read and Scope below is not.
Read from a file
auth_filestringRequiredA path on the gateway host to the service account JSON, such as /etc/gateway/gcp.json. It is read at the first request.
Behavior
log_idstringdefault apisix.apache.org%2Flogsresourceobjectdefault {"type":"global"}resource.typestringRequiredresource.labelsobjectssl_verifybooleandefault truelog_formatobject{"host":"$host","client":"$remote_addr","status":"$status","at":"$time_iso8601"}log_format_extraobject{"zone":"eu-west","gateway":"$hostname"}Advanced
batch_max_sizeintegerdefault 1000buffer_durationintegerdefault 60inactive_timeoutintegerdefault 5max_retry_countintegerdefault 0retry_delayintegerdefault 1namestringdefault google-cloud-loggingEnvironment-wide settings
Set once per environment, under Plugins › google-cloud-logging. Every google-cloud-logging in the environment uses these.
log_formatobject{"host":"$host","client":"$remote_addr","status":"$status","at":"$time_iso8601"}log_format_extraobject{"zone":"eu-west","gateway":"$hostname"}max_pending_entriesintegerdefault 8192How many log entries may wait to be sent. While the backlog is above this number, new entries are dropped rather than queued.