# Cursor integration with Coralogix

Connect Cursor agent sessions to Coralogix and stream traces from local installations. Once connected, each Cursor agent session appears as a trace in Coralogix with spans for prompts, tool usage, file edits, and session activity.

## What you need

- A Coralogix account with a **Send-Your-Data [API key](https://coralogix.com/docs/user-guides/account-management/api-keys/send-your-data-api-key/index.md)**. In Coralogix, navigate to **Settings**, then **API Keys**.
- Your Coralogix OTLP endpoint: `https://ingress.[[DOMAIN_VALUE]]:443`. Use the domain selector at the top of this page to select your region.
- Cursor installed on your machine.

## Set up

### Install

Clone the Coralogix AI agent instrumentation repository and navigate to the Cursor directory:

```bash
git clone https://github.com/coralogix/ai-agent-instrumentation.git
cd ai-agent-instrumentation/cursor
```

### Configure

1. Copy the example environment file:

   ```bash
   cp .env.example .env
   ```

1. Open `.env` and set the following values:

   - `CX_API_KEY` — your Send-Your-Data API key
   - `CX_OTLP_ENDPOINT` — your OTLP endpoint, including the `https://` prefix (for example, `https://ingress.[[DOMAIN_VALUE]]:443`)

1. Install the Cursor hook:

   ```bash
   ./install.sh --env-file .env
   ```

1. Restart Cursor.

   Cursor agent sessions now stream traces to Coralogix.

## View data in Coralogix

Open the [Code agents](https://coralogix.com/docs/user-guides/ai/code-agents/index.md) dashboard in Coralogix to monitor token usage, costs, tool calls, code changes, and session activity from your Cursor agent sessions.

For individual session details, open [Distributed Tracing](https://coralogix.com/docs/user-guides/data_exploration/spans/explore-spans/index.md) in Coralogix and filter by your application and subsystem names. Each Cursor agent session appears as a single trace with all spans grouped by `conversation_id`.

## Data available

| Signal                       | Where in Coralogix                                                            |
| ---------------------------- | ----------------------------------------------------------------------------- |
| Sessions and unique users    | Tracing (`cursor.conversation_id`, `cursor.user_email`)                       |
| Prompt token usage over time | Tracing (`cursor.beforeSubmitPrompt`—`cursor.prompt_len`)                     |
| Lines added and removed      | Tracing (`cursor.afterFileEdit`—`cursor.lines_added`, `cursor.lines_deleted`) |
| Session duration             | Tracing (`cursor.stop`—`cursor.session_duration_ms`)                          |
| Model distribution           | Tracing (`gen_ai.request.model`)                                              |
| Top tools used               | Tracing (`gen_ai.tool.name`)                                                  |

## Data scopes

Cursor emits spans. Use [data scopes](https://coralogix.com/docs/user-guides/account-management/user-management/scopes/index.md) to restrict which Cursor data each user can see. See [Code agents observability — Data scopes](https://coralogix.com/docs/user-guides/ai/code-agents/#data-scopes) for the per-agent breakdown.

## Privacy options

Add these values to your `.env` before running the installation script:

```bash
# Replace all prompt and response text with [MASKED]
CURSOR_MASK_PROMPTS=true

# Skip preToolUse spans to reduce trace noise
CURSOR_OMIT_PRE_TOOL_USE_SPANS=true
```

## Complete configuration

For the full configuration reference, see [cursor in the GitHub repository](https://github.com/coralogix/ai-agent-instrumentation/tree/master/cursor).

## Troubleshoot

### No traces appear

In Cursor, select **View**, then **Output**, then **Hooks**, and look for export errors. Set `CX_OTLP_DEBUG=true` in `.env`, and run `./install.sh --env-file .env` again for verbose output.

### Hooks do not fire

Confirm that agent hooks are active in **Cursor Settings**, then **Features**, then **Agent**.

## Next steps

After you set up the integration, explore [Code agents](https://coralogix.com/docs/user-guides/ai/code-agents/index.md) to monitor token usage, costs, tool calls, code changes, and session data across all your coding agents.