logbench 0.1.0

Python SDK for Logbench

logbench-python

A Python SDK for Logbench

Install

uv add logbench

pip install logbench

Quick start

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.

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

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.

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:

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