Snowflake Gen AI Governance · Topic 15 of 15
AI Observability Tracing, Logging, Event Tables and the TruLens SDK
Trace and log GenAI apps with TruLens spans, store them in the AI_OBSERVABILITY_EVENTS event table, read them with GET_AI_OBSERVABILITY_EVENTS.
- 5 min
- Event table:
SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS; read with GET_AI_OBSERVABILITY_EVENTS. - TruLens packages: trulens-core, trulens-connectors-snowflake, trulens-providers-cortex, version 2.1.2 or later.
- Span types: RETRIEVAL, GENERATION, RECORD_ROOT. Wrappers: TruChain, TruGraph, TruLlama.
What it is
Tracing records what happened inside one request, step by step. Logging keeps the warnings and events around runs. Both are stored in an event table, so you can query them with SQL and control who sees them with privileges.
Snowflake provides one shared event table for AI observability and a Python SDK, TruLens, to produce the traces for custom applications.
How it works
Implementation methods
| Method | When |
|---|---|
| Native Cortex features (Agents, Snowflake Intelligence, Analyst, Search) | Monitoring and evaluations appear in Snowsight with no code |
| TruLens SDK | Custom apps, such as RAG pipelines or agent workflows, on Snowflake or elsewhere |
| Account Usage views | Built-in AI functions and the REST API report only through cost views |
Setting up TruLens
Install TruLens version 2.1.2 or later with three packages: trulens-core, trulens-connectors-snowflake and trulens-providers-cortex. Grant the privileges first (see the previous page).
Decorate functions with @instrument(). A bare decorator captures inputs, outputs and latency. A span_type adds meaning.
| Span type | Use for |
|---|---|
RETRIEVAL | Retrieval or search functions |
GENERATION | LLM inference calls |
RECORD_ROOT | The main entry point of the app |
An attributes mapping links span attributes to function parameter names or "return", for example RETRIEVAL.RETRIEVED_CONTEXTS to capture returned documents.
from trulens.core.otel.instrument import instrument
from trulens.otel.semconv.trace import SpanAttributes
@instrument(span_type=SpanAttributes.SpanType.RETRIEVAL,
attributes={
SpanAttributes.RETRIEVAL.QUERY_TEXT: "query",
SpanAttributes.RETRIEVAL.RETRIEVED_CONTEXTS: "return"})
def retrieve(query): ...
Framework wrappers exist: TruChain for LangChain, TruGraph for LangGraph and TruLlama for LlamaIndex. Register the app by creating a TruApp with the app, a name, a version and a SnowflakeConnector. main_method can be omitted if the entry point uses RECORD_ROOT. Invoke the app while the recorder is active so traces export on each run.
The event table
All AI observability traces for agents, Cortex Code, Search and TruLens go to SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. Rows cannot be modified after ingestion. Direct Cortex Analyst requests are stored separately in SNOWFLAKE.LOCAL.CORTEX_ANALYST_REQUESTS_RAW.
Read it through table functions rather than the raw table:
SELECT * FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_EVENTS(
'MY_DB', 'MY_SCHEMA', 'MY_APP', 'EXTERNAL AGENT'));
The agent type is CORTEX AGENT, EXTERNAL AGENT or CORTEX SEARCH SERVICE. For Cortex Search logs the caller needs MONITOR on the service. GET_AI_OBSERVABILITY_LOGS returns evaluation-run logs and warnings.
Access to the event data
| Privilege or role | Allows |
|---|---|
SNOWFLAKE.AI_OBSERVABILITY_READER (application role) | Read-only access to the table |
SNOWFLAKE.AI_OBSERVABILITY_ADMIN | Delete rows |
READ UNREDACTED AI OBSERVABILITY EVENTS TABLE (account privilege) | See full tool inputs, outputs and conversation text |
USAGE or OWNERSHIP on the External Agent, plus SNOWFLAKE.CORTEX_USER | View traces or query events for the app |
Without the unredacted privilege, metadata such as tool names, latency and token usage stays visible but content is hidden. This matters for privacy: traces can hold prompts and answers.
Viewing traces
In Snowsight go to AI & ML, then Evaluations, choose the External Agent, and open a run or a record to see inputs and outputs per span, latency and intermediate steps.
Logging scope
Registration creates an External Agent that stores only name, version and run name. Traces and scores live in the event table. Evaluation problems appear in the logs function.
Cost reporting
Trace delivery is best effort and can under-report consumption, so do not use the event table as the source for billing. Use the Account Usage views.
A governance question about letting engineers debug without exposing customer text points to AI_OBSERVABILITY_READER without the unredacted privilege.
Event tables in general
An event table is a Snowflake table with a fixed structure that captures logs, traces and events. Snowflake Gen AI features write to one shared event table for AI observability, SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS, so you do not create your own for this purpose. Event tables also appear in other contexts. For example, logs from Snowpark Container Services services land in an event table and incur event table storage cost.
The practical consequences are access and privacy. Access to trace content is governed by roles on the table functions, and the sensitive text inside spans is hidden unless a role holds the unredacted privilege. Treat the data as potentially containing customer prompts.
Choosing the implementation method
| Situation | Method |
|---|---|
| You use Cortex Agents or Snowflake Intelligence | Open the agent in Snowsight and use its built-in monitoring and traces |
| You built a RAG app in Python, on Snowflake or elsewhere | Instrument with TruLens and register a TruApp |
| You use LangChain, LangGraph or LlamaIndex | Use TruChain, TruGraph or TruLlama |
| You only need spend | Query the Account Usage views |
Logging versus tracing
Tracing answers "what path did this request take" and is organized as spans with inputs, outputs and latency. Logging answers "what warnings or errors occurred". For evaluation runs, the logs function (GET_AI_OBSERVABILITY_LOGS) returns the warnings and errors of the run.
Common mistakes
Editing or deleting trace rows. They cannot be modified; deletion needs the ADMIN role.
Selecting from the raw table instead of GET_AI_OBSERVABILITY_EVENTS.
Using a TruLens version below 2.1.2.
Granting broad unredacted access. Traces can contain sensitive prompts.
Skipping the RECORD_ROOT span and then having no main_method.
What to remember for the exam
- Event table:
SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS; read with GET_AI_OBSERVABILITY_EVENTS. - TruLens packages: trulens-core, trulens-connectors-snowflake, trulens-providers-cortex, version 2.1.2 or later.
- Span types: RETRIEVAL, GENERATION, RECORD_ROOT. Wrappers: TruChain, TruGraph, TruLlama.
- READER, ADMIN and the unredacted privilege control access.
Check yourself
Where are TruLens traces stored?
In the event table SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS.
Which span type marks the app's entry point?
RECORD_ROOT.
Which privilege reveals full prompts and answers in traces?
READ UNREDACTED AI OBSERVABILITY EVENTS TABLE.
Topic 15 of 15 in Snowflake Gen AI Governance
Test yourself on Snowflake Gen AI Governance
The full Snowflake GES-C02 question bank has 585 questions, with timed practice exams and an explanation for every answer.
This study guide is independent and is not affiliated with, endorsed by, or sponsored by Snowflake. Vendor names, certification names and exam codes are trademarks of their respective owners and are used for identification only.