​

Sentry Error Tracking

​

Why Use Sentry?

​

1. Real-Time Error Tracking

• Automatic error capture - Exceptions are caught and reported automatically
• Stack traces - Full context of where and why errors occurred
• Breadcrumbs - Trail of events leading up to the error
• User context - Know which users are affected
• Environment context - Server, release, and deployment information

​

2. Performance Monitoring

• Transaction tracing - Monitor request/response times
• Database query performance - Identify slow queries
• External API calls - Track third-party service latency
• Custom instrumentation - Measure specific operations
• Performance trends - Historical performance data

​

3. Release Health Tracking

• Crash-free sessions - Track stability across releases
• Adoption rate - See how quickly users upgrade
• Issue regression - Detect when bugs reappear
• Deploy markers - Correlate issues with deployments

​

4. Intelligent Alerting

• Smart grouping - Similar errors grouped together
• Alert rules - Custom thresholds and conditions
• Integration - Slack, PagerDuty, email, webhooks
• Noise reduction - Filter out expected errors

​

5. Deep Integration

• Starlette/FastAPI - HTTP request errors and performance
• SQLAlchemy - Database query errors and slow queries
• Redis - Cache and queue operation errors
• Loguru - Application logs as breadcrumbs
• Asyncio - Async task errors and context

​

6. Privacy & Compliance

• PII scrubbing - Automatically filter sensitive data
• Custom filters - Define what data to exclude
• On-premise option - Self-hosted Sentry for complete control
• GDPR compliant - Meets European privacy standards

​

When to Use Sentry

• Running in production environments
• Need to track errors across multiple instances
• Want performance monitoring and optimization
• Require alerting for critical errors
• Building enterprise applications
• Need audit trails and compliance
• Want to improve agent reliability

• Only developing locally (use console logs)
• Cost is a major constraint (Sentry has free tier but limits)
• You already have a comprehensive monitoring solution

​

Architecture

┌─────────────────────────────────────────┐
│         Bindu Agent Instances           │
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐   │
│  │ Pod1│  │ Pod2│  │ Pod3│  │ Pod4│   │
│  └──┬──┘  └──┬──┘  └──┬──┘  └──┬──┘   │
└─────┼────────┼────────┼────────┼────────┘
      │        │        │        │
      │   Sentry SDK (automatic capture)
      │        │        │        │
      └────────┴────────┴────────┘
                  │
         ┌────────▼────────┐
         │   Sentry.io     │
         │   (Cloud/Self-  │
         │    Hosted)      │
         │                 │
         │  ┌───────────┐  │
         │  │  Errors   │  │
         │  ├───────────┤  │
         │  │Performance│  │
         │  ├───────────┤  │
         │  │ Releases  │  │
         │  └───────────┘  │
         └─────────────────┘
                  │
         ┌────────▼────────┐
         │   Alerts &      │
         │   Notifications │
         │                 │
         │  Slack, Email,  │
         │  PagerDuty, etc │
         └─────────────────┘

​

How It Works

1. Automatic Instrumentation: Sentry SDK hooks into Starlette, SQLAlchemy, Redis, etc.
2. Error Capture: Exceptions are caught and enriched with context
3. Transmission: Events sent to Sentry (batched for efficiency)
4. Processing: Sentry groups, analyzes, and stores events
5. Alerting: Notifications sent based on alert rules
6. Analysis: View errors, performance, and trends in Sentry UI

​

Configuration

​

Option 1: In-Code Configuration (Recommended)

from bindu.penguin.bindufy import bindufy

config = {
    "author": "[email protected]",
    "name": "production_agent",
    "description": "Production agent with Sentry tracking",
    "deployment": {
        "url": "http://localhost:3773",
        "expose": True
    },
    "skills": ["skills/question-answering"],
    
    # Sentry configuration
    "sentry": {
        "enabled": True,
        "dsn": "https://[email protected]/0",
        "environment": "production",
        "release": "[email protected]",  # Optional
        "traces_sample_rate": 1.0,  # 100% of errors
        "profiles_sample_rate": 0.1,  # 10% of transactions
        "enable_tracing": True,
        "send_default_pii": False,  # Disable in production
        "debug": False,
    }
}

