github.com/projectcontour/contour@v1.28.2/site/content/docs/1.20/config/access-logging.md (about)

     1  # Access Logging
     2  
     3  ## Overview
     4  
     5  Contour allows you to control Envoy's access logging.
     6  By default, HTTP and HTTPS access logs are written to `/dev/stdout` by the Envoy containers and look like following:
     7  
     8  ```
     9  [2021-04-14T16:36:00.361Z] "GET /foo HTTP/1.1" 200 - 0 463 6 3 "-" "HTTPie/1.0.3" "837aa8dc-344f-4faa-b7d5-c9cce1028519" "localhost:8080" "127.0.0.1:8081"
    10  ```
    11  
    12  The detailed description of each field can be found in [Envoy access logging documentation][7].
    13  
    14  
    15  ## Customizing Access Log Destination and Formats
    16  
    17  You can change the destination file where the access log is written by using Contour [command line parameters][1] `--envoy-http-access-log` and `--envoy-https-access-log`.
    18  
    19  The access log can take two different formats, both can be customized
    20  
    21  * Text based access logs, like shown in the example above.
    22  * Structured JSON logging.
    23  
    24  ### Text Based Access Logging
    25  
    26  Ensure that you have selected `envoy` as the access log format.
    27  Note that this is the default format if the parameters are not given.
    28  
    29  - Add `--accesslog-format=envoy` to your Contour startup line, or
    30  - Add `accesslog-format: envoy` to your configuration file.
    31  
    32  Customize the access log format by defining `accesslog-format-string` in your configuration file.
    33  
    34  ```yaml
    35  accesslog-format-string: "[%START_TIME%] \"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%\" %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% \"%REQ(X-FORWARDED-FOR)%\" \"%REQ(USER-AGENT)%\" \"%REQ(X-REQUEST-ID)%\" \"%REQ(:AUTHORITY)%\" \"%UPSTREAM_HOST%\"\n"
    36  ```
    37  After restarting Contour and successful validation of the configuration, the new format will take effect in a short while.
    38  
    39  Refer to [Envoy access logging documentation][7] for the description of the command operators, and note that the format string needs to end in a linefeed `\n`.
    40  
    41  ### Structured JSON Logging
    42  
    43  Contour allows you to choose from a set of JSON fields that will be expanded into Envoy templates and sent to Envoy.
    44  There is a default set of fields if you enable JSON logging, and you may customize which fields you log.
    45  
    46  The list of available fields are discoverable in the following objects:
    47  - [jsonFields][2] are fields that have built in mappings to commonly used envoy operators.
    48  - [envoySimpleOperators][3] are the names of simple envoy operators that don't require arguments, they are case-insensitive when configured.
    49  - [envoyComplexOperators][4] are the names of complex envoy operators that require arguments.
    50  
    51  The default list of fields is available at [DefaultFields][5].
    52  
    53  #### Enabling the Feature
    54  
    55  To enable the feature you have two options:
    56  
    57  - Add `--accesslog-format=json` to your Contour startup line.
    58  - Add `accesslog-format: json` to your configuration file.
    59  
    60  Without any further customization, the [default fields][5] will be used.
    61  
    62  #### Customizing Logged Fields
    63  
    64  To customize the logged fields, add a `json-fields` list of strings to your configuration file.
    65  If the `json-fields` key is not specified, the [default fields][5] will be configured.
    66  
    67  To use a value from [jsonFields][2] or [envoySimpleOperators][3], simply include the name of the value in the list of strings.
    68  The jsonFields are case-sensitive, but envoySimpleOperators are not.
    69  
    70  To use [envoyComplexOperators][4] or to use alternative field names, specify strings as key/value pairs like `"fieldName=%OPERATOR(...)%"`.
    71  
    72  Unknown field names in non key/value fields will result in validation errors, as will unknown Envoy operators in key/value fields.
    73  Note that the `DYNAMIC_METADATA` and `FILTER_STATE` Envoy logging operators are not supported at this time due to the complexity of their validation.
    74  
    75  See the [example config file][6] to see this used in context.
    76  
    77  #### Sample Configuration File
    78  
    79  Here is a sample config:
    80  
    81  ```yaml
    82  accesslog-format: json
    83  json-fields:
    84    - "@timestamp"
    85    - "authority"
    86    - "bytes_received"
    87    - "bytes_sent"
    88    - "customer_id=%REQ(X-CUSTOMER-ID)%"
    89    - "downstream_local_address"
    90    - "downstream_remote_address"
    91    - "duration"
    92    - "method"
    93    - "path"
    94    - "protocol"
    95    - "request_id"
    96    - "requested_server_name"
    97    - "response_code"
    98    - "response_flags"
    99    - "uber_trace_id"
   100    - "upstream_cluster"
   101    - "upstream_host"
   102    - "upstream_local_address"
   103    - "upstream_service_time"
   104    - "user_agent"
   105    - "x_forwarded_for"
   106  ```
   107  
   108  ## Using Access Log Formatter Extensions
   109  
   110  Envoy allows implementing custom access log command operators as extensions.
   111  Following extensions are supported by Contour:
   112  
   113  | Command operator | Description |
   114  |------------------|-------------|
   115  | [REQ_WITHOUT_QUERY][8] | Works the same way as REQ except that it will remove the query string. It is used to avoid logging any sensitive information into the access log. |
   116  
   117  
   118  
   119  [1]: ../configuration#serve-flags
   120  [2]: https://github.com/search?q=jsonFields+repo%3Aprojectcontour%2Fcontour+path%3A%2Fpkg%2Fconfig+filename%3Aaccesslog.go&type=Code
   121  [3]: https://github.com/search?q=envoySimpleOperators+repo%3Aprojectcontour%2Fcontour+path%3A%2Fpkg%2Fconfig+filename%3Aaccesslog.go&type=Code
   122  [4]: https://github.com/search?q=envoyComplexOperators+repo%3Aprojectcontour%2Fcontour+path%3A%2Fpkg%2Fconfig+filename%3Aaccesslog.go&type=Code
   123  [5]: https://github.com/search?q=DefaultFields+repo%3Aprojectcontour%2Fcontour+path%3A%2Fpkg%2Fconfig+filename%3Aaccesslog.go&type=Code
   124  [6]: {{< param github_url >}}/tree/{{< param latest_version >}}/examples/contour/01-contour-config.yaml
   125  [7]: https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage
   126  [8]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/formatter/req_without_query/v3/req_without_query.proto