github.com/projectcontour/contour@v1.28.2/site/content/guides/structured-logs.md (about)

     1  ---
     2  title: How to enable structured JSON logging
     3  layout: page
     4  ---
     5  
     6  This document describes how to configure structured logging for Envoy via Contour.
     7  
     8  ## How the feature works
     9  
    10  Contour allows you to choose from a set of JSON fields that will be expanded into Envoy templates and sent to Envoy.
    11  There is a default set of fields if you enable JSON logging, and you may customize which fields you log.
    12  
    13  The list of available fields are discoverable in the following objects:
    14  - [JSONFields][1] are fields that have built in mappings to commonly used envoy
    15    operators.
    16  - [envoySimpleOperators][2] are the names of simple envoy operators that don't
    17    require arguments, they are case-insensitive when configured.
    18  - [envoyComplexOperators][3] are the names of complex envoy operators that require
    19    arguments.
    20  
    21  The default list of fields is available at [DefaultFields][4].
    22  
    23  ## Enabling the feature
    24  
    25  To enable the feature you have two options:
    26  
    27  - Add `--accesslog-format=json` to your Contour startup line.
    28  - Add `accesslog-format: json` to your configuration file.
    29  
    30  Without any further customization, the [default fields][4] will be used.
    31  
    32  ## Customizing logged fields
    33  
    34  To customize the logged fields, add a `json-fields` list of strings to your
    35  config file.  If the `json-fields` key is not specified, the [default fields][4]
    36  will be configured.
    37  
    38  To use a value from [JSONFields][1] or [envoySimpleOperators][2], simply include
    39  the name of the value in the list of strings. The JSONFields are case-sensitive,
    40  but envoySimpleOperators are not.
    41  
    42  To use [envoyComplexOperators][3] or to use alternative field names, specify strings as
    43  key/value pairs like `"fieldName=%OPERATOR(...)%"`.
    44  
    45  Unknown field names in non key/value fields will result in validation errors, as
    46  will unknown Envoy operators in key/value fields. Note that the
    47  `DYNAMIC_METADATA` and `FILTER_STATE` Envoy logging operators are not supported
    48  at this time due to the complexity of their validation.
    49  
    50  See the [example config file][5] to see this used in context.
    51  
    52  ## Sample configuration file
    53  
    54  Here is a sample config:
    55  
    56  ```yaml
    57  accesslog-format: json
    58  json-fields:
    59    - "@timestamp"
    60    - "authority"
    61    - "bytes_received"
    62    - "bytes_sent"
    63    - "customer_id=%REQ(X-CUSTOMER-ID)%"
    64    - "downstream_local_address"
    65    - "downstream_remote_address"
    66    - "duration"
    67    - "method"
    68    - "path"
    69    - "protocol"
    70    - "request_id"
    71    - "requested_server_name"
    72    - "response_code"
    73    - "response_flags"
    74    - "uber_trace_id"
    75    - "upstream_cluster"
    76    - "upstream_host"
    77    - "upstream_local_address"
    78    - "upstream_service_time"
    79    - "user_agent"
    80    - "x_forwarded_for"
    81  ```
    82  
    83  [1]: https://github.com/projectcontour/contour/blob/main/pkg/config/accesslog.go#L33-L45
    84  [2]: https://github.com/projectcontour/contour/blob/main/pkg/config/accesslog.go#L49-L93
    85  [3]: https://github.com/projectcontour/contour/blob/main/pkg/config/accesslog.go#L97-L102
    86  [4]: https://github.com/projectcontour/contour/blob/main/pkg/config/accesslog.go#L4
    87  [5]: {{< param github_url >}}/tree/{{< param latest_version >}}/examples/contour/01-contour-config.yaml