def handler(messages):
    # Your agent logic
    pass

bindufy(config, handler)

• ✅ No environment variables needed
• ✅ Configuration lives with your code
• ✅ Easy to version control
• ✅ Perfect for packages and libraries
• ✅ Different configs for different agents

​

Option 2: Environment Variables

# Enable Sentry
SENTRY__ENABLED=true

# Sentry DSN (get from your Sentry project settings)
SENTRY__DSN=https://[email protected]/0

# Environment (production, staging, development)
SENTRY__ENVIRONMENT=production

# Release version (optional, defaults to bindu version)
SENTRY__RELEASE=[email protected]

# Error sampling (1.0 = 100% of errors)
SENTRY__TRACES_SAMPLE_RATE=1.0

# Performance sampling (0.1 = 10% of transactions)
SENTRY__PROFILES_SAMPLE_RATE=0.1

# Enable performance monitoring
SENTRY__ENABLE_TRACING=true

# Disable PII in production
SENTRY__SEND_DEFAULT_PII=false

config = {
    "author": "[email protected]",
    "name": "production_agent",
    "description": "Production agent",
    "deployment": {"url": "http://localhost:3773", "expose": True},
    "skills": []
    # Sentry configured via environment variables
}

bindufy(config, handler)

• ✅ Separate config from code
• ✅ Easy to change without code changes
• ✅ Good for deployment pipelines

​

Configuration Priority

1. In-code config (config["sentry"]) - Highest priority
2. Environment variables (SENTRY__*) - Fallback

​

Configuration Options

"sentry": {
    "enabled": True,                    # Enable/disable Sentry
    "dsn": "https://...",               # Your Sentry DSN
    "environment": "production",        # Environment name
    "release": "[email protected]",       # Optional: Release version
    "traces_sample_rate": 1.0,         # 1.0 = 100% of errors
    "profiles_sample_rate": 0.1,       # 0.1 = 10% of transactions
    "enable_tracing": True,            # Performance monitoring
    "send_default_pii": False,         # Disable PII in production
    "debug": False,                    # Debug mode
}

​

What Gets Tracked

​

✅ All HTTP Endpoints (Automatic)

​

1. A2A Protocol Endpoint

• POST / - Main agent communication endpoint
• Captures errors and performance

​

2. Agent Card Endpoint

• GET /.well-known/agent.json - Agent discovery
• Tracks endpoint availability

​

3. DID Endpoints

• GET/POST /did/resolve - DID resolution
• Monitors identity operations

​

4. Skills Endpoints

• GET /agent/skills - List all skills
• GET /agent/skills/{skill_id} - Get skill details
• GET /agent/skills/{skill_id}/documentation - Get skill docs

​

5. Payment Session Endpoints (X402)

• POST /api/start-payment-session - Start payment
• GET /payment-capture - Payment capture page
• GET /api/payment-status/{session_id} - Payment status

​

6. Static/UI Endpoints

