# Proxy telemetry reference

The Espresso AI proxy emits OpenTelemetry traces, 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.

## Traces

The proxy creates one explicit parent span per inbound Snowflake-protocol request, named after the route handler. The complete list:

| Span name                    | Inbound route                                                       | Notes                                                 |
| ---------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------- |
| `handle_sql_v0`              | `/v0/queries{...}`                                                  | Espresso AI's own SQL endpoint.                       |
| `handle_sql`                 | `/queries/v1/query-request`                                         | Snowflake JDBC / Python connector primary query path. |
| `handle_sql_v2`              | `/api/v2/statements`                                                | Snowflake SQL API v2 query submission.                |
| `handle_statement_status_v2` | `/api/v2/statements/{query_id}`                                     | Snowflake SQL API v2 polling / fetch.                 |
| `handle_results`             | `/queries/{query_id}/result`                                        | Result-set retrieval for the v1 protocol.             |
| `handle_login`               | `/session/v1/login-request`                                         | Snowflake connector authentication.                   |
| `handle_token_request`       | `/session/token-request`                                            | Snowflake connector token refresh.                    |
| `handle_session`             | `/session`                                                          | Snowflake session lifecycle.                          |
| `handle_apps_sql`            | `/v1/queries` and `/pep.workspace.v1.WorkspaceService/ExecuteQuery` | Snowpark / Snowflake Apps execution.                  |
| `proxy`                      | Any other path                                                      | Pass-through catch-all.                               |

## 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`                                     |

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`, the originating logger name, and — when emitted from inside a span — the active `trace_id` and `span_id`, so you can pivot from a slow query span directly into the proxy's structured log output for that request.

## 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 all three signals (`traces`, `metrics`, `logs`); narrow with `customer.signals` / `customer_signals` if you only want a subset.


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.