shipbook 0.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- shipbook-0.2.0/.gitignore +14 -0
- shipbook-0.2.0/CHANGELOG.md +23 -0
- shipbook-0.2.0/LICENSE +21 -0
- shipbook-0.2.0/PKG-INFO +205 -0
- shipbook-0.2.0/README.md +163 -0
- shipbook-0.2.0/examples/background_job.py +27 -0
- shipbook-0.2.0/examples/django_settings_snippet.py +35 -0
- shipbook-0.2.0/examples/fastapi_app.py +44 -0
- shipbook-0.2.0/examples/flask_app.py +29 -0
- shipbook-0.2.0/examples/mcp_server.py +31 -0
- shipbook-0.2.0/examples/plain_script.py +30 -0
- shipbook-0.2.0/pyproject.toml +54 -0
- shipbook-0.2.0/src/shipbook/__init__.py +50 -0
- shipbook-0.2.0/src/shipbook/_inner_log.py +23 -0
- shipbook-0.2.0/src/shipbook/_state.py +14 -0
- shipbook-0.2.0/src/shipbook/_util.py +23 -0
- shipbook-0.2.0/src/shipbook/cloud_uploader.py +272 -0
- shipbook-0.2.0/src/shipbook/config.py +108 -0
- shipbook-0.2.0/src/shipbook/connection_client.py +84 -0
- shipbook-0.2.0/src/shipbook/context.py +73 -0
- shipbook-0.2.0/src/shipbook/generated/__init__.py +0 -0
- shipbook-0.2.0/src/shipbook/generated/version.py +2 -0
- shipbook-0.2.0/src/shipbook/handler.py +50 -0
- shipbook-0.2.0/src/shipbook/hooks/__init__.py +0 -0
- shipbook-0.2.0/src/shipbook/hooks/exception_handler.py +48 -0
- shipbook-0.2.0/src/shipbook/hooks/exit_handler.py +52 -0
- shipbook-0.2.0/src/shipbook/integrations/__init__.py +0 -0
- shipbook-0.2.0/src/shipbook/integrations/_common.py +91 -0
- shipbook-0.2.0/src/shipbook/integrations/django.py +97 -0
- shipbook-0.2.0/src/shipbook/integrations/fastapi.py +105 -0
- shipbook-0.2.0/src/shipbook/integrations/flask.py +68 -0
- shipbook-0.2.0/src/shipbook/integrations/mcp.py +59 -0
- shipbook-0.2.0/src/shipbook/models/__init__.py +0 -0
- shipbook-0.2.0/src/shipbook/models/attributes.py +5 -0
- shipbook-0.2.0/src/shipbook/models/exception.py +46 -0
- shipbook-0.2.0/src/shipbook/models/frames.py +59 -0
- shipbook-0.2.0/src/shipbook/models/message.py +92 -0
- shipbook-0.2.0/src/shipbook/models/request_context.py +30 -0
- shipbook-0.2.0/src/shipbook/models/request_event.py +75 -0
- shipbook-0.2.0/src/shipbook/models/session.py +64 -0
- shipbook-0.2.0/src/shipbook/models/user.py +26 -0
- shipbook-0.2.0/src/shipbook/request_events.py +158 -0
- shipbook-0.2.0/src/shipbook/session_manager.py +108 -0
- shipbook-0.2.0/src/shipbook/severity.py +37 -0
- shipbook-0.2.0/src/shipbook/shipbook.py +252 -0
- shipbook-0.2.0/src/shipbook/storage.py +101 -0
- shipbook-0.2.0/tests/__init__.py +0 -0
- shipbook-0.2.0/tests/conftest.py +118 -0
- shipbook-0.2.0/tests/test_cloud_uploader.py +332 -0
- shipbook-0.2.0/tests/test_context.py +70 -0
- shipbook-0.2.0/tests/test_frames.py +61 -0
- shipbook-0.2.0/tests/test_handler_e2e.py +91 -0
- shipbook-0.2.0/tests/test_integrations.py +245 -0
- shipbook-0.2.0/tests/test_mcp.py +100 -0
- shipbook-0.2.0/tests/test_message.py +78 -0
- shipbook-0.2.0/tests/test_process_exit.py +166 -0
- shipbook-0.2.0/tests/test_request_events.py +119 -0
- shipbook-0.2.0/tests/test_session_manager.py +61 -0
- shipbook-0.2.0/tests/test_severity_config.py +91 -0
- shipbook-0.2.0/tests/test_storage.py +39 -0
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [0.2.0]
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
- Sessions are sent as platform `python`, so the console shows them as Python. Before, they appeared as Node.js.
|
|
7
|
+
- Stack frames are sent innermost first, like the other SDKs. This applies to crashes, `logger.exception()` and call stacks.
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
- Each stack frame is marked as your app's code or not (the standard library and installed packages are not), so Loglytics groups a crash by its first line in your code. If your app is installed as a package, name it with `start(in_app_include=["myapp"])`.
|
|
11
|
+
|
|
12
|
+
## [0.1.0]
|
|
13
|
+
|
|
14
|
+
First release of the Shipbook Python server SDK.
|
|
15
|
+
|
|
16
|
+
- Ships the standard library `logging` to Shipbook through one `ShipbookHandler`. `shipbook.start(app_id, app_key)` attaches it to the root logger; every `logging` call, with its source location, logger name, thread and traceback, is batched and uploaded by a background thread. Nothing on the request path blocks on the network, and nothing is written to disk.
|
|
17
|
+
- Web frameworks (FastAPI/Starlette, Flask, Django): each request is recorded with its method, route, path, client IP, user agent, status and duration, and its logs are grouped under it in the Logbook. Extractors attach the user, group requests into a session, set the trace id and add your own `attributes` (string, number or boolean values). A request carrying a client app's `x-shipbook-session` header joins that session, so the Logbook shows the whole flow.
|
|
18
|
+
- JSON-RPC and MCP: a call is labeled with what it asked for (`tools/call get-logs`). `shipbook.integrations.mcp.ShipbookMiddleware` records every call of an `mcp` 2.x server as a request over any transport, and a failed tool as a failed request with its error code.
|
|
19
|
+
- `run_in_context(job_name, attributes=...)` runs a background job as its own session and one request, counted in the request totals and error rates. `run_in_request(kind, operation)` reads any other unit of work the same way, and `preserve_context` carries the request context into threads and executors.
|
|
20
|
+
- With the Accumulate config, logs below warning are held per request and uploaded only when that request logs a warning or error.
|
|
21
|
+
- An uncaught exception is captured and uploaded before Python prints it and exits. Queued logs are uploaded at interpreter exit and on `SIGTERM`/`SIGINT`, waiting at most 2 seconds; `shipbook.flush()` uploads now.
|
|
22
|
+
- No runtime dependencies; each framework helper imports its framework only when used.
|
|
23
|
+
|
shipbook-0.2.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Shipbook
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
shipbook-0.2.0/PKG-INFO
ADDED
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: shipbook
|
|
3
|
+
Version: 0.2.0
|
|
4
|
+
Summary: Shipbook logging SDK for Python servers — ships the standard library logging to Shipbook.
|
|
5
|
+
Project-URL: Homepage, https://shipbook.io
|
|
6
|
+
Project-URL: Documentation, https://docs.shipbook.io
|
|
7
|
+
Project-URL: Source, https://github.com/ShipBook/shipbook-python
|
|
8
|
+
Author-email: Shipbook <support@shipbook.io>
|
|
9
|
+
License: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: logging,logs,monitoring,observability,shipbook
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
21
|
+
Classifier: Topic :: System :: Logging
|
|
22
|
+
Requires-Python: >=3.9
|
|
23
|
+
Provides-Extra: dev
|
|
24
|
+
Requires-Dist: build; extra == 'dev'
|
|
25
|
+
Requires-Dist: django; extra == 'dev'
|
|
26
|
+
Requires-Dist: flask; extra == 'dev'
|
|
27
|
+
Requires-Dist: httpx; extra == 'dev'
|
|
28
|
+
Requires-Dist: mcp>=2; extra == 'dev'
|
|
29
|
+
Requires-Dist: mypy; extra == 'dev'
|
|
30
|
+
Requires-Dist: pytest; extra == 'dev'
|
|
31
|
+
Requires-Dist: ruff; extra == 'dev'
|
|
32
|
+
Requires-Dist: starlette; extra == 'dev'
|
|
33
|
+
Provides-Extra: django
|
|
34
|
+
Requires-Dist: django; extra == 'django'
|
|
35
|
+
Provides-Extra: fastapi
|
|
36
|
+
Requires-Dist: starlette; extra == 'fastapi'
|
|
37
|
+
Provides-Extra: flask
|
|
38
|
+
Requires-Dist: flask; extra == 'flask'
|
|
39
|
+
Provides-Extra: mcp
|
|
40
|
+
Requires-Dist: mcp>=2; extra == 'mcp'
|
|
41
|
+
Description-Content-Type: text/markdown
|
|
42
|
+
|
|
43
|
+
# Shipbook Python SDK
|
|
44
|
+
|
|
45
|
+
Ship your Python server logs to [Shipbook](https://shipbook.io) — with **zero new logging API to learn.** The SDK plugs into Python's standard `logging` module, so the code you already write just works:
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
import logging
|
|
49
|
+
import shipbook
|
|
50
|
+
|
|
51
|
+
shipbook.start(app_id="YOUR_APP_ID", app_key="YOUR_APP_KEY")
|
|
52
|
+
|
|
53
|
+
log = logging.getLogger(__name__)
|
|
54
|
+
log.info("user signed in")
|
|
55
|
+
log.error("payment failed", exc_info=True)
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Every `logging` call in your process is captured, batched, and uploaded to Shipbook in the background. Source location (file, function, line), the logger name (as the tag), thread info, and exception tracebacks all come across automatically — because Python's `logging` already records them.
|
|
59
|
+
|
|
60
|
+
## Install
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pip install shipbook
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Zero required dependencies. Optional framework helpers:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
pip install "shipbook[fastapi]" # or [flask], [django], [mcp]
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## How it works
|
|
73
|
+
|
|
74
|
+
`shipbook.start()` attaches a single `ShipbookHandler` to the root logger and returns at once; it logs in to Shipbook on a background thread, so an unreachable API never delays your app's startup. There is **no** separate Shipbook logging API — `ShipbookHandler` *is* the SDK. Logs are kept in memory and uploaded in batches by a background thread; nothing on your request path blocks on the network, and nothing is written to disk.
|
|
75
|
+
|
|
76
|
+
What ships is controlled by two independent gates:
|
|
77
|
+
|
|
78
|
+
1. **Standard `logging` levels** — records are only created if the logger's level allows them. To ship `DEBUG`/`INFO`, make sure the level permits it (or pass `capture_level=logging.DEBUG` to `start()`).
|
|
79
|
+
2. **Server-side config** — Shipbook's dashboard controls which tags/severities are actually uploaded, and can be changed without a redeploy. Until the first config arrives, logs are held and then filtered by it, so a filter set in the dashboard also applies to startup logs.
|
|
80
|
+
|
|
81
|
+
With the **Accumulate** config, logs below the warning level are held per request and uploaded only when that request logs a warning or error — as their context. Healthy requests cost nothing.
|
|
82
|
+
|
|
83
|
+
To point the SDK at another Shipbook API (for example a staging environment), call `shipbook.set_connection_url(url)` before `start()`.
|
|
84
|
+
|
|
85
|
+
## Attaching to a specific logger
|
|
86
|
+
|
|
87
|
+
By default the handler is attached to the root logger. To scope it yourself:
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
shipbook.start(app_id="...", app_key="...", attach_to_root=False)
|
|
91
|
+
logging.getLogger("myapp").addHandler(shipbook.get_handler())
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
## Web frameworks — read your server request by request
|
|
95
|
+
|
|
96
|
+
A `LogRecord` doesn't know which request it belongs to. The framework integrations bind each request to a Shipbook **session**, so logs carry the user, client IP, and trace id. Each request is also recorded with its method, route (`/items/{item_id}`), status and duration, and its logs are grouped under it in the Logbook. A failed request (5xx) is always recorded, even if it logged nothing.
|
|
97
|
+
|
|
98
|
+
**FastAPI / Starlette**
|
|
99
|
+
|
|
100
|
+
```python
|
|
101
|
+
from shipbook.integrations.fastapi import ShipbookMiddleware
|
|
102
|
+
app.add_middleware(ShipbookMiddleware)
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
**Flask**
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
from shipbook.integrations.flask import init_app
|
|
109
|
+
init_app(app)
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
**Django** (sync and async views) — add to `MIDDLEWARE`, after `SessionMiddleware` and `AuthenticationMiddleware`:
|
|
113
|
+
|
|
114
|
+
```python
|
|
115
|
+
"shipbook.integrations.django.ShipbookMiddleware"
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
Customize each request with extractors (FastAPI/Flask keyword arguments; on Django, subclass and override `get_user`, `get_session_id`, `get_trace_id`, `get_attributes`):
|
|
119
|
+
|
|
120
|
+
```python
|
|
121
|
+
app.add_middleware(
|
|
122
|
+
ShipbookMiddleware,
|
|
123
|
+
user_extractor=lambda request: shipbook.User(user_id=request.headers.get("x-user-id")),
|
|
124
|
+
session_extractor=lambda request: request.cookies.get("login"), # group requests into one session
|
|
125
|
+
attributes_extractor=lambda request: {"tenant": request.headers.get("x-tenant")},
|
|
126
|
+
)
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
Or call `shipbook.register_user(...)` anywhere inside the request. By default every request is its own session; on Django a request joins its Django session when it has one.
|
|
130
|
+
|
|
131
|
+
**Linked apps.** When a client app with a Shipbook SDK calls your API, it sends an `x-shipbook-session` header. The request joins that client session, so the Logbook shows the whole flow — the app's logs and your server's — in one view.
|
|
132
|
+
|
|
133
|
+
**JSON-RPC and MCP over HTTP.** A JSON-RPC call is labeled with what it asked for, e.g. `tools/call get-logs`, so calls to one endpoint stay apart.
|
|
134
|
+
|
|
135
|
+
## MCP servers
|
|
136
|
+
|
|
137
|
+
For an MCP server built with the `mcp` SDK (2.x), add the middleware and every call becomes a request, labeled with its operation, over any transport (stdio included):
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
from mcp.server.mcpserver import MCPServer
|
|
141
|
+
from shipbook.integrations.mcp import ShipbookMiddleware
|
|
142
|
+
|
|
143
|
+
server = MCPServer("my-server", middleware=[ShipbookMiddleware()])
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
A tool that fails, raises or returns `isError`, is recorded as a failed request with its JSON-RPC error code.
|
|
147
|
+
|
|
148
|
+
## Background jobs
|
|
149
|
+
|
|
150
|
+
Wrap background work so its logs are grouped as a named session:
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
with shipbook.run_in_context(job_name="nightly-billing"):
|
|
154
|
+
logging.getLogger(__name__).info("charging customers")
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
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.
|
|
158
|
+
|
|
159
|
+
Anything logged outside a request or job falls back to a per-process background session — nothing is lost.
|
|
160
|
+
|
|
161
|
+
To read other units of work (a queue message, a scheduled task) the way requests are read, run each one as a request:
|
|
162
|
+
|
|
163
|
+
```python
|
|
164
|
+
with shipbook.run_in_request(shipbook.RequestKind.Rpc, "process order"):
|
|
165
|
+
process(order)
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
It's recorded with its duration and whether it finished or raised.
|
|
169
|
+
|
|
170
|
+
## Threads and executors
|
|
171
|
+
|
|
172
|
+
`contextvars` follow `await` and `asyncio` tasks automatically, but a manually
|
|
173
|
+
spawned thread or executor starts with a fresh context and would lose the
|
|
174
|
+
request's user/IP. Wrap the callable to carry the current context along:
|
|
175
|
+
|
|
176
|
+
```python
|
|
177
|
+
pool.submit(shipbook.preserve_context(do_work))
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## Crashes and shutdown
|
|
181
|
+
|
|
182
|
+
An uncaught exception is captured and uploaded before Python prints it and exits, so the crash that killed your process reaches Shipbook. Exceptions in other threads are captured too, and exceptions in `asyncio` tasks arrive through `logging`.
|
|
183
|
+
|
|
184
|
+
Crashes are grouped in Loglytics by the innermost stack frame of your own code; frames from installed packages and the standard library are skipped. If your app is itself installed as a package (`pip install .`), name it so its frames count as yours:
|
|
185
|
+
|
|
186
|
+
```python
|
|
187
|
+
shipbook.start(app_id="...", app_key="...", in_app_include=["myapp"])
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Queued logs are uploaded before the process ends: at interpreter exit and on `SIGTERM`/`SIGINT` (a container stop or a deploy), waiting at most 2 seconds. Your own signal handlers still run afterwards, and a default `SIGTERM` still terminates the process. To flush or stop explicitly:
|
|
191
|
+
|
|
192
|
+
```python
|
|
193
|
+
shipbook.flush() # upload now and wait; flush(timeout=2) to bound it
|
|
194
|
+
shipbook.shutdown()
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Forked workers (for example gunicorn with `--preload`) each upload their own logs.
|
|
198
|
+
|
|
199
|
+
## Troubleshooting
|
|
200
|
+
|
|
201
|
+
`shipbook.enable_inner_log(True)` prints the SDK's own diagnostics (login, uploads) to stderr.
|
|
202
|
+
|
|
203
|
+
## License
|
|
204
|
+
|
|
205
|
+
MIT
|
shipbook-0.2.0/README.md
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# Shipbook Python SDK
|
|
2
|
+
|
|
3
|
+
Ship your Python server logs to [Shipbook](https://shipbook.io) — with **zero new logging API to learn.** The SDK plugs into Python's standard `logging` module, so the code you already write just works:
|
|
4
|
+
|
|
5
|
+
```python
|
|
6
|
+
import logging
|
|
7
|
+
import shipbook
|
|
8
|
+
|
|
9
|
+
shipbook.start(app_id="YOUR_APP_ID", app_key="YOUR_APP_KEY")
|
|
10
|
+
|
|
11
|
+
log = logging.getLogger(__name__)
|
|
12
|
+
log.info("user signed in")
|
|
13
|
+
log.error("payment failed", exc_info=True)
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
Every `logging` call in your process is captured, batched, and uploaded to Shipbook in the background. Source location (file, function, line), the logger name (as the tag), thread info, and exception tracebacks all come across automatically — because Python's `logging` already records them.
|
|
17
|
+
|
|
18
|
+
## Install
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
pip install shipbook
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
Zero required dependencies. Optional framework helpers:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
pip install "shipbook[fastapi]" # or [flask], [django], [mcp]
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## How it works
|
|
31
|
+
|
|
32
|
+
`shipbook.start()` attaches a single `ShipbookHandler` to the root logger and returns at once; it logs in to Shipbook on a background thread, so an unreachable API never delays your app's startup. There is **no** separate Shipbook logging API — `ShipbookHandler` *is* the SDK. Logs are kept in memory and uploaded in batches by a background thread; nothing on your request path blocks on the network, and nothing is written to disk.
|
|
33
|
+
|
|
34
|
+
What ships is controlled by two independent gates:
|
|
35
|
+
|
|
36
|
+
1. **Standard `logging` levels** — records are only created if the logger's level allows them. To ship `DEBUG`/`INFO`, make sure the level permits it (or pass `capture_level=logging.DEBUG` to `start()`).
|
|
37
|
+
2. **Server-side config** — Shipbook's dashboard controls which tags/severities are actually uploaded, and can be changed without a redeploy. Until the first config arrives, logs are held and then filtered by it, so a filter set in the dashboard also applies to startup logs.
|
|
38
|
+
|
|
39
|
+
With the **Accumulate** config, logs below the warning level are held per request and uploaded only when that request logs a warning or error — as their context. Healthy requests cost nothing.
|
|
40
|
+
|
|
41
|
+
To point the SDK at another Shipbook API (for example a staging environment), call `shipbook.set_connection_url(url)` before `start()`.
|
|
42
|
+
|
|
43
|
+
## Attaching to a specific logger
|
|
44
|
+
|
|
45
|
+
By default the handler is attached to the root logger. To scope it yourself:
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
shipbook.start(app_id="...", app_key="...", attach_to_root=False)
|
|
49
|
+
logging.getLogger("myapp").addHandler(shipbook.get_handler())
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Web frameworks — read your server request by request
|
|
53
|
+
|
|
54
|
+
A `LogRecord` doesn't know which request it belongs to. The framework integrations bind each request to a Shipbook **session**, so logs carry the user, client IP, and trace id. Each request is also recorded with its method, route (`/items/{item_id}`), status and duration, and its logs are grouped under it in the Logbook. A failed request (5xx) is always recorded, even if it logged nothing.
|
|
55
|
+
|
|
56
|
+
**FastAPI / Starlette**
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
from shipbook.integrations.fastapi import ShipbookMiddleware
|
|
60
|
+
app.add_middleware(ShipbookMiddleware)
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
**Flask**
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
from shipbook.integrations.flask import init_app
|
|
67
|
+
init_app(app)
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
**Django** (sync and async views) — add to `MIDDLEWARE`, after `SessionMiddleware` and `AuthenticationMiddleware`:
|
|
71
|
+
|
|
72
|
+
```python
|
|
73
|
+
"shipbook.integrations.django.ShipbookMiddleware"
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Customize each request with extractors (FastAPI/Flask keyword arguments; on Django, subclass and override `get_user`, `get_session_id`, `get_trace_id`, `get_attributes`):
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
app.add_middleware(
|
|
80
|
+
ShipbookMiddleware,
|
|
81
|
+
user_extractor=lambda request: shipbook.User(user_id=request.headers.get("x-user-id")),
|
|
82
|
+
session_extractor=lambda request: request.cookies.get("login"), # group requests into one session
|
|
83
|
+
attributes_extractor=lambda request: {"tenant": request.headers.get("x-tenant")},
|
|
84
|
+
)
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Or call `shipbook.register_user(...)` anywhere inside the request. By default every request is its own session; on Django a request joins its Django session when it has one.
|
|
88
|
+
|
|
89
|
+
**Linked apps.** When a client app with a Shipbook SDK calls your API, it sends an `x-shipbook-session` header. The request joins that client session, so the Logbook shows the whole flow — the app's logs and your server's — in one view.
|
|
90
|
+
|
|
91
|
+
**JSON-RPC and MCP over HTTP.** A JSON-RPC call is labeled with what it asked for, e.g. `tools/call get-logs`, so calls to one endpoint stay apart.
|
|
92
|
+
|
|
93
|
+
## MCP servers
|
|
94
|
+
|
|
95
|
+
For an MCP server built with the `mcp` SDK (2.x), add the middleware and every call becomes a request, labeled with its operation, over any transport (stdio included):
|
|
96
|
+
|
|
97
|
+
```python
|
|
98
|
+
from mcp.server.mcpserver import MCPServer
|
|
99
|
+
from shipbook.integrations.mcp import ShipbookMiddleware
|
|
100
|
+
|
|
101
|
+
server = MCPServer("my-server", middleware=[ShipbookMiddleware()])
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
A tool that fails, raises or returns `isError`, is recorded as a failed request with its JSON-RPC error code.
|
|
105
|
+
|
|
106
|
+
## Background jobs
|
|
107
|
+
|
|
108
|
+
Wrap background work so its logs are grouped as a named session:
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
with shipbook.run_in_context(job_name="nightly-billing"):
|
|
112
|
+
logging.getLogger(__name__).info("charging customers")
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
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.
|
|
116
|
+
|
|
117
|
+
Anything logged outside a request or job falls back to a per-process background session — nothing is lost.
|
|
118
|
+
|
|
119
|
+
To read other units of work (a queue message, a scheduled task) the way requests are read, run each one as a request:
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
with shipbook.run_in_request(shipbook.RequestKind.Rpc, "process order"):
|
|
123
|
+
process(order)
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
It's recorded with its duration and whether it finished or raised.
|
|
127
|
+
|
|
128
|
+
## Threads and executors
|
|
129
|
+
|
|
130
|
+
`contextvars` follow `await` and `asyncio` tasks automatically, but a manually
|
|
131
|
+
spawned thread or executor starts with a fresh context and would lose the
|
|
132
|
+
request's user/IP. Wrap the callable to carry the current context along:
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
pool.submit(shipbook.preserve_context(do_work))
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## Crashes and shutdown
|
|
139
|
+
|
|
140
|
+
An uncaught exception is captured and uploaded before Python prints it and exits, so the crash that killed your process reaches Shipbook. Exceptions in other threads are captured too, and exceptions in `asyncio` tasks arrive through `logging`.
|
|
141
|
+
|
|
142
|
+
Crashes are grouped in Loglytics by the innermost stack frame of your own code; frames from installed packages and the standard library are skipped. If your app is itself installed as a package (`pip install .`), name it so its frames count as yours:
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
shipbook.start(app_id="...", app_key="...", in_app_include=["myapp"])
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
Queued logs are uploaded before the process ends: at interpreter exit and on `SIGTERM`/`SIGINT` (a container stop or a deploy), waiting at most 2 seconds. Your own signal handlers still run afterwards, and a default `SIGTERM` still terminates the process. To flush or stop explicitly:
|
|
149
|
+
|
|
150
|
+
```python
|
|
151
|
+
shipbook.flush() # upload now and wait; flush(timeout=2) to bound it
|
|
152
|
+
shipbook.shutdown()
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Forked workers (for example gunicorn with `--preload`) each upload their own logs.
|
|
156
|
+
|
|
157
|
+
## Troubleshooting
|
|
158
|
+
|
|
159
|
+
`shipbook.enable_inner_log(True)` prints the SDK's own diagnostics (login, uploads) to stderr.
|
|
160
|
+
|
|
161
|
+
## License
|
|
162
|
+
|
|
163
|
+
MIT
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""Group a background job's logs into a named Shipbook session."""
|
|
2
|
+
|
|
3
|
+
import logging
|
|
4
|
+
import os
|
|
5
|
+
|
|
6
|
+
import shipbook
|
|
7
|
+
|
|
8
|
+
shipbook.start(
|
|
9
|
+
app_id=os.environ["SHIPBOOK_APP_ID"],
|
|
10
|
+
app_key=os.environ["SHIPBOOK_APP_KEY"],
|
|
11
|
+
capture_level=logging.INFO,
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
log = logging.getLogger("example.job")
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def run_billing():
|
|
18
|
+
with shipbook.run_in_context(job_name="nightly-billing", attributes={"tenant": "acme"}):
|
|
19
|
+
log.info("starting billing run")
|
|
20
|
+
log.info("charged %d customers", 128)
|
|
21
|
+
log.warning("1 payment method expired")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
if __name__ == "__main__":
|
|
25
|
+
run_billing()
|
|
26
|
+
shipbook.flush()
|
|
27
|
+
shipbook.shutdown()
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""Django wiring for Shipbook.
|
|
2
|
+
|
|
3
|
+
In your Django project's ``settings.py``:
|
|
4
|
+
|
|
5
|
+
import logging
|
|
6
|
+
import os
|
|
7
|
+
import shipbook
|
|
8
|
+
|
|
9
|
+
shipbook.start(
|
|
10
|
+
app_id=os.environ["SHIPBOOK_APP_ID"],
|
|
11
|
+
app_key=os.environ["SHIPBOOK_APP_KEY"],
|
|
12
|
+
capture_level=logging.INFO,
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
MIDDLEWARE = [
|
|
16
|
+
# ... your other middleware ...
|
|
17
|
+
# After these two, so the request's session and user are available to it.
|
|
18
|
+
"django.contrib.sessions.middleware.SessionMiddleware",
|
|
19
|
+
"django.contrib.auth.middleware.AuthenticationMiddleware",
|
|
20
|
+
"shipbook.integrations.django.ShipbookMiddleware",
|
|
21
|
+
]
|
|
22
|
+
|
|
23
|
+
To attach the authenticated user, subclass the middleware:
|
|
24
|
+
|
|
25
|
+
from shipbook import User
|
|
26
|
+
from shipbook.integrations.django import ShipbookMiddleware as _Base
|
|
27
|
+
|
|
28
|
+
class ShipbookMiddleware(_Base):
|
|
29
|
+
def get_user(self, request):
|
|
30
|
+
if request.user.is_authenticated:
|
|
31
|
+
return User(user_id=str(request.user.pk), email=request.user.email)
|
|
32
|
+
return None
|
|
33
|
+
|
|
34
|
+
and reference your subclass path in ``MIDDLEWARE`` instead.
|
|
35
|
+
"""
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""FastAPI app whose per-request logs are grouped into Shipbook sessions.
|
|
2
|
+
|
|
3
|
+
Run: SHIPBOOK_APP_ID=... SHIPBOOK_APP_KEY=... uvicorn examples.fastapi_app:app
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
import logging
|
|
7
|
+
import os
|
|
8
|
+
from typing import Optional
|
|
9
|
+
|
|
10
|
+
from fastapi import FastAPI
|
|
11
|
+
|
|
12
|
+
import shipbook
|
|
13
|
+
from shipbook import User
|
|
14
|
+
from shipbook.integrations.fastapi import ShipbookMiddleware
|
|
15
|
+
|
|
16
|
+
shipbook.start(
|
|
17
|
+
app_id=os.environ["SHIPBOOK_APP_ID"],
|
|
18
|
+
app_key=os.environ["SHIPBOOK_APP_KEY"],
|
|
19
|
+
capture_level=logging.INFO,
|
|
20
|
+
)
|
|
21
|
+
|
|
22
|
+
app = FastAPI()
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def extract_user(request) -> Optional[User]:
|
|
26
|
+
user_id = request.headers.get("x-user-id")
|
|
27
|
+
return User(user_id=user_id) if user_id else None
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
app.add_middleware(ShipbookMiddleware, user_extractor=extract_user)
|
|
31
|
+
|
|
32
|
+
log = logging.getLogger("example.api")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@app.get("/hello")
|
|
36
|
+
def hello():
|
|
37
|
+
log.info("handling /hello")
|
|
38
|
+
return {"ok": True}
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@app.get("/boom")
|
|
42
|
+
def boom():
|
|
43
|
+
log.info("about to fail")
|
|
44
|
+
raise RuntimeError("intentional error")
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
"""Flask app whose per-request logs are grouped into Shipbook sessions.
|
|
2
|
+
|
|
3
|
+
Run: SHIPBOOK_APP_ID=... SHIPBOOK_APP_KEY=... flask --app examples.flask_app run
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
import logging
|
|
7
|
+
import os
|
|
8
|
+
|
|
9
|
+
from flask import Flask
|
|
10
|
+
|
|
11
|
+
import shipbook
|
|
12
|
+
from shipbook.integrations.flask import init_app
|
|
13
|
+
|
|
14
|
+
shipbook.start(
|
|
15
|
+
app_id=os.environ["SHIPBOOK_APP_ID"],
|
|
16
|
+
app_key=os.environ["SHIPBOOK_APP_KEY"],
|
|
17
|
+
capture_level=logging.INFO,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
app = Flask(__name__)
|
|
21
|
+
init_app(app)
|
|
22
|
+
|
|
23
|
+
log = logging.getLogger("example.flask")
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
@app.route("/hello")
|
|
27
|
+
def hello():
|
|
28
|
+
log.info("handling /hello")
|
|
29
|
+
return {"ok": True}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
"""An MCP server whose tool calls are read in Shipbook request by request.
|
|
2
|
+
|
|
3
|
+
Run: SHIPBOOK_APP_ID=... SHIPBOOK_APP_KEY=... python examples/mcp_server.py
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
import logging
|
|
7
|
+
import os
|
|
8
|
+
|
|
9
|
+
from mcp.server.mcpserver import MCPServer
|
|
10
|
+
|
|
11
|
+
import shipbook
|
|
12
|
+
from shipbook.integrations.mcp import ShipbookMiddleware
|
|
13
|
+
|
|
14
|
+
shipbook.start(
|
|
15
|
+
app_id=os.environ["SHIPBOOK_APP_ID"],
|
|
16
|
+
app_key=os.environ["SHIPBOOK_APP_KEY"],
|
|
17
|
+
capture_level=logging.INFO,
|
|
18
|
+
)
|
|
19
|
+
|
|
20
|
+
server = MCPServer("orders", middleware=[ShipbookMiddleware()])
|
|
21
|
+
log = logging.getLogger("example.mcp")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
@server.tool()
|
|
25
|
+
def find_order(order_id: str) -> str:
|
|
26
|
+
log.info("looking up order %s", order_id)
|
|
27
|
+
return f"order {order_id}: shipped"
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
if __name__ == "__main__":
|
|
31
|
+
server.run() # stdio
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
"""Minimal usage: attach Shipbook to stdlib logging and log.
|
|
2
|
+
|
|
3
|
+
Run: SHIPBOOK_APP_ID=... SHIPBOOK_APP_KEY=... python examples/plain_script.py
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
import logging
|
|
7
|
+
import os
|
|
8
|
+
|
|
9
|
+
import shipbook
|
|
10
|
+
|
|
11
|
+
shipbook.start(
|
|
12
|
+
app_id=os.environ["SHIPBOOK_APP_ID"],
|
|
13
|
+
app_key=os.environ["SHIPBOOK_APP_KEY"],
|
|
14
|
+
capture_level=logging.DEBUG, # ensure DEBUG/INFO records are created
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
log = logging.getLogger("example.plain")
|
|
18
|
+
|
|
19
|
+
log.info("service started")
|
|
20
|
+
log.debug("loaded config: %s", {"workers": 4})
|
|
21
|
+
log.warning("cache miss for key %s", "user:42")
|
|
22
|
+
|
|
23
|
+
try:
|
|
24
|
+
ratio = 100 / 0
|
|
25
|
+
except ZeroDivisionError:
|
|
26
|
+
log.exception("failed to compute ratio")
|
|
27
|
+
|
|
28
|
+
# Flush before the short script exits (the exit hook also does this).
|
|
29
|
+
shipbook.flush()
|
|
30
|
+
shipbook.shutdown()
|