Full Integration for Python Logs
About Shipbook
Shipbook gives you the power to remotely gather, search and analyze your user logs and exceptions in the cloud, on a per-user & session basis.
The Python SDK plugs into Python's standard logging module. There is no separate Shipbook logging API: the logging calls your code already makes are sent to Shipbook, with their source location, logger name, thread and traceback.
Requirements
Python 3.9 and up.
Installation
Shipbook is available through: PyPI
pip install shipbook
The SDK has no required dependencies. Each web framework helper is an optional extra:
pip install "shipbook[fastapi]" # or [flask], [django], [mcp]
Integrating Shipbook into your code
To initialize, add the following once, where your app starts:
import shipbook
shipbook.start(app_id="YOUR_APP_ID", app_key="YOUR_APP_KEY")
start() returns at once. It logs in to Shipbook in the background, so your app's startup never waits for the network; logs written meanwhile are kept and sent after the login.
The app version is read from the nearest pyproject.toml ([project] or [tool.poetry]), from the working directory up. You can also provide it yourself:
shipbook.start(app_id="YOUR_APP_ID", app_key="YOUR_APP_KEY", app_version="1.0.0")
To have a log on each module, create a logger the standard way. Its name is the log's tag in Shipbook:
import logging
log = logging.getLogger(__name__)
The usage of the log:
log.error("the log message") # Error log
log.warning("the log message") # Warning log
log.info("the log message") # Info log
log.debug("the log message") # Debug log
log.exception("payment failed") # Error log with the current exception and its traceback
An exception raised from another one names its cause: could not load the order (caused by KeyError: 'missing').
Log levels
Two things decide what reaches Shipbook:
-
Python's own log levels. Python creates a log record only if the logger's level allows it, and by default it drops info and debug logs. To send them, set the level yourself, or pass
capture_leveltostart(), which sets the root logger's level:import logging
shipbook.start(app_id="YOUR_APP_ID", app_key="YOUR_APP_KEY", capture_level=logging.INFO)logging.DEBUGalso sends the debug logs of the libraries you use. -
The app's configuration in the Shipbook console. It decides which tags and severities are uploaded, and you can change it without redeploying.
Console output
What your app prints stays as it is. Python prints warnings and errors by itself only while no handler is attached, so Shipbook prints them the same way when it is the only handler. Once your app configures logging, its own handlers decide what is printed.
Attaching to a specific logger
By default every logger in the process is sent. To send only one logger's logs, attach the handler yourself:
shipbook.start(app_id="YOUR_APP_ID", app_key="YOUR_APP_KEY", attach_to_root=False)
logging.getLogger("myapp").addHandler(shipbook.get_handler())
Enable Shipbook debug logging
If your logs weren't uploaded to Shipbook, or you're experiencing some other issue with Shipbook, you can enable Shipbook debug logging to track down the problem. It prints what the SDK does to stderr: the login, each upload, and why either failed.
shipbook.enable_inner_log(True)
Flush
Logs are sent in batches, every few seconds. To send everything waiting right now:
shipbook.flush()
Web frameworks
A log record doesn't know which request it belongs to. The framework middleware gives each request its own context, so in the Logbook its logs are grouped under it, with the request's method, route, status and duration, and with the user who made it.
Every request is counted. A request is shown in the Logbook when it logged something, and always when it failed with a 5xx status. An exception your code didn't handle is sent as an error of that request, with the line of your code that raised it.
FastAPI and Starlette
from shipbook.integrations.fastapi import ShipbookMiddleware
app.add_middleware(ShipbookMiddleware)
Flask
from shipbook.integrations.flask import init_app
init_app(app)
Django
Add the middleware to MIDDLEWARE in settings.py, after Django's session and authentication middleware. It works with sync and async views:
MIDDLEWARE = [
# ... your other middleware ...
"django.contrib.sessions.middleware.SessionMiddleware",
"django.contrib.auth.middleware.AuthenticationMiddleware",
"shipbook.integrations.django.ShipbookMiddleware",
]
Linking Shipbook to a user's information
A server handles many users at once, so the user is attached to each request with a user_extractor. It gets the framework's request and returns a shipbook.User, or None when nobody is signed in:
def signed_in_user(request):
account = getattr(request.state, "account", None) # set by your own auth
return account and shipbook.User(user_id=account.id, email=account.email)
app.add_middleware(ShipbookMiddleware, user_extractor=signed_in_user)
Flask's init_app takes the same user_extractor.
When the user is only known inside the handler, for example in a sign-in endpoint, register it there:
shipbook.register_user("USER_ID", email="USER_EMAIL")
On Django the signed-in user is attached by itself, once your view has read request.user: its id, username and email. The middleware never loads the user itself, so it adds no query to a request. To attach something else, or nobody, subclass the middleware, override get_user, and put your subclass's path in MIDDLEWARE instead:
from shipbook import User
from shipbook.integrations.django import ShipbookMiddleware as ShipbookBase
class ShipbookMiddleware(ShipbookBase):
def get_user(self, request):
account = getattr(request, "account", None) # set by your own auth
return account and User(user_id=str(account.id), full_name=account.name)
The only required field is user_id; user_name, full_name, email, phone_number and additional_info are optional.
Sessions
By default every request is its own session. To read a visitor's requests as one session, return the same id for them from a session_extractor, for example a login cookie:
app.add_middleware(
ShipbookMiddleware,
session_extractor=lambda request: request.cookies.get("login"),
)
On Django a request joins its Django session when it has one. Override get_session_id to change that.
When a client app with a Shipbook SDK calls your API and sends its x-shipbook-session header, the request joins that app session, and the Logbook shows the app's logs and your server's in one timeline. Nothing to configure on the server: see Cross-App Session Linking.
Request Attributes
Each request records its path, IP address and user agent, and the Logbook shows them in the request's header. Add your own facts with an attributes_extractor (string, number or boolean values); they are shown there too:
app.add_middleware(
ShipbookMiddleware,
attributes_extractor=lambda request: {"tenant": request.headers.get("x-tenant", "public")},
)
Flask's init_app takes the same attributes_extractor. On Django, override get_attributes.
The request's trace id is taken from the traceparent, x-request-id or x-correlation-id header. To take it from somewhere else, pass a trace_extractor (on Django, override get_trace_id).
MCP Servers
If your Python app is an MCP server, each MCP call shows in the Logbook as its own request: the tool, prompt or resource it was asked for (tools/call get-logs), how long it took, and whether it failed, with the logs your tool wrote grouped under it.
- MCP over HTTP behind FastAPI, Starlette, Flask or Django: nothing to add. The middleware above already labels each call.
- Any other transport, stdio included: add the Shipbook middleware to a server built with the
mcpSDK (2.x):
from mcp.server.mcpserver import MCPServer
from shipbook.integrations.mcp import ShipbookMiddleware
server = MCPServer("my-server", middleware=[ShipbookMiddleware()])
A tool that raises, or answers with isError, is marked failed.
Background Jobs
For background jobs and workers, wrap each run:
with shipbook.run_in_context("send-emails", attributes={"batch": batch_id}):
# All logs inside here are grouped under this job
log.info("Processing email batch")
Each run is its own session and counts as one request, like an HTTP request: it appears in the request counts and error rates, and the Logbook shows when it started, how long it took, and whether it raised. attributes is optional: the job's own facts, shown on its session.
Logs written outside any request or job are kept in one session per process.
Other Units of Work
For work that isn't an HTTP request, such as a queue message, run_in_request reads it as one request: its logs are grouped together, with how long it took and whether it failed (an exception marks it failed).
with shipbook.run_in_request(shipbook.RequestKind.Rpc, "process-order"):
log.info("Processing order %s", message.order_id)
Threads and Executors
A request's context follows await and asyncio tasks by itself. A thread or an executor you start yourself begins without it, so its logs would land outside the request. Wrap the function to carry the context along:
pool.submit(shipbook.preserve_context(send_confirmation), order_id)
Crashes and Shutdown
The SDK sends what it has before the process ends, with no setup:
- An uncaught exception is recorded and sent before Python prints it and exits. An exception that ends another thread is recorded too, and one in an
asynciotask arrives as an error log. - At exit, and on
SIGTERMorSIGINT(a deploy, Ctrl+C), pending logs are sent, waiting at most 2 seconds. Your own signal handlers still run afterwards.
Each stack frame is marked as your code or not: the standard library and installed packages are not. If your app is itself installed as a package (pip install .), name it so its frames count as yours:
shipbook.start(app_id="YOUR_APP_ID", app_key="YOUR_APP_KEY", in_app_include=["myapp"])
Forked workers, for example gunicorn with --preload, each send their own logs.
When you stop the SDK yourself, call shutdown. It sends pending logs and stops listening:
shipbook.shutdown()