Update README with branded header and documentation links
- 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 <noreply@anthropic.com>
This commit is contained in:
David Friedel
parent
ed9da3dc55
commit
8477bd7986
217
README.md
217
README.md
|
|
@ -1,10 +1,41 @@
|
|||
# IronTelemetry SDK for Python
|
||||
<p align="center">
|
||||
<a href="https://irontelemetry.com">
|
||||
<img src="https://irontelemetry.com/logo.png" alt="IronTelemetry" width="120" />
|
||||
</a>
|
||||
</p>
|
||||
|
||||
Error monitoring and crash reporting SDK for Python applications. Capture exceptions, track user journeys, and get insights to fix issues faster.
|
||||
<h1 align="center">IronTelemetry SDK for Python</h1>
|
||||
|
||||
[](https://pypi.org/project/irontelemetry/)
|
||||
[](https://pypi.org/project/irontelemetry/)
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
<p align="center">
|
||||
<strong>Error monitoring and crash reporting for Python applications</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://pypi.org/project/irontelemetry/"><img src="https://img.shields.io/pypi/v/irontelemetry.svg" alt="PyPI version"></a>
|
||||
<a href="https://pypi.org/project/irontelemetry/"><img src="https://img.shields.io/pypi/pyversions/irontelemetry.svg" alt="Python versions"></a>
|
||||
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://irontelemetry.com">Website</a> •
|
||||
<a href="https://irontelemetry.com/docs">Documentation</a> •
|
||||
<a href="https://irontelemetry.com/docs/python">Python Guide</a> •
|
||||
<a href="https://git.marketally.com/ironservices">Git</a>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
**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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue