Cursor generated rules (#4493)

sl0thentr0py · web-flow · commit 3e2994800dc9 · 2025-06-24T10:17:39.000Z
It also added performance and aws related files but I want to keep it
simple for now.
This adds:

* quick reference
* testing guide
* project overview
* core architecture
* integration guide
diff --git a/.cursor/rules/core-architecture.mdc b/.cursor/rules/core-architecture.mdc
@@ -0,0 +1,122 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Core Architecture
+
+## Scope and Client Pattern
+
+The Sentry SDK uses a **Scope and Client** pattern for managing state and context:
+
+### Scope
+- [sentry_sdk/scope.py](mdc:sentry_sdk/scope.py) - Holds contextual data
+- Holds a reference to the Client
+- Contains tags, extra data, user info, breadcrumbs
+- Thread-local storage for isolation
+
+### Client
+- [sentry_sdk/client.py](mdc:sentry_sdk/client.py) - Handles event processing
+- Manages transport and event serialization
+- Applies sampling and filtering
+
+## Key Components
+
+### API Layer
+- [sentry_sdk/api.py](mdc:sentry_sdk/api.py) - Public API functions
+- `init()` - Initialize the SDK
+- `capture_exception()` - Capture exceptions
+- `capture_message()` - Capture custom messages
+- `set_tag()`, `set_user()`, `set_context()` - Add context
+- `start_transaction()` - Performance monitoring
+
+### Transport
+- [sentry_sdk/transport.py](mdc:sentry_sdk/transport.py) - Event delivery
+- `HttpTransport` - HTTP transport to Sentry servers
+- Handles retries, rate limiting, and queuing
+
+### Integrations System
+- [sentry_sdk/integrations/__init__.py](mdc:sentry_sdk/integrations/__init__.py) - Integration registry
+- Base `Integration` class for all integrations
+- Automatic setup and teardown
+- Integration-specific configuration
+
+## Data Flow
+
+### Event Capture Flow
+1. **Exception occurs** or **manual capture** called
+2. **get_current_scope** gets the active current scope
+2. **get_isolation_scope** gets the active isolation scope
+3. **Scope data** (tags, user, context) is attached
+4. **Client.process_event()** processes the event
+5. **Sampling** and **filtering** applied
+6. **Transport** sends to Sentry servers
+
+### Performance Monitoring Flow
+1. **Transaction started** with `start_transaction()`
+2. **Spans** created for operations within transaction with `start_span()`
+3. **Timing data** collected automatically
+4. **Transaction finished** and sent to Sentry
+
+## Context Management
+
+### Scope Stack
+- **Global scope**: Default scope for the process
+- **Isolation scope**: Isolated scope for specific operations, manages concurrency isolation
+- **Current scope**: Active scope for current execution context
+
+### Scope Operations
+- `configure_scope()` - Modify current scope
+- `new_scope()` - Create isolated scope
+
+## Integration Architecture
+
+### Integration Lifecycle
+1. **Registration**: Integration registered during `init()`
+2. **Setup**: `setup_once()` called to install hooks
+3. **Runtime**: Integration monitors and captures events
+4. **Teardown**: Integration cleaned up on shutdown
+
+### Common Integration Patterns
+- **Monkey patching**: Replace functions/methods with instrumented versions
+- **Signal handlers**: Hook into framework signals/events
+- **Middleware**: Add middleware to web frameworks
+- **Exception handlers**: Catch and process exceptions
+
+### Integration Configuration
+```python
+# Example integration setup
+sentry_sdk.init(
+    dsn="your-dsn",
+    integrations=[
+        DjangoIntegration(),
+        CeleryIntegration(),
+        RedisIntegration(),
+    ],
+    traces_sample_rate=1.0,
+)
+```
+
+## Error Handling
+
+### Exception Processing
+- **Automatic capture**: Unhandled exceptions captured automatically
+- **Manual capture**: Use `capture_exception()` for handled exceptions
+- **Context preservation**: Stack traces, local variables, and context preserved
+
+### Breadcrumbs
+- **Automatic breadcrumbs**: Framework operations logged automatically
+- **Manual breadcrumbs**: Use `add_breadcrumb()` for custom events
+- **Breadcrumb categories**: HTTP, database, navigation, etc.
+
+## Performance Monitoring
+
+### Transaction Tracking
+- **Automatic transactions**: Web requests, background tasks
+- **Custom transactions**: Use `start_transaction()` for custom operations
+- **Span tracking**: Database queries, HTTP requests, custom operations
+- **Performance data**: Timing, resource usage, custom measurements
+
+### Sampling
+- **Transaction sampling**: Control percentage of transactions captured
+- **Dynamic sampling**: Adjust sampling based on context
diff --git a/.cursor/rules/integrations-guide.mdc b/.cursor/rules/integrations-guide.mdc
@@ -0,0 +1,158 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Integrations Guide
+
+## Integration Categories
+
+The Sentry Python SDK includes integrations for popular frameworks, libraries, and services:
+
+### Web Frameworks
+- [sentry_sdk/integrations/django/](mdc:sentry_sdk/integrations/django) - Django web framework
+- [sentry_sdk/integrations/flask/](mdc:sentry_sdk/integrations/flask) - Flask microframework
+- [sentry_sdk/integrations/fastapi/](mdc:sentry_sdk/integrations/fastapi) - FastAPI framework
+- [sentry_sdk/integrations/starlette/](mdc:sentry_sdk/integrations/starlette) - Starlette ASGI framework
+- [sentry_sdk/integrations/sanic/](mdc:sentry_sdk/integrations/sanic) - Sanic async framework
+- [sentry_sdk/integrations/tornado/](mdc:sentry_sdk/integrations/tornado) - Tornado web framework
+- [sentry_sdk/integrations/pyramid/](mdc:sentry_sdk/integrations/pyramid) - Pyramid framework
+- [sentry_sdk/integrations/bottle/](mdc:sentry_sdk/integrations/bottle) - Bottle microframework
+- [sentry_sdk/integrations/chalice/](mdc:sentry_sdk/integrations/chalice) - AWS Chalice
+- [sentry_sdk/integrations/quart/](mdc:sentry_sdk/integrations/quart) - Quart async framework
+- [sentry_sdk/integrations/falcon/](mdc:sentry_sdk/integrations/falcon) - Falcon framework
+- [sentry_sdk/integrations/litestar/](mdc:sentry_sdk/integrations/litestar) - Litestar framework
+- [sentry_sdk/integrations/starlite/](mdc:sentry_sdk/integrations/starlite) - Starlite framework
+
+### Task Queues and Background Jobs
+- [sentry_sdk/integrations/celery/](mdc:sentry_sdk/integrations/celery) - Celery task queue
+- [sentry_sdk/integrations/rq/](mdc:sentry_sdk/integrations/rq) - Redis Queue
+- [sentry_sdk/integrations/huey/](mdc:sentry_sdk/integrations/huey) - Huey task queue
+- [sentry_sdk/integrations/arq/](mdc:sentry_sdk/integrations/arq) - Arq async task queue
+- [sentry_sdk/integrations/dramatiq/](mdc:sentry_sdk/integrations/dramatiq) - Dramatiq task queue
+
+### Databases and Data Stores
+- [sentry_sdk/integrations/sqlalchemy/](mdc:sentry_sdk/integrations/sqlalchemy) - SQLAlchemy ORM
+- [sentry_sdk/integrations/asyncpg/](mdc:sentry_sdk/integrations/asyncpg) - AsyncPG PostgreSQL
+- [sentry_sdk/integrations/pymongo/](mdc:sentry_sdk/integrations/pymongo) - PyMongo MongoDB
+- [sentry_sdk/integrations/redis/](mdc:sentry_sdk/integrations/redis) - Redis client
+- [sentry_sdk/integrations/clickhouse_driver/](mdc:sentry_sdk/integrations/clickhouse_driver) - ClickHouse driver
+
+### Cloud and Serverless
+- [sentry_sdk/integrations/aws_lambda/](mdc:sentry_sdk/integrations/aws_lambda) - AWS Lambda
+- [sentry_sdk/integrations/gcp/](mdc:sentry_sdk/integrations/gcp) - Google Cloud Platform
+- [sentry_sdk/integrations/serverless/](mdc:sentry_sdk/integrations/serverless) - Serverless framework
+
+### HTTP and Networking
+- [sentry_sdk/integrations/requests/](mdc:sentry_sdk/integrations/requests) - Requests HTTP library
+- [sentry_sdk/integrations/httpx/](mdc:sentry_sdk/integrations/httpx) - HTTPX async HTTP client
+- [sentry_sdk/integrations/aiohttp/](mdc:sentry_sdk/integrations/aiohttp) - aiohttp async HTTP
+- [sentry_sdk/integrations/grpc/](mdc:sentry_sdk/integrations/grpc) - gRPC framework
+
+### AI and Machine Learning
+- [sentry_sdk/integrations/openai/](mdc:sentry_sdk/integrations/openai) - OpenAI API
+- [sentry_sdk/integrations/anthropic/](mdc:sentry_sdk/integrations/anthropic) - Anthropic Claude
+- [sentry_sdk/integrations/cohere/](mdc:sentry_sdk/integrations/cohere) - Cohere AI
+- [sentry_sdk/integrations/huggingface_hub/](mdc:sentry_sdk/integrations/huggingface_hub) - Hugging Face Hub
+- [sentry_sdk/integrations/langchain/](mdc:sentry_sdk/integrations/langchain) - LangChain framework
+
+### GraphQL
+- [sentry_sdk/integrations/graphene/](mdc:sentry_sdk/integrations/graphene) - Graphene GraphQL
+- [sentry_sdk/integrations/ariadne/](mdc:sentry_sdk/integrations/ariadne) - Ariadne GraphQL
+- [sentry_sdk/integrations/strawberry/](mdc:sentry_sdk/integrations/strawberry) - Strawberry GraphQL
+- [sentry_sdk/integrations/gql/](mdc:sentry_sdk/integrations/gql) - GQL GraphQL client
+
+### Feature Flags and Configuration
+- [sentry_sdk/integrations/launchdarkly/](mdc:sentry_sdk/integrations/launchdarkly) - LaunchDarkly
+- [sentry_sdk/integrations/unleash/](mdc:sentry_sdk/integrations/unleash) - Unleash
+- [sentry_sdk/integrations/statsig/](mdc:sentry_sdk/integrations/statsig) - Statsig
+- [sentry_sdk/integrations/openfeature/](mdc:sentry_sdk/integrations/openfeature) - OpenFeature
+
+### Other Integrations
+- [sentry_sdk/integrations/logging/](mdc:sentry_sdk/integrations/logging) - Python logging
+- [sentry_sdk/integrations/loguru/](mdc:sentry_sdk/integrations/loguru) - Loguru logging
+- [sentry_sdk/integrations/opentelemetry/](mdc:sentry_sdk/integrations/opentelemetry) - OpenTelemetry
+- [sentry_sdk/integrations/ray/](mdc:sentry_sdk/integrations/ray) - Ray distributed computing
+- [sentry_sdk/integrations/spark/](mdc:sentry_sdk/integrations/spark) - Apache Spark
+- [sentry_sdk/integrations/beam/](mdc:sentry_sdk/integrations/beam) - Apache Beam
+
+## Integration Usage
+
+### Basic Integration Setup
+```python
+import sentry_sdk
+from sentry_sdk.integrations.django import DjangoIntegration
+from sentry_sdk.integrations.celery import CeleryIntegration
+
+sentry_sdk.init(
+    dsn="your-dsn",
+    integrations=[
+        DjangoIntegration(),
+        CeleryIntegration(),
+    ],
+    traces_sample_rate=1.0,
+)
+```
+
+### Integration Configuration
+Most integrations accept configuration parameters:
+```python
+from sentry_sdk.integrations.django import DjangoIntegration
+from sentry_sdk.integrations.redis import RedisIntegration
+
+sentry_sdk.init(
+    dsn="your-dsn",
+    integrations=[
+        DjangoIntegration(
+            transaction_style="url",  # Customize transaction naming
+        ),
+        RedisIntegration(
+            cache_prefixes=["myapp:"],  # Filter cache operations
+        ),
+    ],
+)
+```
+
+### Integration Testing
+Each integration has corresponding tests in [tests/integrations/](mdc:tests/integrations):
+- [tests/integrations/django/](mdc:tests/integrations/django) - Django integration tests
+- [tests/integrations/flask/](mdc:tests/integrations/flask) - Flask integration tests
+- [tests/integrations/celery/](mdc:tests/integrations/celery) - Celery integration tests
+
+## Integration Development
+
+### Creating New Integrations
+1. **Create integration file** in [sentry_sdk/integrations/](mdc:sentry_sdk/integrations)
+2. **Inherit from Integration base class**
+3. **Implement setup_once() method**
+4. **Add to integration registry**
+
+### Integration Base Class
+```python
+from sentry_sdk.integrations import Integration
+
+class MyIntegration(Integration):
+    identifier = "my_integration"
+    
+    def __init__(self, param=None):
+        self.param = param
+    
+    @staticmethod
+    def setup_once():
+        # Install hooks, monkey patches, etc.
+        pass
+```
+
+### Common Integration Patterns
+- **Monkey patching**: Replace functions with instrumented versions
+- **Middleware**: Add middleware to web frameworks
+- **Signal handlers**: Hook into framework signals
+- **Exception handlers**: Catch and process exceptions
+- **Context managers**: Add context to operations
+
+### Integration Best Practices
+- **Zero configuration**: Work without user setup
+- **Check integration status**: Use `sentry_sdk.get_client().get_integration()`
+- **No side effects**: Don't alter library behavior
+- **Graceful degradation**: Handle missing dependencies
+- **Comprehensive testing**: Test all integration features
diff --git a/.cursor/rules/project-overview.mdc b/.cursor/rules/project-overview.mdc
@@ -0,0 +1,47 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Sentry Python SDK - Project Overview
+
+## What is this project?
+
+The Sentry Python SDK is the official Python SDK for [Sentry](mdc:https://sentry.io), an error monitoring and performance monitoring platform. It helps developers capture errors, exceptions, traces and profiles from Python applications.
+
+## Key Files and Directories
+
+### Core SDK
+- [sentry_sdk/__init__.py](mdc:sentry_sdk/__init__.py) - Main entry point, exports all public APIs
+- [sentry_sdk/api.py](mdc:sentry_sdk/api.py) - Public API functions (init, capture_exception, etc.)
+- [sentry_sdk/client.py](mdc:sentry_sdk/client.py) - Core client implementation
+- [sentry_sdk/scope.py](mdc:sentry_sdk/scope.py) - Scope holds contextual metadata such as tags that are applied automatically to events and envelopes
+- [sentry_sdk/transport.py](mdc:sentry_sdk/transport.py) - HTTP Transport that sends the envelopes to Sentry's servers
+- [sentry_sdk/worker.py](mdc:sentry_sdk/worker.py) - Background threaded worker with a queue to manage transport requests
+- [sentry_sdk/serializer.py](mdc:sentry_sdk/serializer.py) - Serializes the payload along with truncation logic
+
+### Integrations
+- [sentry_sdk/integrations/](mdc:sentry_sdk/integrations) - Framework and library integrations
+  - [sentry_sdk/integrations/__init__.py](mdc:sentry_sdk/integrations/__init__.py) - Integration registry
+  - [sentry_sdk/integrations/django/](mdc:sentry_sdk/integrations/django) - Django framework integration
+  - [sentry_sdk/integrations/flask/](mdc:sentry_sdk/integrations/flask) - Flask framework integration
+  - [sentry_sdk/integrations/fastapi/](mdc:sentry_sdk/integrations/fastapi) - FastAPI integration
+  - [sentry_sdk/integrations/celery/](mdc:sentry_sdk/integrations/celery) - Celery task queue integration
+  - [sentry_sdk/integrations/aws_lambda/](mdc:sentry_sdk/integrations/aws_lambda) - AWS Lambda integration
+
+### Configuration and Setup
+- [setup.py](mdc:setup.py) - Package configuration and dependencies
+- [pyproject.toml](mdc:pyproject.toml) - Modern Python project configuration
+- [tox.ini](mdc:tox.ini) - Test matrix configuration for multiple Python versions and integrations
+- [requirements-*.txt](mdc:requirements-testing.txt) - Various dependency requirements
+
+### Documentation and Guides
+- [README.md](mdc:README.md) - Project overview and quick start
+- [CONTRIBUTING.md](mdc:CONTRIBUTING.md) - Development and contribution guidelines
+- [MIGRATION_GUIDE.md](mdc:MIGRATION_GUIDE.md) - Migration from older versions
+- [CHANGELOG.md](mdc:CHANGELOG.md) - Version history and changes
+
+### Testing
+- [tests/](mdc:tests) - Comprehensive test suite
+  - [tests/integrations/](mdc:tests/integrations) - Integration-specific tests
+  - [tests/conftest.py](mdc:tests/conftest.py) - Pytest configuration and fixtures
diff --git a/.cursor/rules/quick-reference.mdc b/.cursor/rules/quick-reference.mdc
@@ -0,0 +1,51 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+# Quick Reference
+
+## Common Commands
+
+### Development Setup
+```bash
+make .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+```
+
+### Testing
+
+Our test matrix is implemented in [tox](mdc:https://tox.wiki).
+The following runs the whole test suite and takes a long time.
+
+```bash
+source .venv/bin/activate
+tox
+```
+
+Prefer testing a single environment instead while developing.
+
+```bash
+tox -e py3.12-common
+```
+
+For running a single test, use the pattern:
+
+```bash
+tox -e py3.12-common -- project/tests/test_file.py::TestClassName::test_method
+```
+
+For testing specific integrations, refer to the test matrix in [sentry_sdk/tox.ini](mdc:sentry_sdk/tox.ini) for finding an entry.
+For example, to test django, use:
+
+```bash
+tox -e py3.12-django-v5.2.3
+```
+
+### Code Quality
+
+Our `linters` tox environment runs `black` for formatting, `flake8` for linting and `mypy` for type checking.
+
+```bash
+tox -e linters
+```
diff --git a/.cursor/rules/testing-guide.mdc b/.cursor/rules/testing-guide.mdc
