Metadata-Version: 2.3
Name: logbench
Version: 0.1.0
Summary: Python SDK for Logbench
Author: Albin Groen
Author-email: Albin Groen <albingroen@proton.me>
Requires-Dist: httpx
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-httpx ; extra == 'dev'
Requires-Python: >=3.10
Provides-Extra: dev
Description-Content-Type: text/markdown

# logbench-python

A Python SDK for [Logbench](https://github.com/albingroen/logbench)

## Install

```bash
uv add logbench
```

```bash
pip install logbench
```

## Quick start

```python
from logbench import Logbench

logger = Logbench(project_id="your-project-id")

logger.info("Server started on port 3000")
logger.warn("Disk usage above 80%")
logger.err("Failed to connect to database")
```

## API

### `Logbench(project_id, **options)`

Creates a new Logbench client.

| Option           | Type   | Required | Description |
| ---------------- | ------ | -------- | ----------- |
| `project_id`     | `str`  | Yes      | Project ID from your Logbench dashboard |
| `url`            | `str`  | No       | Base URL of your Logbench instance. Defaults to `"http://localhost:1447"` |
| `capture_source` | `bool` | No       | Capture the source file and line number of each log. Defaults to `True`; set to `False` to disable. |
| `cwd`            | `str`  | No       | Project root directory. When set, strips this prefix from captured file paths, producing relative paths in the Logbench UI. |

### `logger.info(*content)`

Send an info-level log.

### `logger.warn(*content)`

Send a warning-level log.

### `logger.err(*content)`

Send an error-level log.

All methods accept any number of arguments of any type.

```python
logger.info("User signed in", {"user_id": "abc123", "at": datetime.now()})
logger.err("Request failed", {"status": 500, "headers": {"x-request-id": "abc"}})
```

### `logger.info_with(options, *content)`

### `logger.warn_with(options, *content)`

### `logger.err_with(options, *content)`

Same as `info`, `warn`, and `err`, but with an additional `LogOptions` first argument for attaching metadata:

| Option       | Type   | Description |
| ------------ | ------ | ----------- |
| `bookmark`   | `bool` | Mark this log as bookmarked in the UI |
| `annotation` | `str`  | Free-text annotation to attach to the entry |

```python
logger.info_with(
    {"bookmark": True, "annotation": "deploy v2.1.0"},
    "Deployment started",
    {"version": "2.1.0"},
)
```

### `LogLevel`

Exported enum for the three log levels if you need to reference them directly.

```python
from logbench import LogLevel

LogLevel.Info  # "INFO"
LogLevel.Warn  # "WARNING"
LogLevel.Err   # "ERROR"
```

## Resource management

The client holds an HTTP connection pool. Use it as a context manager or call `close()` when done:

```python
with Logbench(project_id="your-project-id") as logger:
    logger.info("hello")

# or manually
logger = Logbench(project_id="your-project-id")
logger.info("hello")
logger.close()
```

## How it works

Each log call sends a POST request to your Logbench instance:

```
POST {url}/api/projects/{project_id}/logs/ingest
```

Errors from the HTTP call are silently caught so logging never crashes your application.

## Project structure

```
src/logbench/
  __init__.py   Exports
  types.py      Type definitions
  enums.py      LogLevel enum
  utils.py      Internal helpers (source location capture, JSON encoding)
  client.py     Logbench client class
```

## License

MIT
