roselabs-falcon 0.1.0

Falcon error tracking SDK for Python

roselabs-falcon

Official Falcon error tracking SDK for Python.

Installation

pip install roselabs-falcon

Quick Start

from falcon_sdk import init, capture_exception

# Initialize Falcon - validates immediately, fails fast on bad config
init(
    api_key="sk_your_api_key",
    app_name="my-app",
    environment="production",
)

# That's it! Now capture errors manually or install auto-capture.

Automatic Exception Capture

from falcon_sdk import Falcon, FalconConfig

falcon = Falcon(FalconConfig(
    api_key="sk_your_api_key",
    app_name="my-app",
    environment="production",
))

# Install automatic exception handler
falcon.install()

# Now uncaught exceptions are automatically reported

Manual Error Capture

from falcon_sdk import capture_exception

try:
    risky_operation()
except Exception as e:
    capture_exception(e, context={"user_id": "123", "action": "checkout"})

Capture Messages

from falcon_sdk import capture_message

capture_message("User completed signup", level="info", context={"plan": "pro"})

User Context

from falcon_sdk import set_user

# Set user context for all future events
set_user(user_id="user-123", email="[e-mail]", name="John Doe")

# Clear user on logout
set_user()

Async Support

from falcon_sdk import Falcon, FalconConfig

falcon = Falcon(FalconConfig(
    api_key="sk_your_api_key",
    app_name="my-app",
))

# Async capture
await falcon.capture_exception_async(error)
await falcon.capture_message_async("Hello", level="info")

Configuration Options

from falcon_sdk import Falcon, FalconConfig

falcon = Falcon(FalconConfig(
    # Required
    api_key="sk_your_api_key",
    app_name="my-app",

    # Optional
    environment="production",           # Default: None
    release="1.0.0",                    # Default: None
    api_url="https://api.falcon.roselabs.io",  # Default
    enabled=True,                       # Default: True
    debug=False,                        # Default: False

    # Rate limiting (prevents error storms)
    max_events_per_minute=60,           # Default: 60, 0=unlimited
    max_events_per_second=10,           # Default: 10, 0=unlimited

    # Before send hook
    before_send=lambda event: event,    # Return None to drop
))

Pre-validation

The SDK validates configuration immediately on initialization. If your config is invalid, you'll get a FalconConfigError right away instead of silent failures later:

from falcon_sdk import init, FalconConfigError

try:
    init(api_key="bad_key", app_name="my-app")  # Missing sk_ prefix
except FalconConfigError as e:
    print(f"Config error: {e}")
    # Invalid Falcon configuration:
    #   - apiKey must start with 'sk_' (e.g., 'sk_your_key_here')

Rate Limiting

Built-in rate limiting prevents error storms from overwhelming your server:

init(
    api_key="sk_xxx",
    app_name="my-app",
    max_events_per_second=10,   # Burst limit
    max_events_per_minute=60,   # Sustained limit
)

When limits are exceeded, events are silently dropped (logged in debug mode).

Logging Integration

Automatically send Python logging errors to Falcon:

import logging
from falcon_sdk import Falcon, FalconConfig

falcon = Falcon(FalconConfig(api_key="sk_xxx", app_name="my-app"))

# Add Falcon handler to root logger
logging.getLogger().addHandler(falcon.get_logging_handler())

# Now logging.error() also reports to Falcon
logging.error("Something went wrong!")

Decorator

Automatically capture errors from functions:

from falcon_sdk import Falcon, FalconConfig

falcon = Falcon(FalconConfig(api_key="sk_xxx", app_name="my-app"))

@falcon.capture_errors
def risky_function():
    raise ValueError("Something went wrong")

@falcon.capture_errors
async def risky_async_function():
    raise ValueError("Async error")

License

MIT