# Traffic Log

With the Traffic Log policy you can easily set up access logs on every data plane in a mesh.

This policy only records outbound traffic. It doesn't record inbound traffic.

To configure access logs in Kuma you need to:

In the rest of this page we assume you have already configured your observability tools to work with Kuma. If you haven't already read the observability docs.

# Add a logging backend

A logging backend is essentially a sink for access logs.

Currently, it can be either a file or a TCP log collector, such as Logstash, Splunk or other.

    # Add a TrafficLog resource

    You need to create a TrafficLog policy to select a subset of traffic and write its access logs into one of the backends configured for that mesh.

      When backend field is omitted, the logs will be forwarded into the defaultBackend of that Mesh.

      # Matching

      TrafficLog is an Outbound Connection Policy. For this reason the only supported value for destinations.match is kuma.io/service.

      # Logging external services

      When running Kuma on Kubernetes you can also log the traffic to external services. To do it, the matched destination section has to have wildcard * value. In such case %KUMA_DESTINATION_SERVICE% will have value external and %UPSTREAM_HOST% will have an IP of the service.

      # Builtin Gateway support

      Traffic Log is a Kuma outbound connection policy, so Kuma chooses a Traffic Log policy by matching the service tag of the data plane's outbounds. Since a builtin gateway data plane does not have outbounds, Kuma always uses the builtin service name pass_through to match the Traffic Log policy for Gateways.

      # Access Log Format

      Kuma gives you full control over the format of the access logs.

      The shape of a single log record is defined by a template string that uses command operators (opens new window) to extract and format data about a TCP connection or an HTTP request.

      E.g.,

      %START_TIME% %KUMA_SOURCE_SERVICE% => %KUMA_DESTINATION_SERVICE% %DURATION%
      
      1

      where %START_TIME% and %KUMA_SOURCE_SERVICE% are examples of available command operators.

      All command operators defined by Envoy (opens new window) are supported, along with additional command operators defined by Kuma:

      Command Operator Description
      %KUMA_MESH% name of the mesh in which traffic is flowing
      %KUMA_SOURCE_SERVICE% name of a service that is the source of traffic
      %KUMA_DESTINATION_SERVICE% name of a service that is the destination of traffic
      %KUMA_SOURCE_ADDRESS_WITHOUT_PORT% address of a Dataplane that is the source of traffic
      %KUMA_TRAFFIC_DIRECTION% direction of the traffic, INBOUND, OUTBOUND or UNSPECIFIED

      # Access Logs for TCP and HTTP traffic

      All access log command operators are valid to use with both TCP and HTTP traffic.

      If a command operator is specific to HTTP traffic, such as %REQ(X?Y):Z% or %RESP(X?Y):Z%, it will be replaced by a symbol "-" in case of TCP traffic.

      Internally, Kuma determines traffic protocol based on the value of kuma.io/protocol tag on the inbound interface of a destination Dataplane.

      The default format string for TCP traffic is:

      [%START_TIME%] %RESPONSE_FLAGS% %KUMA_MESH% %KUMA_SOURCE_ADDRESS_WITHOUT_PORT%(%KUMA_SOURCE_SERVICE%)->%UPSTREAM_HOST%(%KUMA_DESTINATION_SERVICE%) took %DURATION%ms, sent %BYTES_SENT% bytes, received: %BYTES_RECEIVED% bytes
      
      1

      The default format string for HTTP traffic is:

      [%START_TIME%] %KUMA_MESH% "%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)%" "%KUMA_SOURCE_SERVICE%" "%KUMA_DESTINATION_SERVICE%" "%KUMA_SOURCE_ADDRESS_WITHOUT_PORT%" "%UPSTREAM_HOST%"
      
      1

      To provide different format for TCP and HTTP logging you can define two separate logging backends with the same address and different format. Then define two TrafficLog entity, one for TCP and one for HTTP with matching kuma.io/protocol selector.

      # JSON format

      If you need an access log with entries in JSON format, you have to provide a template string that is a valid JSON object, e.g.

      {
        "start_time":          "%START_TIME%",
        "source":              "%KUMA_SOURCE_SERVICE%",
        "destination":         "%KUMA_DESTINATION_SERVICE%",
        "source_address":      "%KUMA_SOURCE_ADDRESS_WITHOUT_PORT%",
        "destination_address": "%UPSTREAM_HOST%",
        "duration_millis":     "%DURATION%",
        "bytes_received":      "%BYTES_RECEIVED%",
        "bytes_sent":          "%BYTES_SENT%"
      }
      
      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      Last Updated: 8/10/2022, 2:45:21 PM