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

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