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.
couper_job	Provides information about jobs. See Job 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 (if defined in couper file).
"status"		Response status code, see Mozilla HTTP Reference for more information.
"timings":		Field regarding timing (ms).
	{
	"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.
	{
	"bytes"	Raw size of read body bytes.
	"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 (ms).
	{
	"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 Basic Options.
	"retry-delay"	Configured delay of each retry, see Basic Options.
	}

Job Fields

The following fields are found in the log type couper_daemon in addition to the common fields.

Name		Description
"name"		Job name, label of beta_job block.
"timings":		Field regarding timing (ms).
	{
	"interval"	Interval, see interval attribute.
	"total"	Total time taken.
	}
“uid"		Unique request ID configurable in settings.

Custom Logging

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

• Server Block
• Files Block
• SPA Block
• API Block
• Endpoint Block
• Backend Block
• Basic Auth Block
• JWT Block
• OAuth2 AC (Beta) Block
• OIDC Block
• SAML Block
• Error Handler Block

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, see the Command Line Interface documentation and 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.