Skip to main content
Trace Cursor conversations, shell commands, MCP tools, and file operations in Arize AX for full observability.
Cursor is an AI code editor for agentic software development. The Arize Cursor tracing hooks instrument Cursor hook events and export spans to Arize AX and/or Arize Phoenix. A Cursor conversation maps to a session, and each message turn maps to a trace.

​
Launch Arize

To get started, sign up for a free Arize account and get your Space ID and API Key:
  1. Log in at app.arize.com
  2. Click Settings and copy the Space ID
  3. Open the API Keys tab and create or copy an API key

​
Install

Add the Cursor tracing hook files from the Arize Cursor repository to your project. If you are starting from the arize-cursor repo, these files are already included. If you are adding tracing to an existing project, make sure your project contains: 
.cursor/hooks.json
.cursor/hooks/hook-handler.sh
.cursor/hooks/lib/common.sh
.cursor/hooks/scripts/requirements.txt
.cursor/hooks/scripts/send_span.py
.cursor/hooks/scripts/test_arize_ax.sh
Create a .env file in your project root and configure Arize AX: 
ARIZE_API_KEY=your-arize-api-key
ARIZE_SPACE_ID=your-space-id
ARIZE_PROJECT_NAME=cursor
ARIZE_TRACE_ENABLED=true
Install the Python dependencies used to export spans to Arize AX: 
python3 -m venv .cursor/hooks/scripts/.venv
.cursor/hooks/scripts/.venv/bin/pip install -r .cursor/hooks/scripts/requirements.txt
Open the project in Cursor and use the agent normally. The hooks in .cursor/hooks.json will fire automatically.

​
Verify

Run the smoke test from your project root: 
.cursor/hooks/scripts/test_arize_ax.sh
You should see Export OK and a span named cursor-arize-ax-smoke-test. After that, use Cursor and open your Arize project to inspect traces.

​
Observe

Once tracing is enabled, Cursor activity is streamed to Arize AX. You’ll see:
  • Session grouping by conversation_id for each Cursor conversation
  • Turn traces by generation_id for each message turn
  • User prompt spans for submitted prompts
  • Agent response spans with model output
  • Agent thinking spans when Cursor emits reasoning/thought events
  • Shell spans with command input and command output merged into a single tool span
  • MCP spans named MCP: {tool} with tool input and result
  • File read and edit spans for file operations, including tab reads and edits
The default project name is cursor unless you set ARIZE_PROJECT_NAME or reuse PHOENIX_PROJECT.

​
Hooks Captured

HookCaptured Data
beforeSubmitPromptUser prompt span for the turn root
afterAgentResponseAgent response text and model metadata
afterAgentThoughtAgent thinking output and duration
beforeShellExecutionShell command state used for merge
afterShellExecutionOne Shell span with command, cwd, output, and duration
beforeMCPExecutionMCP tool state used for merge
afterMCPExecutionOne MCP: {tool} span with input, result, and duration
beforeReadFileRead file span
afterFileEditFile edit span
stopStop span and state cleanup for the turn
beforeTabFileReadTab read file span
afterTabFileEditTab file edit span

​
How Shell and MCP Merge Works

Cursor emits separate before* and after* hook events for shell commands and MCP tools. The Arize Cursor hooks keep a small disk-backed state entry for the before event, then create a single span on the corresponding after event. That gives you one span with both the input and the output instead of two partial spans. On stop, the hook handler cleans up any saved state for that turn so the state directory does not keep growing over time.

​
Troubleshooting

ProblemFix
Traces not appearing in Arize AXCheck ARIZE_API_KEY, ARIZE_SPACE_ID, and ARIZE_TRACE_ENABLED=true in your project .env
Smoke test says Python dependencies are missingRun python3 -m venv .cursor/hooks/scripts/.venv && .cursor/hooks/scripts/.venv/bin/pip install -r .cursor/hooks/scripts/requirements.txt
Want to verify export before opening CursorRun .cursor/hooks/scripts/test_arize_ax.sh from the project root
Traces land in the wrong projectSet ARIZE_PROJECT_NAME explicitly
Large prompt or tool payloads are truncatedIncrease CURSOR_TRACE_MAX_ATTR_CHARS
Want verbose loggingSet ARIZE_VERBOSE=true and launch Cursor from a shell so hook stderr is visible

​
Fail-Open Behavior

If the tracing hook errors, Cursor continues running. The hook handler always returns the permissive response Cursor expects, so tracing failures do not block the editor or agent workflow.

​
Resources