Monitoring Envoy Proxy

Envoy logo

Instana can help you to collect both infrastructure metrics from Envoy Proxy instances and distributed traces of requests that pass through them.

After you install the Instana host agent, Envoy Proxy sensor is automatically installed and configured. You can view the metrics that are related to Envoy Proxy in the Instana UI with a custom dashboard widget. You can view these metrics only after you configure the Envoy Proxy sensor as outlined in the Monitoring configuration of Envoy Proxy section.

For Envoy versions earlier than 1.30, you can use Instana's Distributed Tracing feature. To use the Distributed Tracing feature, you must complete the configuration steps in the Distributed Tracing configuration of Envoy Proxy section.

If you are using Envoy 1.30 or later, you must use Envoy's Otel tracing support and configure it to connect to the Instana backend. An Envoy OTEL demonstration repository is provided at https://github.com/instana/envoy-otel-tracing to assist with the configuration of the Envoy Otel tracing so that traces appear correctly in Instana.

Supported information

Supported operating systems

For Envoy Proxy sensor, the supported operating systems are consistent with host agents' requirements, which can be checked in the "Supported operating systems" section of each host agent, such as Supported operating systems for Linux.

For Envoy Proxy tracing, the following operating systems are supported:

Operating system Architecture Bitness
Alpine Linux x86_64 64 bit
Amazon Linux: 2, 2023, 2022 x86_64 64 bit
CentOS: Centos 7 x86_64 64
Debian: 12, 11, 10 x86_64 64 bit
Ubuntu: LTS x86_64 64 bit

Supported Envoy Proxy versions and platforms

Envoy Proxy sensor and Envoy Proxy tracing have different version and platform requirements.

  • Envoy Proxy sensor supports metrics and configuration data for Envoy Proxy 1.14.1 and later versions with Linux distributions running on x86_64 architecture.

    Envoy Proxy metrics are available only in custom dashboard widgets.

  • Instana provides Distributed Tracing support for the following Envoy Proxy versions and operating systems with a support policy of 45 days:

    • Envoy Proxy 1.15.x to 1.29.x for glibc-based Linux x86_64 with latest tracer binary files (for 1.5.0 or later)
    • Envoy Proxy 1.12.x and 1.13.x for glibc-based and Alpine-based (musl libc) Linux x86_64 with tracer binary 1.3.0.

    Notes:

    • For Distributed Tracing, Envoy Proxy 1.12 and 1.13 are supported by Envoy Proxy sensor 1.3.0. Envoy Proxy sensor 1.5.0 and later versions support only Envoy Proxy 1.15 to 1.29.x. You are encouraged to upgrade Envoy Proxy if you still use its old versions because no feature development is provided for old Envoy Proxy versions.
    • Support for the propagation of W3C Trace Context headers is available from Envoy Tracer 1.8.0.

Monitoring configuration of Envoy Proxy

To collect Envoy Proxy metrics, Instana uses the admin interface. To enable this admin interface, configure your Envoy Proxy server by using an admin interface address based on the admin interface document. Start the server by using the -c <envoy-config-file-path>.yaml or --config-path <envoy-config-file-path>.yaml command-line argument. For example, -c /etc/envoy/envoy.yaml. Containerized environments and YAML configuration parsing are supported since Envoy Proxy sensor 1.1.0.

Monitoring configuration with Envoy Proxy sensor 1.0.2 or earlier

Envoy Proxy sensor 1.0.2 or earlier require the --admin-address-path <path-to-file-envoy-can-write-to> command-line argument additionally. For example, --config-path /etc/envoy/envoy.yaml --admin-address-path /tmp/envoy-admin.address. To make the monitoring work, the Instana agent and Envoy Proxy must run in the same namespace, and the admin IP address 127.0.0.1 must be set. It is encouraged to upgrade the Envoy Proxy sensor.

Viewing metrics

After you complete the configuration steps in the Monitoring configuration of Envoy Proxy section, you can view metrics that are related to Envoy Proxy in the Instana UI.

To view the metrics, complete the following steps:

  1. In the sidebar of the Instana UI, select Infrastructure.
  2. Click a specific monitored host.

Then, you can see a host dashboard with all the collected metrics and monitored processes.

Distributed Tracing configuration of Envoy Proxy

To use Distributed Tracing of Envoy Proxy, complete the following steps:

  1. Download the Instana binary files for the supported distributions of Envoy Proxy in the Envoy Distributed Tracing binary files page.

  2. After the tracer binary file is downloaded, place it to a location that can be read by Envoy Proxy, such as /opt/envoy/libcxx-libinstana_sensor.so. Then, add a tracing section to the configuration YAML file of Envoy Proxy as follows:

    static_resources:
  listeners:
    - address:
      ...
      filter_chains:
        - filters:
            - name: envoy.filters.network.http_connection_manager
              typed_config:
                "@type": type.googleapis.com/envoy.extensions.filters.network.http_connection_manager.v3.HttpConnectionManager
                ...

  3. Configure the path to the tracer binary file with the library key, and configure your service name with the service key as follows:

                    tracing:
                  provider:
                    name: envoy.tracers.dynamic_ot
                    typed_config:
                      "@type": type.googleapis.com/envoy.config.trace.v3.DynamicOtConfig
                      library: /opt/envoy/libcxx-libinstana_sensor.so
                      config:
                        service: your-service-name

For more information, see the official Envoy Proxy documentation.

For how to use Distributed Tracing, refer to the configuration examples at the envoy-tracing repository page.

Envoy Tracing example

Instana provides a public repository to preview the tracing function of Envoy Proxy sensor. For more information, see envoy-tracing.

Troubleshooting

Monitoring issue type: envoy_access_metrics_endpoint_failed

To resolve this issue, configure an admin interface as described in the admin interface document.

Monitoring issue type: envoy_missing_configuration_admin_address_path

To resolve this issue, upgrade the Envoy Proxy sensor of the Instana agent to the latest version. Support for containerized environments and YAML configuration parsing is available since version 1.1.0.