github.com/avenga/couper@v1.12.2/docs/website/content/3.observation/logging.md (about) 1 # Logging 2 3 ## Introduction 4 5 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](/observation/logging#settings). There are different [Log Types](#log-types) and [Fields](#fields) containing useful information. 6 7 > We aspire to make Couper as stable as possible so these logs are still subject to change. 8 9 ## Log Types 10 11 | Type | Description | 12 |:--------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 13 | `couper_access` | Provides information about the frontend side of things. Compare [Access Fields](#access-fields). | 14 | `couper_access_tls` | Provides information about connections via configured [https_dev_proxy](/configuration/block/settings). Compare [Access Fields](#access-fields). | 15 | `couper_backend` | Provides information about the backend side of things. Compare [Backend Fields](#backend-fields). | 16 | `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](#daemon-fields). | 17 | `couper_job` | Provides information about [jobs](/configuration/block/job). See [Job Fields](#job-fields). | 18 19 ## Fields 20 21 Given the large amount of information contained in some logs, it might come handy to change the format or log level (see [Settings](/configuration/block/settings)). 22 23 ### Common Fields 24 25 These fields are part of all [Log Types](#log-types) and therefore mentioned separately to avoid unnecessary redundancy. 26 27 | Name | Description | 28 |:--------------|:---------------------------------------------------| 29 | `"build”` | GIT short hash during build time. | 30 | `"level"` | Configured log level, determines verbosity of log. | 31 | `"message”` | Context based, mainly used in `couper_daemon`. | 32 | `"timestamp"` | Request starting time. | 33 | `"type"` | [Log Type](#log-types). | 34 | `"version"` | Release version. | 35 36 ### Access Fields 37 38 These fields are found in the [Log Types](#log-types) `couper_access` and `couper_access_tls` in addition to the [Common Fields](#common-fields). 39 40 | Name | | Description | 41 |:--------------|:------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 42 | `"auth_user"` | | Basic auth username (if provided). | 43 | `"client_ip"` | | IP of client. | 44 | `"custom"` | | See [Custom Logging](#custom-logging). | 45 | `"endpoint"` | | Path pattern of endpoint. | 46 | `"handler"` | | One of: `endpoint`, `file`, `spa`. | 47 | `"method"` | | HTTP request method, see [Mozilla HTTP Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more information. | 48 | `"port"` | | Current port accepting request. | 49 | `"request":` | | Field regarding request information. | 50 | | `{` | | 51 | | `"bytes"` | Request body size in bytes. | 52 | | `"headers"` | Field regarding keys and values originating from configured keys/header names. | 53 | | `"host"` | Request host. | 54 | | `"method"` | HTTP request method, see [Mozilla HTTP Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more information. | 55 | | `"origin"` | Request origin (`<proto>://<host>:<port>`), for our purposes excluding `<proto>://` in printing, see [Mozilla HTTP Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin) for more information. | 56 | | `"path"` | Request path. | 57 | | `"proto"` | Request protocol. | 58 | | `"status"` | Request status code, see [Mozilla HTTP Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) for more information. | 59 | | `"tls"` | TLS used `true` or `false`. | 60 | | `}` | | 61 | `"response":` | | Field regarding response information. | 62 | | `{` | | 63 | | `"bytes"` | Response body size in bytes. | 64 | | `"headers"` | Field regarding keys and values originating from configured keys/header names. | 65 | | `}` | | 66 | `"server"` | | Server name (if defined in couper file). | 67 | `"status"` | | Response status code, see [Mozilla HTTP Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) for more information. | 68 | `"timings":` | | Field regarding timing (ms). | 69 | | `{` | | 70 | | `"total"` | Total time taken. | 71 | | `}` | | 72 | `“uid"` | | Unique request ID configurable in [Settings](/configuration/block/settings). | 73 | `"url"` | | Complete URL (`<proto>://<host>:<port><path>` or `<origin><path>`). | 74 75 ### Backend Fields 76 77 These fields are found in the [Log Type](#log-types) `couper_backend` in addition to the [Common Fields](#common-fields). 78 79 | Name | | Description | 80 |:------------------------|:------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 81 | `"auth_user"` | | Backend request basic auth username (if provided). | 82 | `"backend"` | | Configured name (`default` if not provided). | 83 | `"custom"` | | See [Custom Logging](#custom-logging). | 84 | `"method"` | | HTTP request method, see [Mozilla HTTP Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more information. | 85 | `"proxy"` | | Used system proxy URL (if configured), see [Proxy Block](/configuration/block/proxy). | 86 | `"request":` | | Field regarding request information. | 87 | | `{` | | 88 | | `"bytes"` | Request body size in bytes. | 89 | | `"headers"` | Field regarding keys and values originating from configured keys/header names. | 90 | | `"host"` | Request host. | 91 | | `"method"` | HTTP request method, see [Mozilla HTTP Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods) for more information. | 92 | | `"name"` | Configured request name (`default` if not provided). | 93 | | `"origin"` | Request origin, for our purposes excluding `<proto>://` in printing, see [Mozilla HTTP Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Origin) for more information. | 94 | | `"path"` | Request path. | 95 | | `"port"` | Current port accepting request. | 96 | | `"proto"` | Request protocol. | 97 | | `}` | | 98 | `"response":` | | Field regarding response information. | 99 | | `{` | | 100 | | `"bytes"` | Raw size of read body bytes. | 101 | | `"headers"` | Field regarding keys and values originating from configured keys/header names. | 102 | | `"status"` | Response status code, see [Mozilla HTTP Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) for more information. | 103 | | `}` | | 104 | `"status"` | | Response status code, see [Mozilla HTTP Reference](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status) for more information. | 105 | `"timings":` | | Field regarding timing (ms). | 106 | | `{` | | 107 | | `"dns"` | Time taken by DNS. | 108 | | `"tcp"` | Time taken between attempting and establishing TCP connection. | 109 | | `"tls"` | Time taken between attempt and success at TLS handshake. | 110 | | `"total"` | Total time taken. | 111 | | `"ttfb"` | Time to first byte/between establishing connection and receiving first byte. | 112 | | `}` | | 113 | `"token_request"` | | Entry regarding request for token. | 114 | `"token_request_retry"` | | How many `token_request` attempts were made. | 115 | `"uid"` | | Unique request ID configurable in [Settings](/configuration/block/settings) | 116 | `"url"` | | Complete URL (`<proto>://<host>:<port><path>` or `<origin><path>`). | 117 | `"validation"` | | Validation result for open api, see [OpenAPI Block](/configuration/block/open-api). | 118 119 ### Daemon Fields 120 121 These fields are found in the [Log Type](#log-types) `couper_daemon` in addition to the [Common Fields](#common-fields). 122 123 | Name | | Description | 124 |:-------------|:----------------|:-----------------------------------------------------------------------------------------------------------------------------------------------| 125 | `"deadline"` | | Shutdown parameter, see [Health Check](/observation/health). | 126 | `"delay"` | | Shutdown parameter, see [Health Check](/observation/health). | 127 | `"watch":` | | Field watching configuration file changes, logs with this field only appear if `watch=true`, more in [Settings](/configuration/block/settings). | 128 | | `{` | | 129 | | `"max-retries"` | Maximum retry count, see [Basic Options](/configuration/command-line#basic-options). | 130 | | `"retry-delay"` | Configured delay of each retry, see [Basic Options](/configuration/command-line#basic-options). | 131 | | `}` | | 132 133 ## Job Fields 134 135 The following fields are found in the [log type](#log-types) `couper_daemon` in addition to the [common fields](#common-fields). 136 137 | Name | | Description | 138 |:-------------|:-------------|:-------------------------------------------------------------------------------| 139 | `"name"` | | Job name, label of [`beta_job` block](/configuration/block/job). | 140 | `"timings":` | | Field regarding timing (ms). | 141 | | `{` | | 142 | | `"interval"` | Interval, see [`interval` attribute](/configuration/block/job#attributes). | 143 | | `"total"` | Total time taken. | 144 | | `}` | | 145 | `“uid"` | | Unique request ID configurable in [settings](/configuration/block/settings). | 146 147 ## Custom Logging 148 149 These fields are defined in the configuration as `custom_log_fields` attribute in the following blocks: 150 151 - [Server Block](/configuration/block/server) 152 - [Files Block](/configuration/block/files) 153 - [SPA Block](/configuration/block/spa) 154 - [API Block](/configuration/block/api) 155 - [Endpoint Block](/configuration/block/endpoint) 156 - [Backend Block](/configuration/block/backend) 157 - [Basic Auth Block](/configuration/block/basic_auth) 158 - [JWT Block](/configuration/block/jwt) 159 - [OAuth2 AC (Beta) Block](/configuration/block/beta_oauth2) 160 - [OIDC Block](/configuration/block/oidc) 161 - [SAML Block](/configuration/block/saml) 162 - [Error Handler Block](/configuration/error-handling) 163 164 All `custom_log_fields` definitions will take place within the `couper_access` log with the `custom` field as parent. 165 Except the `custom_log_fields` defined in a [`backend` block](/configuration/block/backend) which will take place 166 in the `couper_backend` log. 167 168 **Example:** 169 170 ```hcl 171 server "example" { 172 endpoint "/anything" { 173 custom_log_fields = { 174 origin = backend_responses.default.json_body.origin 175 success = backend_responses.default.status == 200 176 } 177 178 proxy { 179 backend = "httpbin" 180 path = "/anything" 181 } 182 } 183 } 184 185 definitions { 186 backend "httpbin" { 187 origin = "https://httpbin.org" 188 189 custom_log_fields = { 190 method = request.method 191 } 192 } 193 } 194 ``` 195 196 ## Settings 197 198 For more information regarding the usage of these settings, see the [Command Line Interface](/configuration/command-line) documentation and the [`settings` block reference](/configuration/block/settings). 199 200 | Feature | Description | 201 |:-------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| 202 | `log-format` | Can be set to either `common` or `json` output format. | 203 | `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](https://pkg.go.dev/github.com/sirupsen/logrus@v1.8.1#Level). | 204 | `log-pretty` | Option for `log-format=json` which pretty prints with basic key coloring. | 205 | `watch` | Watch for configuration file changes and reload on modifications. Resulting information manifests in [Daemon Logs](#daemon-fields). |