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.
Files changed (60) hide show
  1. shipbook-0.2.0/.gitignore +14 -0
  2. shipbook-0.2.0/CHANGELOG.md +23 -0
  3. shipbook-0.2.0/LICENSE +21 -0
  4. shipbook-0.2.0/PKG-INFO +205 -0
  5. shipbook-0.2.0/README.md +163 -0
  6. shipbook-0.2.0/examples/background_job.py +27 -0
  7. shipbook-0.2.0/examples/django_settings_snippet.py +35 -0
  8. shipbook-0.2.0/examples/fastapi_app.py +44 -0
  9. shipbook-0.2.0/examples/flask_app.py +29 -0
  10. shipbook-0.2.0/examples/mcp_server.py +31 -0
  11. shipbook-0.2.0/examples/plain_script.py +30 -0
  12. shipbook-0.2.0/pyproject.toml +54 -0
  13. shipbook-0.2.0/src/shipbook/__init__.py +50 -0
  14. shipbook-0.2.0/src/shipbook/_inner_log.py +23 -0
  15. shipbook-0.2.0/src/shipbook/_state.py +14 -0
  16. shipbook-0.2.0/src/shipbook/_util.py +23 -0
  17. shipbook-0.2.0/src/shipbook/cloud_uploader.py +272 -0
  18. shipbook-0.2.0/src/shipbook/config.py +108 -0
  19. shipbook-0.2.0/src/shipbook/connection_client.py +84 -0
  20. shipbook-0.2.0/src/shipbook/context.py +73 -0
  21. shipbook-0.2.0/src/shipbook/generated/__init__.py +0 -0
  22. shipbook-0.2.0/src/shipbook/generated/version.py +2 -0
  23. shipbook-0.2.0/src/shipbook/handler.py +50 -0
  24. shipbook-0.2.0/src/shipbook/hooks/__init__.py +0 -0
  25. shipbook-0.2.0/src/shipbook/hooks/exception_handler.py +48 -0
  26. shipbook-0.2.0/src/shipbook/hooks/exit_handler.py +52 -0
  27. shipbook-0.2.0/src/shipbook/integrations/__init__.py +0 -0
  28. shipbook-0.2.0/src/shipbook/integrations/_common.py +91 -0
  29. shipbook-0.2.0/src/shipbook/integrations/django.py +97 -0
  30. shipbook-0.2.0/src/shipbook/integrations/fastapi.py +105 -0
  31. shipbook-0.2.0/src/shipbook/integrations/flask.py +68 -0
  32. shipbook-0.2.0/src/shipbook/integrations/mcp.py +59 -0
  33. shipbook-0.2.0/src/shipbook/models/__init__.py +0 -0
  34. shipbook-0.2.0/src/shipbook/models/attributes.py +5 -0
  35. shipbook-0.2.0/src/shipbook/models/exception.py +46 -0
  36. shipbook-0.2.0/src/shipbook/models/frames.py +59 -0
  37. shipbook-0.2.0/src/shipbook/models/message.py +92 -0
  38. shipbook-0.2.0/src/shipbook/models/request_context.py +30 -0
  39. shipbook-0.2.0/src/shipbook/models/request_event.py +75 -0
  40. shipbook-0.2.0/src/shipbook/models/session.py +64 -0
  41. shipbook-0.2.0/src/shipbook/models/user.py +26 -0
  42. shipbook-0.2.0/src/shipbook/request_events.py +158 -0
  43. shipbook-0.2.0/src/shipbook/session_manager.py +108 -0
  44. shipbook-0.2.0/src/shipbook/severity.py +37 -0
  45. shipbook-0.2.0/src/shipbook/shipbook.py +252 -0
  46. shipbook-0.2.0/src/shipbook/storage.py +101 -0
  47. shipbook-0.2.0/tests/__init__.py +0 -0
  48. shipbook-0.2.0/tests/conftest.py +118 -0
  49. shipbook-0.2.0/tests/test_cloud_uploader.py +332 -0
  50. shipbook-0.2.0/tests/test_context.py +70 -0
  51. shipbook-0.2.0/tests/test_frames.py +61 -0
  52. shipbook-0.2.0/tests/test_handler_e2e.py +91 -0
  53. shipbook-0.2.0/tests/test_integrations.py +245 -0
  54. shipbook-0.2.0/tests/test_mcp.py +100 -0
  55. shipbook-0.2.0/tests/test_message.py +78 -0
  56. shipbook-0.2.0/tests/test_process_exit.py +166 -0
  57. shipbook-0.2.0/tests/test_request_events.py +119 -0
  58. shipbook-0.2.0/tests/test_session_manager.py +61 -0
  59. shipbook-0.2.0/tests/test_severity_config.py +91 -0
  60. shipbook-0.2.0/tests/test_storage.py +39 -0
@@ -0,0 +1,14 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ .eggs/
5
+ build/
6
+ dist/
7
+ .venv/
8
+ venv/
9
+ .mypy_cache/
10
+ .ruff_cache/
11
+ .pytest_cache/
12
+ .coverage
13
+ htmlcov/
14
+ *.log
@@ -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.
@@ -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
@@ -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()