Categories:: Table functions (AI Observability)

GET_AI_OBSERVABILITY_EVENTS (SNOWFLAKE.LOCAL)¶

Return AI Observability events from the AI_OBSERVABILITY_EVENTS table in the LOCAL schema. Pass an agent type that matches the object you are inspecting:

CORTEX AGENT for a Cortex Agent (see Monitor Cortex Agent requests)
EXTERNAL AGENT for an External Agent object used with TruLens (see External Agent commands)
CORTEX SEARCH SERVICE for a Cortex Search service with REQUEST_LOGGING enabled (see Monitor Cortex Search requests)

Each row uses the event table column layout (including RECORD, RECORD_ATTRIBUTES, VALUE, and trace fields). Events can represent conversation activity, spans (planning, tools, response generation), Cortex Search request bodies, logs, user feedback, and other telemetry written for the object.

For Snowsight workflows and examples of filtering events (including feedback), see Monitor Cortex Agent requests. For how AI Observability stores data in the event table, see AI_OBSERVABILITY_EVENTS table.

Direct SELECT on AI_OBSERVABILITY_EVENTS bypasses object scoping and is for limited admin use only. Prefer this function for routine monitoring of a Cortex Agent, External Agent, or Cortex Search service.

See also:: GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL) , GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL) , GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL)

Syntax¶

SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_EVENTS( <database>, <schema>, <agent_name>, <agent_type> )

Arguments¶

database: Name of the database containing the object.
schema: Name of the schema containing the object.
agent_name: Name of the Cortex Agent, External Agent, or Cortex Search service whose observability events you want to retrieve.
agent_type: The object type string. Use CORTEX AGENT for a Cortex Agent, EXTERNAL AGENT for an External Agent object, or CORTEX SEARCH SERVICE for a Cortex Search service. This value is case-insensitive.

Returns¶

A table of observability events. Column definitions follow the event table schema. Filter and project with standard SQL (for example on RECORD:name, RECORD_ATTRIBUTES, or severity fields inside RECORD) to narrow to specific event kinds.

Access control requirements¶

A role used to execute this operation must have the following privileges at a minimum:

Privilege	Object	Notes
CORTEX_USER	Database role
USAGE	External Agent	Required on the External Agent identified by `agent_name` when `agent_type` is `EXTERNAL AGENT`. USAGE is sufficient to call this function; MONITOR does not apply.
MONITOR	Cortex Agent	Required on the Cortex Agent identified by `agent_name` when `agent_type` is `CORTEX AGENT`.
MONITOR	Cortex Search Service	Required on the Cortex Search service identified by `agent_name` when `agent_type` is `CORTEX SEARCH SERVICE`. Request logging must be enabled on the service.

Operating on an object in a schema requires at least one privilege on the parent database and at least one privilege on the parent schema.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

When agent_type is EXTERNAL AGENT, only USAGE on that object is required to call this function. OWNERSHIP on the External Agent is required to modify or remove the object with ALTER EXTERNAL AGENT or DROP EXTERNAL AGENT.

For typical Cortex Agent monitoring setup (including grants for future agents), see Monitor Cortex Agent requests. For Cortex Search request logs, see Monitor Cortex Search requests. For External Agent access to observability data, see AI_OBSERVABILITY_EVENTS table.

Examples¶

Return observability events for an agent:

SELECT *
  FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_EVENTS(
    'my_database',
    'my_schema',
    'my_agent',
    'CORTEX AGENT'
  ));

To list only user feedback events, filter on the event name (see View feedback provided by users):

SELECT *
  FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_EVENTS(
    'my_database',
    'my_schema',
    'my_agent',
    'CORTEX AGENT'
  ))
  WHERE RECORD:name = 'CORTEX_AGENT_FEEDBACK';

The same function works for an externally instrumented application by passing EXTERNAL AGENT as agent_type and the External Agent object name in agent_name (see AI_OBSERVABILITY_EVENTS table).

Return request logs for a Cortex Search service (REQUEST_LOGGING must be enabled on the service):

SELECT *
  FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_EVENTS(
    'my_database',
    'my_schema',
    'my_search_service',
    'CORTEX SEARCH SERVICE'
  ));

For filtering and output fields, see Monitor Cortex Search requests.