> ## Documentation Index
> Fetch the complete documentation index at: https://docs.snowflake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Observability with Snowflake Cortex

This feature is not available in the People's Republic of China.

## What is AI observability?

AI observability is a collection of features inside Cortex products that help you answer questions about AI workloads in your account, such as what happened in a specific production request, how well the feature performs on test data, what the cost was for a request, and whether Guardrails blocked a request. You might review conversation traces in Snowsight, run batch evaluations on a dataset, or query Account Usage views for credits, tokens, and request metadata such as models and request IDs.

Not every Cortex feature supports the same observability surfaces. Native features such as Cortex Agents expose monitoring and evaluations in Snowsight. Other features expose usage/billing information through Account Usage only. Custom AI applications you host through Snowflake products, or even outside of Snowflake, can stream telemetry information into your account with TruLens.

## Where to start

Use the following paths to find the right documentation:

- **Cortex feature in Snowflake**: See [Observability at a glance](#observability-at-a-glance) and [Native Cortex features](#native-cortex-features) below.
- **Custom AI applications you host**: See [Custom AI application observability with TruLens](#custom-applications-outside-snowflake).
- **Guardrail scans and blocked requests**: [Cortex AI Guardrails](/user-guide/snowflake-cortex/cortex-ai-guardrails) protect **CoCo**, **%sf-intelligence%**, and **Cortex Agents**. See [Cortex AI Guardrails](#label-cortex-ai-guardrails-observability) below and [Monitor guardrail activity](/user-guide/snowflake-cortex/cortex-ai-guardrails#label-cortex-ai-guardrails-monitor).
- **Spend reporting, budgets, and alerts**: See [Cost and governance](#cost-and-governance) and [AI cost management and governance](/user-guide/snowflake-cortex/governance-and-availability/ai-cost-management-and-governance).

For Cortex Agent terms such as thread, turn, trace, and span, see [Terminology](/user-guide/snowflake-cortex/cortex-agents-monitor#label-cortex-agent-observability-terminology).

<a id="observability-at-a-glance"></a>

## Observability at a glance

The following table summarizes what you can observe for each native Cortex feature and where to read more:

| Feature                                     | What you can observe                                                                                       | Documentation                                                                                                                    |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **%sf-intelligence%** and **Cortex Agents** | Live agent threads and traces; batch evaluations on a dataset                                              | [Monitor Cortex Agent requests](/user-guide/snowflake-cortex/cortex-agents-monitor), [Cortex Agent evaluations](/user-guide/snowflake-cortex/cortex-agents-evaluations)               |
| **CoCo**                                    | Prompt traces in the event table; credits, tokens, models, and request IDs in Account Usage                | [Observability](/user-guide/cortex-code/observability), [Daily credit usage limits for CoCo](/user-guide/cortex-code/credit-usage-limit)                                        |
| **Cortex Analyst**                          | Request and response logs; batch evaluations                                                               | [Cortex Analyst administrator monitoring](/user-guide/snowflake-cortex/cortex-analyst/admin-observability), [Cortex Analyst evaluations](/user-guide/snowflake-cortex/cortex-analyst-evaluations) |
| **Cortex Search**                           | Request logs when logging is enabled; query with `GET_AI_OBSERVABILITY_EVENTS` and `CORTEX SEARCH SERVICE` | [Monitor Cortex Search requests](/user-guide/snowflake-cortex/cortex-search/cortex-search-monitor)                                                             |
| **Built-in Cortex AI Functions**            | Credits, tokens, function name, and model per call in Account Usage                                        | [Managing Cortex AI Function costs with Account Usage](/user-guide/snowflake-cortex/ai-func-cost-management)                                                                         |
| **Cortex AI Function Studio**               | Author and evaluate custom AI functions; production usage in Account Usage                                 | [Cortex AI Function Evaluation and Optimization](/user-guide/snowflake-cortex/ai-function-studio)                                                                              |
| **Cortex REST API**                         | Tokens, credits, model, request ID, and inference region per request in Account Usage                      | [](/user-guide/snowflake-cortex/cortex-rest-api#label-cortex-rest-api-monitor-usage)                                             |
| **Cortex AI Guardrails**                    | Guardrail scan activity, tokens, credits, and request metadata in Account Usage                            | [](/user-guide/snowflake-cortex/cortex-ai-guardrails#label-cortex-ai-guardrails-monitor)                                         |

## Native Cortex features

The sections below describe observability for each native feature. For step-by-step procedures, follow the links in each section.

### %sf-intelligence% and Cortex Agents

Cortex Agents deployed through the Agent API or %sf-intelligence% log conversation threads, turns, and execution spans automatically into `SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS`. Use the **Observability** tab or [Monitor Cortex Agent requests](/user-guide/snowflake-cortex/cortex-agents-monitor) to debug production conversations. Use the **Evaluations** tab or [Cortex Agent evaluations](/user-guide/snowflake-cortex/cortex-agents-evaluations) to score an agent on a dataset before or after deployment.

Credit usage appears in [CORTEX_AGENT_USAGE_HISTORY](/sql-reference/account-usage/cortex_agent_usage_history) and [SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY](/sql-reference/account-usage/snowflake_intelligence_usage_history_view). Those views include request IDs, user and agent identifiers, token counts with per-model breakdowns, and a `METADATA` column for interface and role context. Resource and shared budgets are described in [Resource budgets for Cortex Agents](/user-guide/snowflake-cortex/cortex-agents-resource-budgets) and [AI cost management and governance](/user-guide/snowflake-cortex/governance-and-availability/ai-cost-management-and-governance).

### CoCo

CoCo writes span records to `AI_OBSERVABILITY_EVENTS` for each prompt. All three CoCo surfaces (Snowsight, Desktop, and the CLI) are traced the same way, emit the same spans, and use the same access model. For what's captured and how to query it, see [Observability](/user-guide/cortex-code/observability).

Credits, tokens, models, and request IDs for every surface are recorded in [SNOWFLAKE_COCO_USAGE_HISTORY](/sql-reference/account-usage/snowflake_coco_usage_history), whose `INTERFACE` column identifies the originating surface. Per-surface views are also available:

- **Snowsight**: [Observability](/user-guide/cortex-code/cortex-code-snowsight/observability) and [CORTEX_CODE_SNOWSIGHT_USAGE_HISTORY](/sql-reference/account-usage/cortex_code_snowsight_usage_history)
- **Desktop**: [Audit logging and observability](/user-guide/cortex-code/cortex-code-desktop/security#audit-logging-and-observability) and [CORTEX_CODE_DESKTOP_USAGE_HISTORY](/sql-reference/account-usage/cortex_code_desktop_usage_history)
- **CLI**: [CoCo CLI](/user-guide/cortex-code/cortex-code-cli) and [CORTEX_CODE_CLI_USAGE_HISTORY](/sql-reference/account-usage/cortex_code_cli_usage_history)

See also [Cost controls for CoCo](/user-guide/cortex-code/cost-controls) and [daily credit usage limits](/user-guide/cortex-code/credit-usage-limit).

### Cortex Analyst

Cortex Analyst stores **direct** Analyst request and response telemetry in `SNOWFLAKE.LOCAL.CORTEX_ANALYST_REQUESTS_RAW`, not in the shared AI observability event table. When a **Cortex Agent** invokes Analyst as a tool (including agentic Analyst flows), those steps are recorded in `AI_OBSERVABILITY_EVENTS` as part of the agent trace. Administrators can query direct Analyst logs with Analyst-specific SQL or review usage in Account Usage. Batch evaluations use a separate workflow documented in [Cortex Analyst evaluations](/user-guide/snowflake-cortex/cortex-analyst-evaluations).

See [Administrator monitoring](/user-guide/snowflake-cortex/cortex-analyst/admin-observability) for log access and [CORTEX_ANALYST_USAGE_HISTORY](/sql-reference/account-usage/cortex_analyst_usage_history) for billing data, including message counts and request timing metadata.

### Cortex Search

When [`REQUEST_LOGGING`](/user-guide/snowflake-cortex/cortex-search/cortex-search-monitor#label-cortex-search-request-logging) is enabled on a service, Cortex Search writes one event row per request to `AI_OBSERVABILITY_EVENTS`. Query those logs with [GET_AI_OBSERVABILITY_EVENTS](/sql-reference/functions/get_ai_observability_events-snowflake-local) and `agent_type` `CORTEX SEARCH SERVICE` (requires `MONITOR` on the service), or follow the steps in [Monitor Cortex Search requests](/user-guide/snowflake-cortex/cortex-search/cortex-search-monitor). You can also monitor serving usage and credits in Account Usage and configure resource budgets.

See [CORTEX_SEARCH_DAILY_USAGE_HISTORY](/sql-reference/account-usage/cortex_search_daily_usage_history).

### Built-in Cortex AI Functions

Built-in functions such as `AI_COMPLETE` and `AI_CLASSIFY` do not write traces to the observability event table. Monitor credit consumption with [Managing Cortex AI Function costs with Account Usage](/user-guide/snowflake-cortex/ai-func-cost-management) and [CORTEX_AI_FUNCTIONS_USAGE_HISTORY](/sql-reference/account-usage/cortex_ai_functions_usage_history), which records function name, model, warehouse, and token counts per call. You can attach alerts and shared resource budgets as described in that topic.

### Custom AI Functions with Function Studio

[Cortex AI Function Studio](/user-guide/snowflake-cortex/ai-function-studio) helps you create, [evaluate](/user-guide/snowflake-cortex/ai-function-studio#label-cortex-ai-function-studio-evaluate), and optimize custom AI functions in Snowsight or CoCo. Production invocations of registered functions appear in `CORTEX_AI_FUNCTIONS_USAGE_HISTORY` with `CUSTOM_AI_FUNCTION_NAME` in the metrics column.

### Cortex REST API

REST API inference does not write to the observability event table. Monitor token counts, credits, model name, request ID, and inference region with [CORTEX_REST_API_USAGE_HISTORY](/sql-reference/account-usage/cortex_rest_api_usage_history).

See [Monitor usage](/user-guide/snowflake-cortex/cortex-rest-api#label-cortex-rest-api-monitor-usage).

<a id="label-cortex-ai-guardrails-observability"></a>

### Cortex AI Guardrails

[Cortex AI Guardrails](/user-guide/snowflake-cortex/cortex-ai-guardrails) run at request time on [CoCo](/user-guide/cortex-code/cortex-code), [%sf-intelligence%](/user-guide/snowflake-cortex/snowflake-cowork), and [Cortex Agents](/user-guide/snowflake-cortex/cortex-agents). They do not apply to the Cortex REST API or TruLens External Agents.

Built-in functions such as `AI_COMPLETE` also support a separate **`guardrails`** request parameter ([Cortex Guard](/sql-reference/functions/ai_complete-single-string#label-cortex-llm-complete-cortex-guard)) that filters potentially harmful model output. That per-request option is distinct from account-level Cortex AI Guardrails configured through `AI_SETTINGS`.

Guardrail scans are recorded in [CORTEX_AI_GUARDRAILS_USAGE_HISTORY](/sql-reference/account-usage/cortex_ai_guardrails_usage_history), including scan activity, tokens, credits, and request metadata. Flagged scans also appear in Cortex Agent monitoring traces and in CoCo conversation logs.

See [Monitor guardrail activity](/user-guide/snowflake-cortex/cortex-ai-guardrails#label-cortex-ai-guardrails-monitor).

<a id="label-ai-observability-trulens-external-agent"></a>
<a id="custom-applications-outside-snowflake"></a>

## Custom AI application observability with TruLens

Use **TruLens** when you build a **custom AI application** whose observability you own end to end: for example, a standalone agent or workflow, a RAG pipeline that combines Cortex Search with `AI_COMPLETE`, a graph of Cortex Agents, or other compositions that are not served only through native Snowflake monitoring for a single Cortex Agent, Analyst, or Search deployment. You can host the app on Snowflake compute or on other infrastructure. Typical examples include agent or RAG apps on Snowpark Container Services, workloads on another cloud or on-premises, custom retrieval pipelines, or batch evaluations you run from Python instead of Snowsight.

Snowflake registers each TruLens application as an [External Agent](/sql-reference/commands-external-agent) object. That object stores metadata only. Traces and scores live in `SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS`.

- [Trace applications with TruLens](/user-guide/snowflake-cortex/ai-observability/trace-applications-trulens)
- [Evaluate applications with TruLens](/user-guide/snowflake-cortex/ai-observability/evaluate-applications-trulens)
- [Snowflake AI Observability Reference](/user-guide/snowflake-cortex/ai-observability/reference)
- [AI Observability tutorial](/user-guide/snowflake-cortex/ai-observability/tutorial)

View External Agent traces and evaluation runs in %sf-web-interface% under **AI & ML** %raa% **Evaluations**.

## Cost and governance

Credits, tokens, and request metadata (such as model name, request ID, and user ID) for most AI features are recorded in [Account Usage](/sql-reference/account-usage) views. Traces for agents, CoCo, Search, and TruLens are stored separately in `AI_OBSERVABILITY_EVENTS`. Some workloads, such as CoCo, support joining trace data to usage rows on `REQUEST_ID` to attribute cost to individual prompts.

Base spend reporting on the usage views rather than on `AI_OBSERVABILITY_EVENTS`. Trace delivery is best effort, so totals computed from the event table can under-report consumption. For the authoritative sources, see [](/sql-reference/local/ai_observability_events#label-ai-observability-events-billing).

For usage views, budget types, alerts, and showback patterns by feature, see [AI cost management and governance](/user-guide/snowflake-cortex/governance-and-availability/ai-cost-management-and-governance). For list prices and consumption units, see [Cortex pricing](/user-guide/snowflake-cortex/pricing).

## Shared trace storage

Several features write traces to `SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS`. Direct Cortex Analyst requests use a separate LOCAL table instead. For what the event table stores, which features write to it, application roles, redaction behavior, and the four `GET_AI_*` table functions (including `GET_AI_OBSERVABILITY_EVENTS` with `CORTEX AGENT`, `EXTERNAL AGENT`, or `CORTEX SEARCH SERVICE`), see [AI_OBSERVABILITY_EVENTS table](/sql-reference/local/ai_observability_events) in the LOCAL schema reference.