API Reference

Full reference for all functions in the statly module.

Initialization

init()

Initialize the SDK. Call once at application startup.

def init(
    dsn: str,
    environment: str | None = None,
    release: str | None = None,
    debug: bool = False,
    sample_rate: float = 1.0,
    max_breadcrumbs: int = 100,
    before_send: Callable | None = None,
    transport: Transport | None = None,
) -> None

Parameters:

dsn - Data Source Name (required)
environment - Environment name
release - Application version
debug - Enable debug logging
sample_rate - Event sampling rate (0.0-1.0)
max_breadcrumbs - Maximum breadcrumbs per event
before_send - Callback to filter/modify events
transport - Custom transport implementation

Example:

from statly_observe import Statly
 
Statly.init(
    dsn='https://[email protected]/your-org',
    environment='production',
    release='1.2.3',
)

Capturing Events

capture_exception()

Capture an exception.

def capture_exception(
    exception: BaseException | None = None,
    context: dict | None = None,
) -> str

Parameters:

exception - Exception to capture (uses current if None)
context - Additional context data

Returns: Event ID (UUID string)

Example:

from statly_observe import Statly
 
try:
    risky_operation()
except Exception as e:
    event_id = Statly.capture_exception(e, context={
        'operation': 'risky_operation',
        'user_id': current_user.id,
    })
    print(f'Captured: {event_id}')

capture_message()

Capture a message event.

def capture_message(
    message: str,
    level: str = 'info',
    context: dict | None = None,
) -> str

Parameters:

message - Message text
level - Severity: debug, info, warning, error, fatal
context - Additional context data

Returns: Event ID

Example:

from statly_observe import Statly
 
Statly.capture_message('User completed checkout', level='info')
Statly.capture_message('Payment retry needed', level='warning')
Statly.capture_message('Critical system error', level='fatal')

Context Management

set_user()

Set user context for all future events.

def set_user(
    id: str | None = None,
    email: str | None = None,
    username: str | None = None,
    **kwargs,
) -> None

Example:

from statly_observe import Statly
 
# Set user after login
Statly.set_user(
    id='user_123',
    email='[email protected]',
    username='janedoe',
    plan='enterprise',  # Custom field
)
 
# Clear user on logout
Statly.set_user()  # No args clears user

set_tag()

Set a single tag.

def set_tag(key: str, value: str) -> None

Example:

from statly_observe import Statly
 
Statly.set_tag('feature', 'checkout')
Statly.set_tag('experiment', 'new_ui')

set_tags()

Set multiple tags at once.

def set_tags(tags: dict[str, str]) -> None

Example:

from statly_observe import Statly
 
Statly.set_tags({
    'region': 'us-east-1',
    'service': 'payment-api',
    'version': '2.1.0',
})

Breadcrumbs

add_breadcrumb()

Add a breadcrumb to the trail.

def add_breadcrumb(
    message: str,
    category: str | None = None,
    level: str = 'info',
    data: dict | None = None,
    type: str = 'default',
) -> None

Example:

from statly_observe import Statly
 
# Navigation
Statly.add_breadcrumb(
    message='User navigated to /checkout',
    category='navigation',
    level='info',
)
 
# Database query
Statly.add_breadcrumb(
    message='SELECT * FROM users WHERE id = ?',
    category='query',
    level='info',
    data={'duration_ms': 45},
)
 
# HTTP request
Statly.add_breadcrumb(
    message='POST /api/orders',
    category='http',
    level='info',
    data={'status': 201, 'duration': 245},
)

Lifecycle

flush()

Wait for all pending events to be sent.

def flush(timeout: float | None = None) -> None

Example:

from statly_observe import Statly
 
Statly.capture_message('Important event')
Statly.flush(timeout=5.0)  # Wait up to 5 seconds

close()

Flush pending events and shut down the SDK.

def close(timeout: float | None = None) -> None

Example:

from statly_observe import Statly
import atexit
 
Statly.init(dsn='...')
atexit.register(lambda: Statly.close(timeout=2.0))

get_client()

Get the SDK client instance.

def get_client() -> StatlyClient | None

Example:

from statly_observe import Statly
 
client = Statly.get_client()
if client:
    print('SDK is initialized')

Exception Handling

Unhandled exceptions are automatically captured when Statly.init() is called. The SDK installs a Python exception hook that captures any unhandled exceptions before the program exits.

Configuration Flask