> 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).

# Proxy 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).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.espresso.ai/snowflake-optimizer/proxy-onboarding/proxy-telemetry-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.