- HTTPProxy Fundamentals
- Ingress v1 Support
- Virtual Hosts
- Inclusion and Delegation
- TLS Termination
- Upstream TLS
- Request Routing
- External Service Routing
- Request Rewriting
- Upstream Health Checks
- Client Authorization
- TLS Delegation
- Rate Limiting
- Access logging
- Annotations Reference
- Cookie Rewriting
- API Reference
- Deployment Options
- Contour Configuration
- Upgrading Contour
- Enabling TLS between Envoy and Contour
- Redeploy Envoy
- AWS with NLB
- External Authorization
- JSON logging
- Migrating to HTTPProxy
- Prometheus Metrics
- PROXY Protocol Support
- Resource Limits
- Envoy Administration Access
- Contour Debug Logging
- Envoy Debug Logging
- Visualize the Contour Graph
- Show Contour xDS Resources
- Profiling Contour
- Contour Operator
- Support Policy
- Compatibility Matrix
- Contour Deprecation Policy
- Release Process
- Frequently Asked Questions
Contour allows you to control Envoy’s access logging.
By default, HTTP and HTTPS access logs are written to
/dev/stdout by the Envoy containers and look like following:
[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"
The detailed description of each field can be found in Envoy access logging documentation.
Customizing Access Log Destination and Formats
You can change the destination file where the access log is written by using Contour
command line parameters
The access log can take two different formats, both can be customized
- Text based access logs, like shown in the example above.
- Structured JSON logging.
Text Based Access Logging
Ensure that you have selected
envoy as the access log format.
Note that this is the default format if the parameters are not given.
--accesslog-format=envoyto your Contour startup line, or
accesslog-format: envoyto your configuration file.
Customize the access log format by defining
accesslog-format-string in your configuration file.
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"
After restarting Contour and successful validation of the configuration, the new format will take effect in a short while.
Envoy access logging documentation for the description of the command operators, and note that the format string needs to end in a linefeed
Structured JSON Logging
Contour allows you to choose from a set of JSON fields that will be expanded into Envoy templates and sent to Envoy. There is a default set of fields if you enable JSON logging, and you may customize which fields you log.
The list of available fields are discoverable in the following objects:
- jsonFields are fields that have built in mappings to commonly used envoy operators.
- envoySimpleOperators are the names of simple envoy operators that don’t require arguments, they are case-insensitive when configured.
- envoyComplexOperators are the names of complex envoy operators that require arguments.
The default list of fields is available at DefaultFields.
Enabling the Feature
To enable the feature you have two options:
--accesslog-format=jsonto your Contour startup line.
accesslog-format: jsonto your configuration file.
Without any further customization, the default fields will be used.
Customizing Logged Fields
To customize the logged fields, add a
json-fields list of strings to your configuration file.
json-fields key is not specified, the
default fields will be configured.
To use a value from jsonFields or envoySimpleOperators, simply include the name of the value in the list of strings. The jsonFields are case-sensitive, but envoySimpleOperators are not.
envoyComplexOperators or to use alternative field names, specify strings as key/value pairs like
Unknown field names in non key/value fields will result in validation errors, as will unknown Envoy operators in key/value fields.
Note that the
FILTER_STATE Envoy logging operators are not supported at this time due to the complexity of their validation.
See the example config file to see this used in context.
Sample Configuration File
Here is a sample config:
accesslog-format: json json-fields: - "@timestamp" - "authority" - "bytes_received" - "bytes_sent" - "customer_id=%REQ(X-CUSTOMER-ID)%" - "downstream_local_address" - "downstream_remote_address" - "duration" - "method" - "path" - "protocol" - "request_id" - "requested_server_name" - "response_code" - "response_flags" - "uber_trace_id" - "upstream_cluster" - "upstream_host" - "upstream_local_address" - "upstream_service_time" - "user_agent" - "x_forwarded_for"
Using Access Log Formatter Extensions
Envoy allows implementing custom access log command operators as extensions. Following extensions are supported by Contour:
|REQ_WITHOUT_QUERY||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.|