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
In a nutshell
  • 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.

Python appinstrument decoratorspansTruLens SDKTruAppexports toEvent tableAI_OBSERVABILITY_EVENTSread withGET_AI_OBSERVABILITY_EVENTS

How it works

Implementation methods

MethodWhen
Native Cortex features (Agents, Snowflake Intelligence, Analyst, Search)Monitoring and evaluations appear in Snowsight with no code
TruLens SDKCustom apps, such as RAG pipelines or agent workflows, on Snowflake or elsewhere
Account Usage viewsBuilt-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 typeUse for
RETRIEVALRetrieval or search functions
GENERATIONLLM inference calls
RECORD_ROOTThe 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 roleAllows
SNOWFLAKE.AI_OBSERVABILITY_READER (application role)Read-only access to the table
SNOWFLAKE.AI_OBSERVABILITY_ADMINDelete 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_USERView 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.

Exam tip

A governance question about letting engineers debug without exposing customer text points to AI_OBSERVABILITY_READER without the unredacted privilege.

EngineerREADER roleseesRedacted spanstool names, latency, tokensAuditorunredacted privilegeseesFull spansinputs and outputs

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

SituationMethod
You use Cortex Agents or Snowflake IntelligenceOpen the agent in Snowsight and use its built-in monitoring and traces
You built a RAG app in Python, on Snowflake or elsewhereInstrument with TruLens and register a TruApp
You use LangChain, LangGraph or LlamaIndexUse TruChain, TruGraph or TruLlama
You only need spendQuery 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.