cursor-otel-hook

Cursor OpenTelemetry Hook

The Cursor OpenTelemetry Hook is a Python-based integration designed for the Cursor IDE that simplifies the capture of agent activity and the export of detailed traces to any OpenTelemetry-compliant receiver. It is specifically engineered to work with LangGuard.AI's AI Control Plane, providing seamless integration and observability capabilities.

Key Features

• Compatibility with LangGuard, LangSmith, and LangChain: The hook utilizes official GenAI semantic conventions and LangSmith attribute mappings to ensure smooth integration with:

  • LangGuard - AI Control Plane from LangGuard
  • Langfuse - Open-source LLM observability
  • Any OTLP backend

• Comprehensive Event Tracing: This integration captures a variety of Cursor IDE hook events, including but not limited to:

  • Lifecycle of sessions (start/end)
  • Tool usage events (pre/post/failure)
  • Execution of shell commands
  • Model Context Protocol (MCP) calls
  • File operations (read/edit)
  • Submissions of prompts
  • Context compaction events
  • Activities involving subagents

• Generation-based Batching: When transmitting data using the HTTP/JSON protocol, spans are batched according to generation_id, reducing network overhead and enhancing trace coherence. This optimization sends a single payload upon receipt of the 'stop' event.

• Custom JSON Exporter: A built-in OTLP/JSON exporter is included for environments requiring JSON format.

• Privacy Controls: The tool features built-in data masking to safeguard sensitive user details.

• Flexible Configuration Options: It supports multiple configuration methods, allowing setup through environment variables or JSON config files.

• Streamlined Installation: Automated installation scripts are available for Windows and macOS/Linux environments.

• Support for Multiple Protocols: The integration is compatible with gRPC, HTTP/Protobuf, and HTTP/JSON protocols.

Quick Start

To begin using this integration, ensure that the following prerequisites are met:

• Python 3.8 or higher
• Cursor IDE
• An OpenTelemetry collector or a compatible backend

Usage Overview

Once installed and configured correctly, the hook will automatically execute with each Cursor usage, directing traces to the configured OpenTelemetry endpoint. It adheres to the LangSmith/LangChain OpenTelemetry conventions, ensuring compatibility with LLM observability platforms.

Common Attributes Utilized in Spans

The traces generated include a variety of attributes, some of which are:

• langsmith.trace.session_id: Identifies the conversation (from Cursor's conversation_id)
• gen_ai.request.model: Specifies the AI model in use (e.g., "claude-sonnet-4-5")
• langsmith.metadata.user_email: Contains the user's email, which can be masked for privacy.

Privacy and Security

The openTelemetry hook has built-in data masking that protects:

• User prompts and messages
• Tool inputs and outputs
• Email addresses (partially masked)

The integration ensures sensitive data is never sent, thus enhancing security while providing essential telemetry data.

Conclusion

The Cursor OpenTelemetry Hook stands out as a robust solution for developers looking to enhance their observability within the Cursor IDE, while ensuring compliance with modern privacy standards and maintaining simplicity in configuration and deployment.