github.com/projectcontour/contour@v1.28.2/site/content/docs/main/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  #### Omitting Logs with Empty Values
    80  
    81  Contour automatically omits empty fields in Envoy JSON access logs, enhancing clarity and delivering more concise and relevant log outputs by default.
    82  
    83  #### Sample Configuration File
    84  
    85  Here is a sample config:
    86  
    87  ```yaml
    88  accesslog-format: json
    89  json-fields:
    90    - "@timestamp"
    91    - "authority"
    92    - "bytes_received"
    93    - "bytes_sent"
    94    - "customer_id=%REQ(X-CUSTOMER-ID)%"
    95    - "downstream_local_address"
    96    - "downstream_remote_address"
    97    - "duration"
    98    - "method"
    99    - "path"
   100    - "protocol"
   101    - "request_id"
   102    - "requested_server_name"
   103    - "response_code"
   104    - "response_flags"
   105    - "uber_trace_id"
   106    - "upstream_cluster"
   107    - "upstream_host"
   108    - "upstream_local_address"
   109    - "upstream_service_time"
   110    - "user_agent"
   111    - "x_forwarded_for"
   112  ```
   113  
   114  ### Logging the route source
   115  
   116  Contour can log the kind, namespace and name of the Kubernetes resource that generated the route for a given access log entry. 
   117  
   118  For text-based access logging, the following command operators can be used:
   119  - `%METADATA(ROUTE:envoy.access_loggers.file:io.projectcontour.kind)%`
   120  - `%METADATA(ROUTE:envoy.access_loggers.file:io.projectcontour.namespace)%`
   121  - `%METADATA(ROUTE:envoy.access_loggers.file:io.projectcontour.name)%`
   122  
   123  For JSON access logging, the following fields can be added (these are Contour-specific aliases to the above command operators):
   124  - `contour_config_kind`
   125  - `contour_config_namespace`
   126  - `contour_config_name`
   127  
   128  ## Using Access Log Formatter Extensions
   129  
   130  Envoy allows implementing custom access log command operators as extensions.
   131  Following extensions are supported by Contour:
   132  
   133  | Command operator | Description |
   134  |------------------|-------------|
   135  | [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. |
   136  | [METADATA][9] | Prints all types of metadata. |
   137  
   138  
   139  
   140  [1]: ../configuration#serve-flags
   141  [2]: https://github.com/search?q=%22var+jsonFields%22+repo%3Aprojectcontour%2Fcontour+path%3Aapis&type=code
   142  [3]: https://github.com/search?q=%22var+envoySimpleOperators%22+repo%3Aprojectcontour%2Fcontour+path%3Aapis&type=code
   143  [4]: https://github.com/search?q=%22var+envoyComplexOperators%22+repo%3Aprojectcontour%2Fcontour+path%3Aapis&type=code
   144  [5]: https://github.com/search?q=%22var+DefaultAccessLogJSONFields%22+repo%3Aprojectcontour%2Fcontour+path%3Aapis&type=code
   145  [6]: {{< param github_url >}}/tree/{{< param latest_version >}}/examples/contour/01-contour-config.yaml
   146  [7]: https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage
   147  [8]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/formatter/req_without_query/v3/req_without_query.proto
   148  [9]: https://www.envoyproxy.io/docs/envoy/latest/api-v3/extensions/formatter/metadata/v3/metadata.proto