# Envoy Logs

## Overview

Panther supports ingesting [Envoy access](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage) logs by streaming them to an [HTTP Source](https://docs.panther.com/data-onboarding/data-transports/http), after they are forwarded with [Fluent Bit.](https://docs.fluentbit.io/manual/)

## How to onboard Envoy logs to Panther

### Step 1: Create a new Envoy log source in Panther

1. In the left-side navigation bar of your Panther Console, click **Configure** > **Log Sources.**
2. Click **Create New**.
3. Search for "Envoy," then click its tile.
   * In the slide-out panel, the **Transport Mechanism** dropdown in the upper-right corner will be pre-populated with the **HTTP** option.
4. Click **Start Setup**.
5. Follow Panther's [instructions for configuring an HTTP Source](https://docs.panther.com/data-transports/http#how-to-set-up-an-http-log-source-in-panther), beginning at Step 5.
   * When setting the **Auth method** for the source, we recommend using [**Shared Secret**](https://docs.panther.com/data-transports/http#shared-secret). Save the header name and value in a secure location, as you will need them in Step 3.
   * Payloads sent to this source are subject to the [payload requirements for all HTTP sources](https://docs.panther.com/data-transports/http#payload-requirements).
   * Do not proceed to the next step until the creation of your HTTP endpoint has completed.

### Step 2: Configure Envoy Logging

{% hint style="info" %}
While it's possible to customize your Envoy logs by adding or removing fields, Panther's [Envoy.Access schema](#envoy.access) is built to support the default log format. To prevent classification failures, use the default format for your log configuration.
{% endhint %}

1. Make the following additions to your `envoy.yml` configuration file:
   * At the root level, add the following snippet to enable admin access logging:

     ```yaml
     admin:
       access_log_path: "access.log"
     ```
   * Within the resources section, add the following snippet to each resource(s) you wish to enable access logging for:

     ```yaml
      access_log:
      - name: envoy.access_loggers.file
        typed_config:
          "@type": type.googleapis.com/envoy.extensions.access_loggers.file.v3.FileAccessLog
          path: "access.log"
     ```

{% hint style="info" %}
If you customize the access log file path (`access.log` above), make sure to also point to the appropriate location in your Fluent Bit configuration.
{% endhint %}

2. Restart your Envoy proxy, ensuring it is pointing to this updated configuration file, by running `envoy -c envoy.yml`.

### Step 3: Configure Fluent Bit

1. Follow the [Getting Started with Fluent Bit instructions](https://docs.fluentbit.io/manual/installation/getting-started-with-fluent-bit) to install Fluent Bit as a service.
2. Create a [Fluent Bit configuration file](https://docs.fluentbit.io/manual/administration/configuring-fluent-bit/classic-mode/configuration-file), and set the following fields:

   * `[INPUT]` variables:
     * **Name:** Set to `tail`.
     * **Path**: Set to the path to your log file.
     * **Parser**: Set to `envoy`.
   * `[OUTPUT]` variables:
     * **Host**: Enter your Panther URL.
       * Example: `logs.instance-name.runpanther.net`
     * **URI**: Enter the end of the HTTP Source ingest URL (generated in Step 1 of this process), starting with `/http/`.
       * Example: `/http/cb015ee4-543c-4489-9f4b-testaa16d7a`
     * **Header**: Enter the header name you created and the secret you generated while configuring your HTTP source in the Panther Console in Step 1.
     * **Format**: Set to `json_lines`
     * **Name**: Set to `http`.
     * **TLS**: Set to `ON`.
     * **Port**: Set to `443`.

   ```editorconfig
   [SERVICE]
       Flush      1
   [INPUT]
       Name       tail
       # This path depends on your envoy.yml configuration
       Path       /var/log/envoy/access.log
       Parser     envoy

   [OUTPUT]
       Name       http
       Match      *
       Host       logs.pre-alpha.runpanther.net
       Port       443
       URI        /http/6897ec53-9c4c-4fc7-a8c8-faf7b29571de
       # Ensure the x-sender-header name matches the header name
       # you provided when creating the HTTP source in Panther
       Header     x-sender-header {YOUR_SECRET_HERE}
       Format     json_lines
       TLS        On
       TLS.Verify On
   ```
3. Start Fluent Bit, passing the path to your new configuration file and the path to the `parsers.conf` file. The `envoy` parser is available with the default parser configuration that ships with Fluent Bit.
   * Example: `fluent-bit -c fluent.conf -R /var/etc/fluent-bit/parsers.conf`

## Supported Log Types

### Envoy.Access

The following defines the Envoy access log schema:

```yaml
schema: Envoy.Access
description: Envoy access logs over HTTP using FluentBit
fields:
  - name: start_time
    description: Start time of the request.
    type: timestamp
    timeFormats:
      - rfc3339
    isEventTime: true
  - name: method
    description: HTTP request method, such as GET, POST, etc.
    type: string
  - name: path
    description: The URI path of the request.
    type: string
  - name: protocol
    description: The HTTP protocol version.
    type: string
  - name: code
    description: The HTTP status code of the response.
    type: string
  - name: response_flags
    description: Additional flags related to the response.
    type: string
  - name: bytes_received
    description: Bytes received from the client.
    type: string
  - name: bytes_sent
    description: Bytes sent to the client.
    type: string
  - name: duration
    description: Total duration of the request.
    type: string
  - name: x_envoy_upstream_service_time
    description: Time spent in the upstream service.
    type: string
  - name: x_forwarded_for
    description: X-Forwarded-For header (if present).
    type: string
  - name: user_agent
    description: User-agent string from the request header.
    type: string
  - name: request_id
    description: The request ID header value.
    type: string
  - name: authority
    description: The authority header value.
    type: string
  - name: upstream_host
    description: The upstream host selected for the request.
    type: string
```