> ## Documentation Index
> Fetch the complete documentation index at: https://docs.steadwing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install the Steadwing Python SDK to auto-capture exceptions, error logs, and HTTP breadcrumbs from your Python applications and send them to Steadwing for AI-powered root cause analysis.

## What is the Steadwing Python SDK?

The Steadwing Python SDK auto-captures exceptions, error logs, and HTTP breadcrumbs from your Python applications and sends them to Steadwing for root cause analysis. Add two lines of code and Steadwing starts monitoring your application no manual instrumentation required.

<CardGroup cols={2}>
  <Card title="Auto-Capture" icon="bolt">
    Unhandled exceptions, error logs, and thread crashes captured automatically
  </Card>

  <Card title="HTTP Breadcrumbs" icon="globe">
    Outgoing HTTP requests recorded with method, URL, status, and duration
  </Card>

  <Card title="FastAPI Support" icon="server">
    Automatic route error capture with request context when FastAPI is installed
  </Card>

  <Card title="Data Scrubbing" icon="shield">
    Sensitive fields (passwords, tokens, API keys) redacted before sending
  </Card>
</CardGroup>

## Installation

```bash theme={null}
pip install steadwing
```

Requires Python 3.10+. View on [PyPI](https://pypi.org/project/steadwing/) or browse the [source on GitHub](https://github.com/steadwing/steadwing-python).

## Quick Start

Get your API key from [app.steadwing.com/organization](https://app.steadwing.com/organization), then initialize the SDK:

```python theme={null}
import steadwing

steadwing.init(
    api_key="st_your_api_key"
)
```

That's it. The SDK automatically:

* Captures unhandled exceptions (including in threads)
* Captures `logging.error()` and `logging.critical()` calls
* Records outgoing HTTP requests as breadcrumbs
* Sends heartbeats every 60 seconds
* Patches supported frameworks to capture route errors with request context

## Configuration

```python theme={null}
steadwing.init(
    api_key="st_...",           # Required: your API key
    service="my-service",       # Optional: defaults to "default"
    env="PROD",                 # Optional: defaults to "PROD"
    enabled=True,               # Optional: set False to disable
)
```

<Note>
  Only events sent with `env="PROD"` are considered for auto-monitoring. Events from other environments are received but will not trigger automated RCA.
</Note>

## Manual Capture

For cases where you want to explicitly report errors or messages:

<Tabs>
  <Tab title="Capture Exception">
    ```python theme={null}
    import steadwing

    # Capture a specific exception
    try:
        risky_operation()
    except Exception as e:
        steadwing.capture_exception(e)

    # Capture the current exception (in an except block)
    try:
        risky_operation()
    except Exception:
        steadwing.capture_exception()
    ```
  </Tab>

  <Tab title="Capture Message">
    ```python theme={null}
    import steadwing

    steadwing.capture_message("Deployment completed", level="info")
    ```
  </Tab>
</Tabs>

## What Gets Captured

### Exceptions

| Data            | Description                                      |
| --------------- | ------------------------------------------------ |
| Stack trace     | Full trace with local variables                  |
| Exception chain | `__cause__` and `__context__` included           |
| Breadcrumbs     | Last 100 events leading up to the error          |
| Request context | Method, path, headers (for web framework routes) |

### Logs

* `logging.error()` and `logging.critical()` are sent as events
* All log levels are recorded as breadcrumbs for context

### HTTP Breadcrumbs

Every outgoing HTTP request is recorded with:

* Method and URL
* Response status code
* Request duration
* Rolling buffer of last 100 entries

## Data Scrubbing

Sensitive data is automatically scrubbed before leaving your application. Keys matching the following patterns (case-insensitive) have their values replaced with `[REDACTED]`:

```
password, passwd, secret, api_key, apikey, token, auth,
authorization, cookie, csrf, session, credit_card, ssn
```

## Framework Support

The SDK auto-detects installed frameworks and patches them automatically. No extra configuration needed.

| Framework      | What's Captured                                                |
| -------------- | -------------------------------------------------------------- |
| **FastAPI**    | Route errors with full request context (method, path, headers) |
| **Django**     | Middleware-based exception capture with request metadata       |
| **Flask**      | Error handler integration with request context                 |
| **SQLAlchemy** | Database query breadcrumbs (query, duration)                   |
| **Django ORM** | Database query breadcrumbs via cursor wrapper                  |
| **asyncio**    | Unhandled exceptions in async tasks and event loops            |

## FAQs

<AccordionGroup>
  <Accordion title="Do I need to change my code?">
    No. After calling `steadwing.init()`, the SDK hooks into Python's exception handling and logging system automatically. Manual capture is available for cases where you want explicit control.
  </Accordion>

  <Accordion title="What's the performance impact?">
    Minimal. Events are sent asynchronously and the SDK adds negligible overhead to your application. Breadcrumbs are stored in a fixed-size ring buffer.
  </Accordion>

  <Accordion title="Can I disable it in development?">
    Yes. Pass `enabled=False` to `steadwing.init()` and the SDK becomes a no-op no patches are installed and no events are sent.
  </Accordion>

  <Accordion title="How does it work with existing error tracking (Sentry, etc.)?">
    The SDK coexists with other error trackers. It hooks into `sys.excepthook` and the logging module without interfering with other handlers.
  </Accordion>

  <Accordion title="Is my data secure?">
    Sensitive fields are scrubbed before transmission. Data is sent over HTTPS to Steadwing's backend. See the Data Scrubbing section for details on what's redacted.
  </Accordion>
</AccordionGroup>

Need help? Contact us at [hello@steadwing.com](mailto:hello@steadwing.com)