github.com/projectcontour/contour@v1.28.2/site/content/docs/1.27/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
    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  ## Customizing Access Log Format
    20  
    21  The access log can take two different formats, both can be customized
    22  
    23  * Text based access logs, like shown in the example above.
    24  * Structured JSON logging.
    25  
    26  ### Text Based Access Logging
    27  
    28  Ensure that you have selected `envoy` as the access log format.
    29  Note that this is the default format if the parameters are not given.
    30  
    31  - Add `--accesslog-format=envoy` to your Contour startup line, or
    32  - Add `accesslog-format: envoy` to your configuration file.
    33  
    34  Customize the access log format by defining `accesslog-format-string` in your configuration file.
    35  
    36  ```yaml
    37  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"
    38  ```
    39  After restarting Contour and successful validation of the configuration, the new format will take effect in a short while.
    40  
    41  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`.
    42  
    43  ### Structured JSON Logging
    44  
    45  Contour allows you to choose from a set of JSON fields that will be expanded into Envoy templates and sent to Envoy.
    46  There is a default set of fields if you enable JSON logging, and you may customize which fields you log.
    47  
    48  The list of available fields are discoverable in the following objects:
    49  - [jsonFields][2] are fields that have built in mappings to commonly used envoy operators.
    50  - [envoySimpleOperators][3] are the names of simple envoy operators that don't require arguments, they are case-insensitive when configured.
    51  - [envoyComplexOperators][4] are the names of complex envoy operators that require arguments.
    52  
    53  The default list of fields is available at [DefaultAccessLogJSONFields][5].
    54  
    55  #### Enabling the Feature
    56  
    57  To enable the feature you have two options:
    58  
    59  - Add `--accesslog-format=json` to your Contour startup line.
    60  - Add `accesslog-format: json` to your configuration file.
    61  
    62  Without any further customization, the [default fields][5] will be used.
    63  
    64  #### Customizing Logged Fields
    65  
    66  To customize the logged fields, add a `json-fields` list of strings to your configuration file.
    67  If the `json-fields` key is not specified, the [default fields][5] will be configured.
    68  
    69  To use a value from [jsonFields][2] or [envoySimpleOperators][3], simply include the name of the value in the list of strings.
    70  The jsonFields are case-sensitive, but envoySimpleOperators are not.
    71  
    72  To use [envoyComplexOperators][4] or to use alternative field names, specify strings as key/value pairs like `"fieldName=%OPERATOR(...)%"`.
    73  
    74  Unknown field names in non key/value fields will result in validation errors, as will unknown Envoy operators in key/value fields.
    75  Note that the `DYNAMIC_METADATA` and `FILTER_STATE` Envoy logging operators are not supported at this time due to the complexity of their validation.
    76  
    77  See the [example config file][6] to see this used in context.
    78  
    79  #### Sample Configuration File
    80  
    81  Here is a sample config:
    82  
    83  ```yaml
    84  accesslog-format: json
    85  json-fields:
    86    - "@timestamp"
    87    - "authority"
    88    - "bytes_received"
    89    - "bytes_sent"
    90    - "customer_id=%REQ(X-CUSTOMER-ID)%"
    91    - "downstream_local_address"
    92    - "downstream_remote_address"
    93    - "duration"
    94    - "method"
    95    - "path"
    96    - "protocol"
    97    - "request_id"
    98    - "requested_server_name"
    99    - "response_code"
   100    - "response_flags"
   101    - "uber_trace_id"
   102    - "upstream_cluster"
   103    - "upstream_host"
   104    - "upstream_local_address"
   105    - "upstream_service_time"
   106    - "user_agent"
   107    - "x_forwarded_for"
   108  ```
   109  
   110  ### Logging the route source
   111  
   112  Contour can log the kind, namespace and name of the Kubernetes resource that generated the route for a given access log entry. 
   113  
   114  For text-based access logging, the following command operators can be used:
   115  - `%METADATA(ROUTE:envoy.access_loggers.file:io.projectcontour.kind)%`
   116  - `%METADATA(ROUTE:envoy.access_loggers.file:io.projectcontour.namespace)%`
   117  - `%METADATA(ROUTE:envoy.access_loggers.file:io.projectcontour.name)%`
   118  
   119  For JSON access logging, the following fields can be added (these are Contour-specific aliases to the above command operators):
   120  - `contour_config_kind`
   121  - `contour_config_namespace`
   122  - `contour_config_name`
   123  
   124  ## Using Access Log Formatter Extensions
   125  
   126  Envoy allows implementing custom access log command operators as extensions.
   127  Following extensions are supported by Contour:
   128  
   129  | Command operator | Description |
   130  |------------------|-------------|
   131  | [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. |
   132  | [METADATA][9] | Prints all types of metadata. |
   133  
   134  
   135  
   136  [1]: ../configuration#serve-flags
   137  [2]: https://github.com/search?q=%22var+jsonFields%22+repo%3Aprojectcontour%2Fcontour+path%3Aapis&type=code
   138  [3]: https://github.com/search?q=%22var+envoySimpleOperators%22+repo%3Aprojectcontour%2Fcontour+path%3Aapis&type=code
   139  [4]: https://github.com/search?q=%22var+envoyComplexOperators%22+repo%3Aprojectcontour%2Fcontour+path%3Aapis&type=code
   140  [5]: https://github.com/search?q=%22var+DefaultAccessLogJSONFields%22+repo%3Aprojectcontour%2Fcontour+path%3Aapis&type=code
   141  [6]: {{< param github_url >}}/tree/{{< param latest_version >}}/examples/contour/01-contour-config.yaml
   142  [7]: https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage
   143  [8]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/formatter/req_without_query/v3/req_without_query.proto
   144  [9]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/formatter/metadata/v3/metadata.proto