Metadata-Version: 2.5
Name: blipit
Version: 0.4.0
Summary: Blipit error monitoring for Python: Django, Flask, FastAPI, Celery and scripts. Know your app broke before your users tell you.
Project-URL: Homepage, https://blipit.io
Project-URL: Documentation, https://docs.blipit.io/python
Project-URL: Changelog, https://blipit.io/changelog
Author-email: Louward Labs <support@blipit.io>
License-Expression: MIT
Keywords: blipit,django,error-monitoring,errors,fastapi,flask,logging
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# blipit

Blipit error monitoring for Python. Know your app broke before your users tell you.

Built on Blipit's own core, blipit-nuggets. No third-party monitoring library, no extra dependencies: the standard library only.

## Install

```sh
pip install blipit
```

## Quick start

Call `init` once at startup, before the app is created. For Django, put it at the top of `settings.py`.

```python
import blipit

blipit.init(key="<public key>", environment="production", release="myapp@1.4.2")
```

The key is on the project's Keys page at app.blipit.io. `project=` is still accepted for older setups and no longer needed. If the key is empty (for example an unset environment variable), `init` logs a warning on the `blipit` logger, returns `False` and Blipit stays off; it never raises, so a missing key cannot stop the app from starting.

## What is reported on its own

- Uncaught exceptions (`sys.excepthook` and threads), sent before the process exits.
- `logging`: records at `ERROR` and above become events, `INFO` and above become breadcrumbs. Change with `logging_event_level=` and `logging_breadcrumb_level=` (`None` turns either off).
- HTTP calls made with `http.client` (so `urllib`, `requests`, `urllib3`) and `httpx` become breadcrumbs.
- Django, Flask, FastAPI and Starlette: unhandled view errors with the request (URL, method, user agent; never cookies, auth headers or bodies), one isolated scope per request.
- Celery: task failures, tagged with the task name.
- Django ORM and SQLAlchemy queries become breadcrumbs with literals replaced by `?`.

Pass `default_integrations=False` to turn all of this off and only send what you capture yourself.

## Manual capture

```python
blipit.capture_exception(err)
blipit.capture_message("cache miss rate above 50%", level="warning")
blipit.set_user({"id": "42", "email": "ana@example.com"})
blipit.set_tag("region", "ap-southeast-1")
blipit.set_context("order", {"id": 1042, "total": 99.5})
blipit.add_breadcrumb(message="cache cleared", category="cache")
blipit.capture_security("login_failed", actor=email, ip=client_ip, outcome="bad_password")
```

Login attempts (`capture_security`) need the project's secret key (init with it on the server) and the Scale plan; with the public key ingest refuses them with 403 `security_needs_secret_key`.

## Options

| Option | Default | |
| --- | --- | --- |
| `environment`, `release` | `production`, none | Shown on every issue. |
| `sample_rate` | `1.0` | Share of error events to send. |
| `traces_sample_rate` | `0.0` | Share of requests and tasks traced for Pulse. |
| `before_send(event, hint)` | none | Change the event (a dict in Blipit's format) or return `None` to drop it. |
| `before_breadcrumb(crumb, hint)` | none | Same for breadcrumbs. |
| `ignore_errors` | `[]` | Exception classes or class names never sent. |
| `server_name` | none | Tag `server` on events, service name on spans. |
| `max_breadcrumbs` | `100` | |
| `include_source_context` | `True` | Five lines of source around each frame. |
| `shutdown_timeout` | `2.0` | Seconds to wait for unsent events at exit. |
| `debug` | `False` | Logs rejected sends and rate limits. |

Other options from older versions are accepted and ignored.

## Pulse (performance)

Pass `traces_sample_rate=0.2` to `init`. Django, Flask, FastAPI and Starlette requests, Celery tasks, outgoing HTTP calls and SQL queries show up on the Pulse page, and errors link to their trace.

## How sending works

Events go to `POST /api/v1/events` and spans to `/v1/traces` from one background thread, with a queue of at most 100 events (the oldest is dropped first). A `429` pauses sending for the `Retry-After` the server gives; a `5xx` or network error is retried twice. Keys and values that look like passwords, tokens, cookies, sessions or card numbers are replaced with `[Filtered]` before anything leaves the process.

## Updates

In development Blipit logs one line on the `blipit` logger when a newer version is out, with the reason and the command. Update with `pip install -U blipit`. Details: https://docs.blipit.io/updates

## Tests

```sh
pip install pytest
python -m pytest
```

Framework smoke tests run when Django, Flask, FastAPI, Celery or SQLAlchemy are installed, and are skipped otherwise.

Docs: https://docs.blipit.io/python

## Package list

About ten seconds after `blipit.init`, a background thread sends the installed distributions (`importlib.metadata`) to Blipit, which checks them against known vulnerabilities (Scale plan, Security, Weak spots). It is sent again only when the list changes, needs the secret key, and `report_packages=False` turns it off.
