AI Observability with Snowflake Cortex¶
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 does the feature perform on test data, what was the cost for this 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 and Native Cortex features below.
- Custom AI applications you host: See Custom AI application observability with TruLens.
- Guardrail scans and blocked requests: Cortex AI Guardrails protect CoCo, Snowflake CoWork, and Cortex Agents. See Cortex AI Guardrails below and Monitor guardrail activity.
- Spend reporting, budgets, and alerts: See Cost and governance and AI cost management and governance.
For Cortex Agent terms such as thread, turn, trace, and span, see Terminology.
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 |
|---|---|---|
| Snowflake CoWork and Cortex Agents | Live agent threads and traces; batch evaluations on a dataset | Monitor Cortex Agent requests, Cortex Agent evaluations |
| CoCo | Prompt traces in the event table; credits, tokens, models, and request IDs in Account Usage | Observability, Cost controls for CoCo |
| Cortex Analyst | Request and response logs; batch evaluations | Cortex Analyst administrator monitoring, 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 |
| Built-in Cortex AI Functions | Credits, tokens, function name, and model per call in Account Usage | Managing Cortex AI Function costs with Account Usage |
| Cortex AI Function Studio | Author and evaluate custom AI functions; production usage in Account Usage | Cortex AI Function Studio |
| Cortex REST API | Tokens, credits, model, request ID, and inference region per request in Account Usage | Monitor usage |
| Cortex AI Guardrails | Guardrail scan activity, tokens, credits, and request metadata in Account Usage | Monitor guardrail activity |
Native Cortex features¶
The sections below describe observability for each native feature. For step-by-step procedures, follow the links in each section.
Snowflake CoWork and Cortex Agents¶
Cortex Agents deployed through the Agent API or Snowflake CoWork log conversation threads, turns, and execution spans automatically into SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. Use the Monitoring tab or Monitor Cortex Agent requests to debug production conversations. Use the Evaluations tab or Cortex Agent evaluations to score an agent on a dataset before or after deployment.
Credit usage appears in CORTEX_AGENT_USAGE_HISTORY and SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY. 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 and AI cost management and governance.
CoCo¶
CoCo writes span records to AI_OBSERVABILITY_EVENTS for each prompt. Snowsight, Desktop, and the CLI record credits, tokens, models, and request IDs in separate Account Usage views.
- Snowsight: Observability and CORTEX_CODE_SNOWSIGHT_USAGE_HISTORY
- Desktop: Audit logging and observability and CORTEX_CODE_DESKTOP_USAGE_HISTORY
- CLI: CoCo CLI and CORTEX_CODE_CLI_USAGE_HISTORY
See also credit usage limits.
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.
See Administrator monitoring for log access and CORTEX_ANALYST_USAGE_HISTORY for billing data, including message counts and request timing metadata.
Cortex Search¶
When 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 and agent_type CORTEX SEARCH SERVICE (requires MONITOR on the service), or follow the steps in Monitor Cortex Search requests. You can also monitor serving usage and credits in Account Usage and configure resource budgets.
See 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 and 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 helps you create, 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.
See Monitor usage.
Cortex AI Guardrails¶
Cortex AI Guardrails run at request time on CoCo, Snowflake CoWork, and 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) 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, 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.
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 object. That object stores metadata only. Traces and scores live in SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS.
- Trace applications with TruLens
- Evaluate applications with TruLens
- Snowflake AI Observability Reference
- AI Observability tutorial
View External Agent traces and evaluation runs in Snowsight under AI & ML » 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 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.
For usage views, budget types, alerts, and showback patterns by feature, see AI cost management and governance. For list prices and consumption units, see 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 in the LOCAL schema reference.