trapy
Python logging facade that emits real Rust tracing events with structured kwargs.
In a process that mixes Python and Rust (PyO3 cdylibs), trapy gives both sides one tracing pipeline: trapy.info("msg", cat="planning", x=1) produces an event indistinguishable from tracing::info!(cat = "planning", x = 1, "msg") to any subscriber — including category routing, level filtering, and per-field structured access. Caller file/line/module are pulled from the Python frame and woven into the event metadata (target = "py:<module>"), so subscribers report Python locations and can route by Python module.
Events
import trapy
trapy.info("seam planned", cat="planning", part="bracket", qs=[0.1, 0.2])
trapy.warn("ik fallback", attempts=3)
trapy.error("collision", link="wrist", depth_mm=1.7)
Each kwarg becomes a real tracing field. Primitives (bool/int/float/str/None) flow through natively; lists, tuples, dicts, dataclasses, and anything implementing __array__ (numpy arrays, tensors) flow through valuable as structured values. Anything else is stringified rather than raising.
Spans
with trapy.info_span("plan_part", part="bracket"):
trapy.debug("inside the span")
@trapy.instrument("plan_path", level="debug", category="planning")
def plan(path): ...
timer = trapy.LocalTimer()
timer.epoch("load") # closes the previous epoch span, opens the next
timer.epoch("solve")
timer.close_last("write")
Every span emits cat="timing" events on enter and exit (with elapsed_ms), so <dir>/timing.log doubles as a wall-clock record. For aggregate statistics install the timing layer (below) and call trapy.dump_timing().
Subscriber backend
The backend is compiled behind the subscribers cargo feature (the wheel enables it). Configure any number of layers, then install once:
trapy.add_file_router("/tmp/trace") # tracing-catty: events route to <dir>/<cat>.log
trapy.add_env_filter("info,planning=trace")
trapy.add_fmt_layer("stderr", format="compact", span_events=["close"])
trapy.add_json_file("/tmp/trace/events.json")
trapy.add_timing_layer() # tracing-timing HDR histograms
trapy.add_tracy_layer() # stream to a Tracy profiler
trapy.add_opentelemetry_layer(service_name="composer") # OTLP span export
trapy.init_subscriber() # one-shot; add_* calls fail afterwards
Or the one-call convenience for the file-router-only setup: trapy.init_tracing(dir).
Available layers:
| call | layer |
|---|---|
add_file_router(dir, ...) |
tracing-catty per-category file router. Defaults: cat="progress" mirrors to stdout, cat="console" is stdout-only, ERROR events fan out to errors.log; override via console_cats= / console_only_cats= / split_errors= / split_warnings= |
add_fmt_layer(...) |
tracing_subscriber::fmt with the full builder surface: format= full/compact/pretty/json, stdout/stderr or file=, span_events=, thread/file/line knobs |
add_env_filter(directive) / add_env_filter_from_env(var) |
EnvFilter with RUST_LOG syntax; rejected events never reach downstream layers |
add_json_file(path) |
JSON-per-line file, for Loki/Promtail-style shipping |
add_timing_layer(...) + dump_timing() |
tracing-timing inter-event HDR histograms keyed by (span, event) |
add_tracy_layer() |
tracing-tracy; starts the Tracy client eagerly so the profiler can attach before the first span |
add_opentelemetry_layer(endpoint, service_name) |
tracing-opentelemetry OTLP span export over HTTP + binary protobuf (no embedded tokio runtime) |
Flushing: flush_tracing() (async), flush_tracing_sync() (blocks until the writer acks — call before process exit), flush_opentelemetry() / shutdown_opentelemetry() for the OTLP batch exporter.
Multi-cdylib forwarding
Every PyO3 cdylib statically links its own copy of tracing-core, so a subscriber installed in trapy._trapy.so is invisible to events emitted from another cdylib. trapy bridges this with a C-ABI capsule (trapy._capsule): the host cdylib links trapy as an rlib without default features and installs a forwarding subscriber at module init —
trapy = { version = "0.1.0", default-features = false }
#[pymodule]
fn _my_ext(m: &Bound<'_, PyModule>) -> PyResult<()> {
let _ = trapy::import_trapy_subscriber(m.py()); // best-effort, never raises
...
}
Events from the host's tracing::*! macros then flow through trapy's full layer chain. The handshake is fail-safe: if trapy isn't importable, the host still loads and its events are dropped. set_log_level() / get_log_level() gate the FFI boundary coarsely so foreign cdylibs can drop events before paying for formatting; in-process filtering is EnvFilter's job.
Building
pip install trapy # or: maturin develop --release
Cargo features:
| feature | meaning |
|---|---|
subscribers |
the whole backend: layer builders, the file router, the capsule owner side. The wheel enables it via pyproject.toml |
extension-module |
pyo3/extension-module, for standalone wheel builds only |
Crates that consume trapy as an rlib (capsule forwarding) must enable neither — they stay consumer-only and skip compiling every subscriber crate.
The valuable field support rides tracing's unstable API: builds need --cfg tracing_unstable (the workspace .cargo/config.toml sets it).
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file trapy-0.1.0.tar.gz.
File metadata
- Download URL: trapy-0.1.0.tar.gz
- Upload date:
- Size: 57.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
504ff94dfe5625c4862164681419414c2fef2b6cdc354e2f10faa69d2129b6de
|
|
| MD5 |
8c440f7bc7e1b532a2a7e445b13f9f18
|
|
| BLAKE2b-256 |
6fa192e11958402c090c48e72a9a5778e58e74f804196c75da3db55035ea0e98
|
File details
Details for the file trapy-0.1.0-cp315-abi3.abi3t-win_arm64.whl.
File metadata
- Download URL: trapy-0.1.0-cp315-abi3.abi3t-win_arm64.whl
- Upload date:
- Size: 1.7 MB
- Tags: CPython 3.15, CPython 3.15+, Windows ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4f7321635082def2a314f3547b133634c92406be742dfbe181adfeadc41b3df0
|
|
| MD5 |
7d13815672924bbc170b9143f654b5be
|
|
| BLAKE2b-256 |
55ea81d9509bc9520a6d1accb15d92c00ce152f720a4f4f80022e2bec57ab238
|
File details
Details for the file trapy-0.1.0-cp315-abi3.abi3t-win_amd64.whl.
File metadata
- Download URL: trapy-0.1.0-cp315-abi3.abi3t-win_amd64.whl
- Upload date:
- Size: 1.7 MB
- Tags: CPython 3.15, CPython 3.15+, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
89cbbb63776ac8506134ec91beb8eeb22a50c2442e78703eb80ed038df72dd4e
|
|
| MD5 |
02c01e0bc82808ab80ade3d88bf2fa92
|
|
| BLAKE2b-256 |
2fff4e5fe152e4c4208c2cd642987d1d3b6dedd3849e76b80a6049830078e90b
|
File details
Details for the file trapy-0.1.0-cp315-abi3.abi3t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: trapy-0.1.0-cp315-abi3.abi3t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 2.2 MB
- Tags: CPython 3.15, CPython 3.15+, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
8103a25a05e1b30cd97eeec02794d28db56db1cecda61d4583abda28a415b90f
|
|
| MD5 |
a9acc1419ed23fc67627bffb4c47bfc7
|
|
| BLAKE2b-256 |
d2ee71cf380ff4083db4b36d7a97a78b024613b3416c329561cb1f86e7084cc1
|
File details
Details for the file trapy-0.1.0-cp315-abi3.abi3t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.
File metadata
- Download URL: trapy-0.1.0-cp315-abi3.abi3t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Upload date:
- Size: 2.2 MB
- Tags: CPython 3.15, CPython 3.15+, manylinux: glibc 2.17+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
cb387eef21eafc12f8bc37aac39b72fa1007cf2611352e7b173a74562f741a03
|
|
| MD5 |
98ae891ab2f84342c50536a7017f4490
|
|
| BLAKE2b-256 |
b539a6c86436bb8c48fb6038c49fd56324c581f2157dfb0b8ba4700f4e217f01
|
File details
Details for the file trapy-0.1.0-cp315-abi3.abi3t-macosx_11_0_arm64.whl.
File metadata
- Download URL: trapy-0.1.0-cp315-abi3.abi3t-macosx_11_0_arm64.whl
- Upload date:
- Size: 1.9 MB
- Tags: CPython 3.15, CPython 3.15+, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
4735dd8b3178a67508117618aa6b54aa4e73bf94d8f7fd42f5a55085e33f5f04
|
|
| MD5 |
f46264830c1d53bba59ac6d85de16e4f
|
|
| BLAKE2b-256 |
b0f3ea0423e027c2d0f9de6f5d8ad6d1f2fb0d473ccfe8ab9fd3e9de93e34c96
|
File details
Details for the file trapy-0.1.0-cp314-cp314t-win_arm64.whl.
File metadata
- Download URL: trapy-0.1.0-cp314-cp314t-win_arm64.whl
- Upload date:
- Size: 1.7 MB
- Tags: CPython 3.14t, Windows ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
88b4e5c625177bfcafcdd71c486077ed5d40ebd92fa34f678be39bb899601bb9
|
|
| MD5 |
7195ab9a0dccbf41b04c91d4a50a92a3
|
|
| BLAKE2b-256 |
5fb6cdf2d0fdbf39124e98da23498a9c783b5aac3a8f4c73f6eeb17540f10c6a
|
File details
Details for the file trapy-0.1.0-cp314-cp314t-win_amd64.whl.
File metadata
- Download URL: trapy-0.1.0-cp314-cp314t-win_amd64.whl
- Upload date:
- Size: 1.7 MB
- Tags: CPython 3.14t, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
335f9ffd5e84a989914b694b86c15ef33d30d715a6ab25b9bece57f4936e3b58
|
|
| MD5 |
95fd40e63a9980d402793b13292411e9
|
|
| BLAKE2b-256 |
c9e665fc3e65ca34da0c7df6441b1cfec74383d64bda09fdfe4b12c2abae917d
|
File details
Details for the file trapy-0.1.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: trapy-0.1.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 2.2 MB
- Tags: CPython 3.14t, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c21a4eeb24c4d74580f8e427d4ce899111f82f0790255e122fd03b1ec2a2b9ce
|
|
| MD5 |
76bd25a3e450e325247a2db6d0b2a98c
|
|
| BLAKE2b-256 |
f8eed03280543834a9e1be06b53e5df57796f254fdc0c2fd3fa5e1c04243e7ed
|
File details
Details for the file trapy-0.1.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.
File metadata
- Download URL: trapy-0.1.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Upload date:
- Size: 2.2 MB
- Tags: CPython 3.14t, manylinux: glibc 2.17+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
47406d2de70b19da66179413190fdd7683b3099518b380a285468c3b4692506b
|
|
| MD5 |
cee97a721b4d8a1c615ea5c0f5944bc9
|
|
| BLAKE2b-256 |
673ca50f92b4db36da561833f306fe35c8415fb7831409132761b75eb9c49a9e
|
File details
Details for the file trapy-0.1.0-cp314-cp314t-macosx_11_0_arm64.whl.
File metadata
- Download URL: trapy-0.1.0-cp314-cp314t-macosx_11_0_arm64.whl
- Upload date:
- Size: 1.9 MB
- Tags: CPython 3.14t, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
17ab8b4bcce6fd899ad88aadbe2f6dce35de9a0ce35ae0e159002c203411fbb8
|
|
| MD5 |
4e477c85ef0ff1beb9d24ce042a61642
|
|
| BLAKE2b-256 |
12e7f231edffa91926df68c022bcd47fb0d74271a0b8cae006daab09773d47aa
|
File details
Details for the file trapy-0.1.0-cp310-abi3-win_arm64.whl.
File metadata
- Download URL: trapy-0.1.0-cp310-abi3-win_arm64.whl
- Upload date:
- Size: 1.7 MB
- Tags: CPython 3.10+, Windows ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
da456ae1d2435da708770ac863cde265641fb158a2c029523e933ffe94ee06c7
|
|
| MD5 |
8004a028e6be2098c927a7b8a9cffb97
|
|
| BLAKE2b-256 |
a099910881a68ad7ad6e06331ad5633d8ee90607ff8ec0279fb2ab1bd3282237
|
File details
Details for the file trapy-0.1.0-cp310-abi3-win_amd64.whl.
File metadata
- Download URL: trapy-0.1.0-cp310-abi3-win_amd64.whl
- Upload date:
- Size: 1.7 MB
- Tags: CPython 3.10+, Windows x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
417f627ce020b39e434a1051fe1ed2303df6942c4047cdd3a1701e772336da3f
|
|
| MD5 |
ed66e2ce939507618747e768210bc215
|
|
| BLAKE2b-256 |
b764772d5802fc16eb39fff51f2e671d8fbe1eca426cc024fd224c4c431c082e
|
File details
Details for the file trapy-0.1.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.
File metadata
- Download URL: trapy-0.1.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Upload date:
- Size: 2.2 MB
- Tags: CPython 3.10+, manylinux: glibc 2.17+ x86-64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3bbc9a3ff519d9ad6b0ed3968791da93991422d2533b755c6ecea8de06d0602d
|
|
| MD5 |
999491a8257a3c3fe8ed34553d94eb19
|
|
| BLAKE2b-256 |
ed4028458cc741b5d303bafd6ed7282be2d91ff21e0d25736772901bea0e2fbe
|
File details
Details for the file trapy-0.1.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.
File metadata
- Download URL: trapy-0.1.0-cp310-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Upload date:
- Size: 2.2 MB
- Tags: CPython 3.10+, manylinux: glibc 2.17+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
3d4fb8113ea0a8be55575d6128740bc3f05ccb1ec8354a5854dc9ef267cbfe09
|
|
| MD5 |
3001ea1faaeb90381d157c160832fe1e
|
|
| BLAKE2b-256 |
0f5ce7e0f8908c596af2955431327d5f638d1de5f7be306fa7d10b12405f27c5
|
File details
Details for the file trapy-0.1.0-cp310-abi3-macosx_11_0_arm64.whl.
File metadata
- Download URL: trapy-0.1.0-cp310-abi3-macosx_11_0_arm64.whl
- Upload date:
- Size: 1.9 MB
- Tags: CPython 3.10+, macOS 11.0+ ARM64
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.12.7 {"installer":{"name":"uv","version":"0.12.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
21a8c658136c5bb6adf113bc38384104217ffbfca09fe94d2e2a4edbefc258bb
|
|
| MD5 |
94565a0c050c8986b9a9ee6dcf805213
|
|
| BLAKE2b-256 |
42e908d3986266b585c55fecdb84089f64d2ab4c1ce2127d78993324cfa92079
|
