From 8477bd7986af3d320133b1528792956de6307abd Mon Sep 17 00:00:00 2001 From: David Friedel Date: Sat, 27 Dec 2025 10:40:21 +0000 Subject: [PATCH] Update README with branded header and documentation links MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add centered logo and title with product branding - Add links to product website and documentation - Add badges for package manager and license - Add Other SDKs table with cross-references - Add Support section with dev@ironservices.io email - Update repository links to git.marketally.com 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 217 +++++++++++++++++++++++++----------------------------- 1 file changed, 99 insertions(+), 118 deletions(-) diff --git a/README.md b/README.md index f78d452..6d8e864 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,41 @@ -# IronTelemetry SDK for Python +

+ + IronTelemetry + +

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

IronTelemetry SDK for Python

-[![PyPI](https://img.shields.io/pypi/v/irontelemetry.svg)](https://pypi.org/project/irontelemetry/) -[![Python](https://img.shields.io/pypi/pyversions/irontelemetry.svg)](https://pypi.org/project/irontelemetry/) -[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +

+ Error monitoring and crash reporting for Python applications +

+ +

+ PyPI version + Python versions + License: MIT +

+ +

+ Website • + Documentation • + Python Guide • + Git +

+ +--- + +**IronTelemetry** helps you capture exceptions, track user journeys, and get actionable insights to fix issues faster. Built for developers who want simple, powerful error monitoring without the complexity. + +## Features + +- **Exception Capture** - Automatically capture and report exceptions with full stack traces +- **Journey Tracking** - Understand what users did before an error occurred +- **Breadcrumbs** - Add context with custom breadcrumbs and metadata +- **Framework Support** - Built-in integrations for Django, Flask, FastAPI +- **Async Support** - Full async/await support +- **Type Hints** - Complete type annotations for IDE support +- **Offline Queue** - Events are queued when offline and sent when connectivity returns ## Installation @@ -14,15 +45,17 @@ pip install irontelemetry ## Quick Start -### Basic Exception Capture +### Initialize the SDK ```python import irontelemetry -# Initialize with your DSN irontelemetry.init("https://pk_live_xxx@irontelemetry.com") +``` -# Capture exceptions +### Capture Exceptions + +```python try: do_something() except Exception as e: @@ -30,14 +63,9 @@ except Exception as e: raise ``` -### Journey Tracking - -Track user journeys to understand the context of errors: +### Track User Journeys ```python -import irontelemetry - -# Track a complete user journey with irontelemetry.start_journey("Checkout Flow"): irontelemetry.set_user("user-123", "user@example.com") @@ -51,7 +79,48 @@ with irontelemetry.start_journey("Checkout Flow"): send_confirmation_email() ``` -Any exceptions captured during the journey are automatically correlated. +### Add Breadcrumbs + +```python +from irontelemetry import add_breadcrumb, BreadcrumbCategory + +add_breadcrumb("User clicked checkout button", BreadcrumbCategory.UI) +add_breadcrumb("Payment API called", BreadcrumbCategory.HTTP) +``` + +## Framework Integrations + +### Django + +```python +# settings.py +INSTALLED_APPS = [ + 'irontelemetry.django', + # ... +] + +IRONTELEMETRY_DSN = "https://pk_live_xxx@irontelemetry.com" +``` + +### Flask + +```python +from flask import Flask +from irontelemetry.flask import IronTelemetry + +app = Flask(__name__) +IronTelemetry(app, dsn="https://pk_live_xxx@irontelemetry.com") +``` + +### FastAPI + +```python +from fastapi import FastAPI +from irontelemetry.fastapi import IronTelemetryMiddleware + +app = FastAPI() +app.add_middleware(IronTelemetryMiddleware, dsn="https://pk_live_xxx@irontelemetry.com") +``` ## Configuration @@ -62,119 +131,31 @@ init(TelemetryOptions( dsn="https://pk_live_xxx@irontelemetry.com", environment="production", app_version="1.2.3", - sample_rate=1.0, # 100% of events + sample_rate=1.0, debug=False, before_send=lambda event: event if "expected" not in (event.message or "") else None, )) ``` -### Configuration Options +## Documentation -| 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 | +For complete documentation, visit [irontelemetry.com/docs](https://irontelemetry.com/docs). -## Features +## Other SDKs -- **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 +| Platform | Package | +|----------|---------| +| JavaScript/TypeScript | [@ironservices/telemetry](https://git.marketally.com/ironservices/irontelemetry-js) | +| .NET | [IronTelemetry.Client](https://git.marketally.com/ironservices/irontelemetry-dotnet) | +| Go | [irontelemetry-go](https://git.marketally.com/ironservices/irontelemetry-go) | +| Java | [irontelemetry-java](https://git.marketally.com/ironservices/irontelemetry-java) | +| Rust | [irontelemetry](https://git.marketally.com/ironservices/irontelemetry-rust) | -## Breadcrumbs +## Support -```python -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 - -```python -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 - -```python -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 - -```python -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 - -```python -# Flush pending events before app shutdown -irontelemetry.flush() -``` - -## Type Support - -This package includes full type annotations: - -```python -from irontelemetry import ( - TelemetryOptions, - TelemetryEvent, - Breadcrumb, - SeverityLevel, - BreadcrumbCategory, -) -``` - -## Python Version Support - -- Python 3.8+ -- Full type hints support -- async/await support +- **Documentation**: [irontelemetry.com/docs](https://irontelemetry.com/docs) +- **Email**: dev@ironservices.io +- **Issues**: [git.marketally.com/ironservices/irontelemetry-python/issues](https://git.marketally.com/ironservices/irontelemetry-python/issues) ## License