• GET /docs - Chat UI
• GET /favicon.ico - Favicon
• GET /static/* - Static files (CSS/JS)

​

✅ Database Operations (SQLAlchemy)

• SQL queries (parameterized, no sensitive data)
• Query execution time
• Database connection errors
• Slow query warnings
• Transaction failures

​

✅ Redis Operations

• Redis commands (LPUSH, BRPOP, etc.)
• Command execution time
• Connection errors
• Timeout errors
• Queue operations

​

✅ Logging Events

from bindu.utils.logging import get_logger

logger = get_logger("my_module")

# This creates a Sentry event
logger.error("Task processing failed", task_id=task_id, error=str(e))

# These become breadcrumbs (context for errors)
logger.info("Processing task", task_id=task_id)
logger.debug("Fetching from database")

• Error-level logs → Sentry events
• All logs → Breadcrumbs (context trail)

​

✅ Async Operations

• Unhandled exceptions in async tasks
• Coroutine context
• Task stack traces

​

❌ What’s NOT Captured (Filtered)

• /healthz
• /health
• /metrics
• /favicon.ico

• authorization headers
• x-api-key headers
• cookie headers
• password fields
• token fields
• secret fields
• api_key fields
• private_key fields

​

Getting Started

​

1. Create Sentry Account

• Go to sentry.io
• Create an account (free tier available)
• Create a new project (select “Python” as platform)

​

2. Get Your DSN

1. Navigate to Settings → Projects → [Your Project]
2. Go to Client Keys (DSN)
3. Copy the DSN URL

https://[email protected]/0

​

3. Configure Bindu

config = {
    "author": "[email protected]",
    "name": "my_agent",
    "description": "My awesome agent",
    "deployment": {"url": "http://localhost:3773", "expose": True},
    "skills": [],
    
    "sentry": {
        "enabled": True,
        "dsn": "https://[email protected]/123456",
        "environment": "production",
        "traces_sample_rate": 1.0,
        "profiles_sample_rate": 0.1,
    }
}

​

4. Run Your Agent

python my_agent.py

✅ Sentry initialized successfully

​

5. Test Error Tracking

from bindu.observability import capture_exception

try:
    1 / 0
except Exception as e:
    capture_exception(e, tags={"test": "true"})

​

Features

​

Automatic Error Capture

def handler(messages):
    # This error will be automatically sent to Sentry
    result = some_function_that_might_fail()
    return result

​

Manual Error Capture

from bindu.observability import capture_exception

try:
    risky_operation()
except Exception as e:
    capture_exception(
        e,
        tags={"operation": "risky", "user_id": "123"},
        extra={"input_data": data}
    )

​

Breadcrumbs

from bindu.observability import add_breadcrumb

add_breadcrumb(
    message="User requested task",
    category="task",
    level="info",
    data={"task_id": "123", "type": "question-answering"}
)

​

User Context

from bindu.observability import set_user

set_user(
    user_id="user-123",
    email="[email protected]",
    username="john_doe"
)

​

Custom Context

from bindu.observability import set_context

set_context("task", {
    "task_id": "task-123",
    "conversation_id": "conv-456",
    "status": "working"
})

​

Performance Monitoring

from bindu.observability import start_transaction

with start_transaction(name="process_task", op="task") as transaction:
    # Your code here
    result = process_task(task_id)
    
    # Add custom measurements
    transaction.set_measurement("tokens_used", 1500, "token")

​

Message Capture

from bindu.observability import capture_message

capture_message(
    "High memory usage detected",
    level="warning",
    tags={"component": "worker"},
    extra={"memory_mb": 8192}
)

​

Best Practices

​

1. Environment Configuration

# Production
SENTRY__ENVIRONMENT=production
SENTRY__TRACES_SAMPLE_RATE=1.0
SENTRY__PROFILES_SAMPLE_RATE=0.1

# Staging
SENTRY__ENVIRONMENT=staging
SENTRY__TRACES_SAMPLE_RATE=1.0
SENTRY__PROFILES_SAMPLE_RATE=0.5

# Development
SENTRY__ENABLED=false  # Or use a separate Sentry project

​

2. Release Tracking

SENTRY__RELEASE=[email protected]

SENTRY__RELEASE=bindu@$(git rev-parse --short HEAD)

​

3. Sample Rates

SENTRY__TRACES_SAMPLE_RATE=1.0  # 100% of errors
SENTRY__PROFILES_SAMPLE_RATE=1.0  # 100% of transactions

SENTRY__TRACES_SAMPLE_RATE=1.0  # 100% of errors
SENTRY__PROFILES_SAMPLE_RATE=0.1  # 10% of transactions

SENTRY__TRACES_SAMPLE_RATE=1.0  # 100% of errors (always capture errors)
SENTRY__PROFILES_SAMPLE_RATE=0.01  # 1% of transactions

​

4. PII Scrubbing

# Production - disable PII
SENTRY__SEND_DEFAULT_PII=false

• Passwords
• API keys
• Tokens
• Credit card numbers
• Social security numbers

​

5. Filter Noise

# In settings.py
SENTRY__IGNORE_ERRORS=["KeyboardInterrupt", "SystemExit", "ExpectedError"]

# In settings.py
SENTRY__FILTER_TRANSACTIONS=["/healthz", "/health", "/metrics"]

​

6. Alert Configuration

• Critical errors: Immediate notification (Slack, PagerDuty)
• Performance degradation: Daily digest
• New issues: Weekly summary

​

7. Context Enrichment

# Good
capture_exception(
    error,
    tags={"component": "task_processor", "task_type": "qa"},
    extra={"task_id": task_id, "input_size": len(messages)}
)

# Bad
capture_exception(error)  # No context

​

Monitoring & Dashboards

​

Sentry Dashboard

1. Error Rate: Errors per hour/day
2. Crash-Free Sessions: % of sessions without crashes
3. Response Time: p50, p95, p99 latencies
4. Throughput: Requests per second
5. Top Errors: Most frequent errors
6. Slow Transactions: Slowest operations

​

Custom Dashboards

• Task processing performance
• LLM API latency
• Database query performance
• Redis operation metrics
• User-specific errors

​

Alerts

• Error rate > threshold
• New error types
• Performance degradation
• Specific error patterns
• Release health issues

​

Troubleshooting

​

Sentry Not Initializing

1. Check SENTRY__ENABLED=true
2. Verify DSN is correct
3. Check network connectivity to Sentry
4. Look for initialization errors in logs

​

Too Many Events

1. Reduce SENTRY__PROFILES_SAMPLE_RATE
2. Filter out noisy transactions
3. Ignore expected errors
4. Upgrade Sentry plan

​

Missing Context

1. Add breadcrumbs before operations
2. Set user context
3. Add custom context
4. Increase SENTRY__MAX_BREADCRUMBS

​

Performance Impact

1. Reduce sampling rates
2. Disable profiling
3. Filter transactions
4. Use async transport (default)

​

Security Considerations

​

1. DSN Protection

• Don’t commit DSN to public repos (use environment variables)
• Rotate DSN if exposed
• Use Sentry’s rate limiting

​

2. PII Scrubbing

SENTRY__SEND_DEFAULT_PII=false

​

3. Data Retention

• Default: 90 days
• Can be reduced for compliance
• Can be extended with paid plans

​

4. Self-Hosted Option

# Point to your self-hosted instance
SENTRY__DSN=https://[email protected]/project-id

​

Cost Optimization

​

Free Tier

• 5,000 errors/month
• 10,000 performance units/month
• 1 project
• 30-day data retention

​

Optimization Tips

1. Sample transactions: Use low PROFILES_SAMPLE_RATE
2. Filter noise: Exclude health checks, metrics
3. Ignore errors: Filter expected errors
4. Use environments: Separate dev/staging/prod projects
5. Monitor quota: Set up quota alerts

​

Paid Plans

• Higher error volume
• More projects
• Longer retention
• Advanced features (SAML SSO, etc.)

​

Comparison with Alternatives

​

Conclusion

• ✅ Real-time error tracking: Catch issues as they happen
• ✅ Performance monitoring: Optimize agent response times
• ✅ Release health: Track deployment stability
• ✅ Deep integration: Starlette, SQLAlchemy, Redis, Loguru
• ✅ Privacy-first: PII scrubbing and compliance
• ✅ Free tier: Get started without cost

• PostgreSQL Storage Documentation
• Redis Scheduler Documentation
• Sentry Documentation