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

# Python Logging Handler

> Send Python logging records to Squasher with a standard logging.Handler.

If your service already uses Python's built-in `logging` module, add `SquasherHandler` to forward log records to Squasher without replacing the rest of your logging setup.

## Installation

```bash theme={null}
pip install squasher-python
```

## Configuration

Create a handler once, attach it to your logger, and keep the rest of your logging pipeline unchanged.

```python app/logging.py theme={null}
import logging

from squasher import SquasherHandler

handler = SquasherHandler(
    api_key="sq_pk_your_key",
    project_id="your-project-id",
)

logger = logging.getLogger("app")
logger.setLevel(logging.INFO)
logger.addHandler(handler)
```

| Option       | Type  | Default                      | Description                                                    |
| ------------ | ----- | ---------------------------- | -------------------------------------------------------------- |
| `api_key`    | `str` | Required                     | Your project ingest key                                        |
| `project_id` | `str` | Required                     | Your Squasher project ID                                       |
| `endpoint`   | `str` | `https://ingest.squasher.ai` | Override the ingest base URL for local or staging environments |

The handler sends events on a background thread, so `logger.error()` does not block while the HTTP request is in flight.

## Usage Example

```python app/main.py theme={null}
import logging

from squasher import SquasherHandler

handler = SquasherHandler(
    api_key="sq_pk_your_key",
    project_id="your-project-id",
)

logger = logging.getLogger("app")
logger.setLevel(logging.INFO)
logger.addHandler(handler)

logger.info("worker booted")
logger.error("payment capture failed")

handler.flush()
handler.close()
```

<Note>
  Call `flush()` and `close()` during shutdown to make sure queued log records are delivered before
  the process exits.
</Note>

## Exception Handling

Use `logger.exception()` inside an `except` block to include the exception type and traceback automatically.

```python theme={null}
try:
    raise RuntimeError("card processor timed out")
except RuntimeError:
    logger.exception("captured checkout exception")
finally:
    handler.flush()
    handler.close()
```

When `exc_info` is present, the handler sends both the exception type and the formatted stack trace alongside the log message, so the error shows up in Squasher with full debugging context.

## Agent handoff

```text theme={null}
Install squasher-python, add SquasherHandler to the existing logger with SQUASHER_API_KEY and SQUASHER_PROJECT_ID from env, avoid logging secrets, call flush or close during shutdown, and verify with one logger.error call.
```