4.7 KiB

Raw Blame History

IronTelemetry SDK for Python

Error monitoring and crash reporting SDK for Python applications. Capture exceptions, track user journeys, and get insights to fix issues faster.

Installation

pip install irontelemetry

Quick Start

Basic Exception Capture

import irontelemetry

# Initialize with your DSN
irontelemetry.init("https://pk_live_xxx@irontelemetry.com")

# Capture exceptions
try:
    do_something()
except Exception as e:
    irontelemetry.capture_exception(e)
    raise

Journey Tracking

Track user journeys to understand the context of errors:

import irontelemetry

# Track a complete user journey
with irontelemetry.start_journey("Checkout Flow"):
    irontelemetry.set_user("user-123", "user@example.com")

    with irontelemetry.start_step("Validate Cart", "business"):
        validate_cart()

    with irontelemetry.start_step("Process Payment", "business"):
        process_payment()

    with irontelemetry.start_step("Send Confirmation", "notification"):
        send_confirmation_email()

Any exceptions captured during the journey are automatically correlated.

Configuration

from irontelemetry import TelemetryOptions, init

init(TelemetryOptions(
    dsn="https://pk_live_xxx@irontelemetry.com",
    environment="production",
    app_version="1.2.3",
    sample_rate=1.0,  # 100% of events
    debug=False,
    before_send=lambda event: event if "expected" not in (event.message or "") else None,
))

Configuration Options

Option	Type	Default	Description
`dsn`	str	required	Your Data Source Name
`environment`	str	'production'	Environment name
`app_version`	str	'0.0.0'	Application version
`sample_rate`	float	1.0	Sample rate (0.0 to 1.0)
`max_breadcrumbs`	int	100	Max breadcrumbs to keep
`debug`	bool	False	Enable debug logging
`before_send`	callable	None	Hook to filter/modify events
`enable_offline_queue`	bool	True	Enable offline queue
`max_offline_queue_size`	int	500	Max offline queue size

Features

Automatic Exception Capture: Capture and report exceptions with full stack traces
Journey Tracking: Track user flows and correlate errors with context
Breadcrumbs: Leave a trail of events leading up to an error
User Context: Associate errors with specific users
Tags & Extras: Add custom metadata to your events
Offline Queue: Events are queued when offline and sent when connectivity returns
Async Support: Full async/await support with capture_exception_async and capture_message_async
Type Hints: Full type annotations for IDE support

Breadcrumbs

from irontelemetry import add_breadcrumb, BreadcrumbCategory

# Add breadcrumbs to understand what happened before an error
add_breadcrumb("User clicked checkout button", BreadcrumbCategory.UI)
add_breadcrumb("Payment API called", BreadcrumbCategory.HTTP)

# Or with full control
add_breadcrumb(
    "User logged in",
    category=BreadcrumbCategory.AUTH,
    level=SeverityLevel.INFO,
    data={"user_id": "123"},
)

Global Exception Handling

import irontelemetry

irontelemetry.init("your-dsn")
irontelemetry.use_unhandled_exception_handler()

This sets up a handler for sys.excepthook to capture uncaught exceptions.

Helper Methods

from irontelemetry import track_step

# Track a step with automatic error handling
track_step("Process Order", lambda: process_order())

# With return value
result = track_step("Calculate Total", lambda: calculate_total())

Async Support

import irontelemetry

# Async exception capture
await irontelemetry.capture_exception_async(error)

# Async message capture
await irontelemetry.capture_message_async("Something happened")

# Async flush
await irontelemetry.flush_async()

Flushing

# Flush pending events before app shutdown
irontelemetry.flush()

Type Support

This package includes full type annotations:

from irontelemetry import (
    TelemetryOptions,
    TelemetryEvent,
    Breadcrumb,
    SeverityLevel,
    BreadcrumbCategory,
)

Python Version Support

Python 3.8+
Full type hints support
async/await support

License

MIT License - see LICENSE for details.

4.7 KiB Raw Blame History