> For the complete documentation index, see [llms.txt](https://docs.espresso.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.espresso.ai/snowflake-optimizer/proxy-onboarding/proxy-telemetry-reference.md).

# Telemetry reference

The Espresso AI proxy emits OpenTelemetry metrics, and logs over OTLP. When deployed with chart `v0.3.0` / proxy-tf `v0.4.0` or later, that traffic flows through the in-pod OTEL Collector sidecar and can be mirrored to a customer-owned OTLP backend (see [`otelCollector`](/snowflake-optimizer/proxy-onboarding/proxy-onboarding-helm-deployment.md#telemetry-collector) for Helm and [`otel_collector`](/snowflake-optimizer/proxy-onboarding/proxy-onboarding-terraform-deployment-aws.md#otel_collector) for Terraform).

This page lists what to expect on that customer-side stream so you can build dashboards and alerts against it.

## Resource attributes

The following resource attributes are attached to every signal emitted by the proxy:

| Attribute                | Value                                                   | Source                                                                                                    |
| ------------------------ | ------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `service.name`           | `proxy`                                                 | Baked into the proxy image.                                                                               |
| `deployment.environment` | `prod`                                                  | Derived from the `ENV` env var, which the chart and Terraform module set to `PROD`.                       |
| `customer`               | The customer identifier you supplied during onboarding. | Derived from the `CUSTOMER` env var, which the chart and Terraform module wire from the `customer` value. |

Standard OpenTelemetry SDK resource attributes (`telemetry.sdk.name`, `telemetry.sdk.language=python`, `telemetry.sdk.version`, `process.runtime.*`, host attributes) are also present.

## Metrics

The proxy emits two custom metrics on top of any standard runtime metrics produced by the OpenTelemetry Python SDK.

| Metric                         | Instrument       | Unit           | Description                                                                                       | Attributes                                                     |
| ------------------------------ | ---------------- | -------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `proxy_httpx_pool_connections` | Observable gauge | `{connection}` | Snapshot of the httpx connection pool used to talk to Snowflake, sliced by connection state.      | `pool` (logical pool name), `state` ∈ `open`, `active`, `idle` |
| `proxy_httpx_pool_requests`    | Observable gauge | `{request}`    | Snapshot of the httpx pool's request queue. Emitted only when the pool exposes its request queue. | `pool`, `state` = `queued`                                     |
| `proxy_endpoint_responses`     | counter          | `{response}`   | Status Code counter for the Proxy service's responses.                                            | `status_code`                                                  |

Use these to alert on pool saturation (`state=queued` rising, or `state=active` approaching the pool's configured limit).

## Logs

The proxy ships Python `logging` records as OTLP log records. Each log record carries the resource attributes above, the standard `severity_text` / `severity_number` and the originating logger name.

## How to subscribe

To receive these signals at your own OTLP backend, set the customer exporter on the OTEL Collector sidecar:

* **Helm** — set `otelCollector.customer.endpoint` (and optionally `customer.protocol`, `customer.signals`, `customer.authSecret`, `customer.tls.insecure`). See [Telemetry collector](/snowflake-optimizer/proxy-onboarding/proxy-onboarding-helm-deployment.md#telemetry-collector).
* **Terraform** — set `proxy_config.otel_collector.customer_endpoint` (and the matching `customer_*` fields). See the `otel_collector` reference on the [AWS](/snowflake-optimizer/proxy-onboarding/proxy-onboarding-terraform-deployment-aws.md#otel_collector) and [Azure](/snowflake-optimizer/proxy-onboarding/proxy-onboarding-terraform-deployment-azure.md#otel_collector) pages.

By default the customer exporter mirrors both signals (`metrics`, `logs`); narrow with `customer.signals` / `customer_signals` if you only want a subset.

To point each sidecar at a customer collector running on its own node, inject the node IP with `otelCollector.env` and reference it from the endpoint via the collector's `${env:NAME}` substitution. See [Per-node customer collector](/snowflake-optimizer/proxy-onboarding/proxy-onboarding-helm-deployment.md#telemetry-collector).