Skip to content

Latest commit

 

History

History
199 lines (167 loc) · 19.3 KB

LOGS.md

File metadata and controls

199 lines (167 loc) · 19.3 KB
Raw

Logging

Introduction

Upon the execution of Couper all log events are sent to the standard output. You can adjust the appearance and verbosity of the logs with a variety of Settings. There are different Log Types and Fields containing useful information.

We aspire to make Couper as stable as possible so these logs are still subject to change.

Log Types

Type Description
couper_access Provides information about the frontend side of things. Compare Access Fields.
couper_access_tls Provides information about connections via configured https_dev_proxy. Compare Access Fields.
couper_backend Provides information about the backend side of things. Compare Backend Fields.
couper_daemon Provides background information about the execution of Couper. Each printed log of this type contains a message entry describing the current actions of Couper. Compare Daemon Fields.

Fields

Given the large amount of information contained in some logs, it might come handy to change the format or log level (see Settings).

Common Fields

These fields are part of all Log Types and therefore mentioned separately to avoid unnecessary redundancy.

Name Description
"build” git short hash during build time
"level" configured log level, determines verbosity of log
"message” context based, mainly used in couper_daemon
"timestamp" request starting time
"type"  Log Type
"version" release version

Access Fields

These fields are found in the Log Types couper_access and couper_access_tls in addition to the Common Fields.

Name Description
"auth_user"  basic auth username (if provided)
"client_ip"   ip of client
"custom" see Custom Logging
"endpoint"   path pattern of endpoint
"handler"   one of: endpoint, file, spa
"method"   http request method, see Mozilla HTTP Reference for more information
"port"   current port accepting request
"request": field regarding request information
{
"bytes" request body size in bytes
"headers" field regarding keys and values originating from configured keys/header names
"host" request host
"method" http request method, see Mozilla HTTP Reference for more information
"origin" request origin (<proto>://<host>:<port>), for our purposes excluding <proto>:// in printing, see Mozilla HTTP Reference for more information
"path" request path
"proto" request protocol
"status" request status code, see Mozilla HTTP Reference for more information
"tls" TLS used true or false
}
"response": field regarding response information
{
"bytes" response body size in bytes
"headers" field regarding keys and values originating from configured keys/header names
}
"server" server name (defined in couper file)
"status"   response status code, see Mozilla HTTP Reference for more information
"timings": field regarding timing
{
 "total" total time taken
)
“uid" unique request id configurable in Settings
"url" complete url (<proto>://<host>:<port><path> or <origin><path>)

Backend Fields

These fields are found in the Log Type couper_backend in addition to the Common Fields.

Name Description
"auth_user"   backend request basic auth username (if provided)
"backend"   configured name, default if not provided
"custom" see Custom Logging
"method"   http request method, see Mozilla HTTP Reference for more information
"proxy" used system proxy url (if configured), see Proxy Block
"request": field regarding request information
{
"bytes" request body size in bytes
"headers" field regarding keys and values originating from configured keys/header names
"host" request host
"method" http request method, see Mozilla HTTP Reference for more information
"name" configured request name, default if not provided
"origin" request origin, for our purposes excluding <proto>:// in printing, see Mozilla HTTP Reference for more information
"path" request path
"port" current port accepting request
"proto" request protocol
}
 "response": field regarding response information
{
"headers" field regarding keys and values originating from configured keys/header names
"status" response status code, see Mozilla HTTP Reference for more information
}
"status" response status code, see Mozilla HTTP Reference for more information
"timings": field regarding timing
{
"dns" time taken by dns
"tcp" time taken between attempting and establishing tcp connection
"tls" time taken between attempt and success at tls handshake
"total" total time taken
 "ttfb" time to first byte/between establishing connection and receiving first byte
)
"token_request"   entry regarding request for token
"token_request_retry"   how many token_request attempts were made
"uid" unique request id configurable in Settings
"url" complete url (<proto>://<host>:<port><path> or <origin><path>)
"validation" validation result for open api, see OpenAPI Block

Daemon Fields

These fields are found in the Log Type couper_daemon in addition to the Common Fields.

Name Description
"deadline" shutdown parameter, see Health-Check
"delay" shutdown parameter, see Health-Check
"watch": field watching configuration file changes, logs with this field only appear if watch=true, more in Settings
{
"max-retries" maximum retry count, see Global Options
"retry-delay" configured delay of each retry, see Global Options
)

Custom Logging

These fields are defined in the configuration as custom_log_fields attribute in the following blocks:

All custom_log_fields definitions will take place within the couper_access log with the custom field as parent. Except the custom_log_fields defined in a Backend Block which will take place in the couper_backend log.

Example:

server "example" {
  endpoint "/anything" {
    custom_log_fields = {
      origin  = backend_responses.default.json_body.origin
      success = backend_responses.default.status == 200
    }

    proxy {
      backend = "httpbin"
      path = "/anything"
    }
  }
}

definitions {
  backend "httpbin" {
    origin = "https://httpbin.org"

    custom_log_fields = {
      method = request.method
    }
  }
}

Settings

For more information regarding the usage of these settings, compare the Command Line Interface documentation, Couper's Environment Options and/or the Settings Block reference.

Feature Description
log-format Can be set to either common or json output format.
log-level Can be set to one of: panic, fatal, error, warn, info, debug and trace. For more information regarding the usage of each, see the official documentation of Level.
log-pretty Option for log-format=json which pretty prints with basic key coloring.
watch Watch for configuration file changes and reload on modifications. Resulting information manifests in Daemon Logs.