jlogtail 0.1.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 (41) hide show
  1. jlogtail-0.1.0/.github/workflows/wheels.yml +90 -0
  2. jlogtail-0.1.0/.gitignore +7 -0
  3. jlogtail-0.1.0/AGENTS.md +31 -0
  4. jlogtail-0.1.0/Cargo.lock +334 -0
  5. jlogtail-0.1.0/Cargo.toml +23 -0
  6. jlogtail-0.1.0/LICENSE +21 -0
  7. jlogtail-0.1.0/PKG-INFO +94 -0
  8. jlogtail-0.1.0/README.ko.md +82 -0
  9. jlogtail-0.1.0/README.md +82 -0
  10. jlogtail-0.1.0/docs/bench/m5-bench.txt +13 -0
  11. jlogtail-0.1.0/docs/bench/m5-hyperfine.json +1088 -0
  12. jlogtail-0.1.0/docs/bench/m5-hyperfine.txt +15 -0
  13. jlogtail-0.1.0/docs/demo/agents.jsonl +3 -0
  14. jlogtail-0.1.0/docs/demo/codex-sample.jsonl +2 -0
  15. jlogtail-0.1.0/docs/demo/dark.gif +0 -0
  16. jlogtail-0.1.0/docs/demo/dark.tape +25 -0
  17. jlogtail-0.1.0/docs/demo/light.gif +0 -0
  18. jlogtail-0.1.0/docs/demo/light.tape +25 -0
  19. jlogtail-0.1.0/docs/demo/setup.sh +3 -0
  20. jlogtail-0.1.0/docs/diagrams/bench-results.en.dark.svg +1 -0
  21. jlogtail-0.1.0/docs/diagrams/bench-results.en.light.svg +1 -0
  22. jlogtail-0.1.0/docs/diagrams/bench-results.en.mmd +5 -0
  23. jlogtail-0.1.0/docs/diagrams/bench-results.ko.dark.svg +1 -0
  24. jlogtail-0.1.0/docs/diagrams/bench-results.ko.light.svg +1 -0
  25. jlogtail-0.1.0/docs/diagrams/bench-results.ko.mmd +5 -0
  26. jlogtail-0.1.0/docs/diagrams/tail-flow.en.dark.svg +1 -0
  27. jlogtail-0.1.0/docs/diagrams/tail-flow.en.light.svg +1 -0
  28. jlogtail-0.1.0/docs/diagrams/tail-flow.en.mmd +13 -0
  29. jlogtail-0.1.0/docs/diagrams/tail-flow.ko.dark.svg +1 -0
  30. jlogtail-0.1.0/docs/diagrams/tail-flow.ko.light.svg +1 -0
  31. jlogtail-0.1.0/docs/diagrams/tail-flow.ko.mmd +13 -0
  32. jlogtail-0.1.0/docs/orbit-receipts-incremental-follow.md +5 -0
  33. jlogtail-0.1.0/docs/social.json +34 -0
  34. jlogtail-0.1.0/docs/social.png +0 -0
  35. jlogtail-0.1.0/public.json +54 -0
  36. jlogtail-0.1.0/pyproject.toml +23 -0
  37. jlogtail-0.1.0/python/jlogtail/__init__.py +19 -0
  38. jlogtail-0.1.0/python/jlogtail/cli.py +11 -0
  39. jlogtail-0.1.0/src/cli.rs +228 -0
  40. jlogtail-0.1.0/src/lib.rs +495 -0
  41. jlogtail-0.1.0/src/main.rs +11 -0
@@ -0,0 +1,90 @@
1
+ name: wheels
2
+
3
+ on:
4
+ push:
5
+ tags: ["v*"]
6
+ workflow_dispatch:
7
+
8
+ jobs:
9
+ linux:
10
+ runs-on: ${{ matrix.platform.runner }}
11
+ strategy:
12
+ matrix:
13
+ platform:
14
+ - runner: ubuntu-22.04
15
+ target: x86_64
16
+ - runner: ubuntu-24.04-arm
17
+ target: aarch64
18
+ steps:
19
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
20
+ - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
21
+ with:
22
+ python-version: "3.12"
23
+ - name: Build wheels
24
+ uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
25
+ with:
26
+ target: ${{ matrix.platform.target }}
27
+ manylinux: auto
28
+ args: --release --out dist
29
+ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
30
+ with:
31
+ name: wheels-linux-${{ matrix.platform.target }}
32
+ path: dist
33
+
34
+ macos:
35
+ runs-on: ${{ matrix.runner }}
36
+ strategy:
37
+ fail-fast: false
38
+ matrix:
39
+ include:
40
+ - { runner: macos-15, target: aarch64-apple-darwin }
41
+ - { runner: macos-15-intel, target: x86_64-apple-darwin }
42
+ steps:
43
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
44
+ - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
45
+ with:
46
+ python-version: "3.12"
47
+ - name: Build wheels
48
+ uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
49
+ with:
50
+ target: ${{ matrix.target }}
51
+ args: --release --out dist
52
+ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
53
+ with:
54
+ name: wheels-macos-${{ matrix.target }}
55
+ path: dist
56
+
57
+ windows:
58
+ runs-on: windows-2022
59
+ steps:
60
+ - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
61
+ - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
62
+ with:
63
+ python-version: "3.12"
64
+ - name: Build wheels
65
+ uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
66
+ with:
67
+ target: x64
68
+ args: --release --out dist
69
+ - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
70
+ with:
71
+ name: wheels-windows-x64
72
+ path: dist
73
+
74
+ release:
75
+ name: Release
76
+ runs-on: ubuntu-latest
77
+ # Publish whatever built: a hosted runner shortage (macOS arm64) must not block the other wheels;
78
+ # a missing wheel is built locally and uploaded with --skip-existing semantics.
79
+ if: ${{ always() && startsWith(github.ref, 'refs/tags/v') }}
80
+ needs: [linux, macos, windows]
81
+ environment: pypi # PyPI trusted publisher is bound to this environment
82
+ permissions:
83
+ id-token: write
84
+ steps:
85
+ - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
86
+ - name: Publish to PyPI
87
+ uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
88
+ with:
89
+ command: upload
90
+ args: --skip-existing wheels-*/*.whl
@@ -0,0 +1,7 @@
1
+ /target/
2
+ /.venv/
3
+ __pycache__/
4
+ *.py[cod]
5
+
6
+ /docs/demo/_bench-copy.jsonl
7
+ /docs/demo/_preview.png
@@ -0,0 +1,31 @@
1
+ # jlogtail
2
+
3
+ This folder contains the Rust CLI and PyO3 extension for reading JSON Lines tails.
4
+
5
+ ## Layout
6
+
7
+ - `src/lib.rs`: shared bounded suffix reader, Codex history selector, and PyO3 module.
8
+ - `src/main.rs` and `src/cli.rs`: Rust CLI, suffix reads, filters, projection and follow mode.
9
+ - `python/jlogtail/`: PyO3-backed Python package and command entry point.
10
+ - `docs/demo/`: synthetic JSONL fixture, VHS tapes and recordings.
11
+ - `Cargo.toml`, `pyproject.toml`: Rust and Python package metadata.
12
+
13
+ ## Build
14
+
15
+ Run `cargo build --release` in this directory. Install the Rust command with `cargo install --path .`, or install the Python wheel and command with `pipx install jlogtail` / `uv tool install jlogtail`.
16
+
17
+ ## Style and behavior
18
+
19
+ - Read only the requested suffix. Do not replace reverse scanning with a full-file read.
20
+ - Emit only complete records in follow mode. Keep an unterminated suffix for the next poll and compare file IDs to detect rotation.
21
+ - Keep Python `tail()` on the shared Rust suffix reader. Preserve `native-history-tail.py` metadata keys and oldest-to-newest output order.
22
+ - Demo records must be synthetic. Benchmarks may read a temporary copy of a real transcript, never its live source.
23
+ - Do not publish to GitHub, PyPI or crates.io from this checkout.
24
+ - Keep generated `target/` and `.venv/` files out of `public.json`.
25
+ - The Orbit receipts note is a future integration pointer; do not edit Orbit host files here.
26
+ - This source folder is not a system-wide installation.
27
+ - Keep package exports listed in `public.json` in sync with the files that ship.
28
+
29
+ ## Checks
30
+
31
+ Build the Rust CLI with `cargo build --release`. Inspect the actual output with a small synthetic JSONL fixture. The public package has not been released.
@@ -0,0 +1,334 @@
1
+ # This file is automatically @generated by Cargo.
2
+ # It is not intended for manual editing.
3
+ version = 4
4
+
5
+ [[package]]
6
+ name = "autocfg"
7
+ version = "1.5.1"
8
+ source = "registry+https://github.com/rust-lang/crates.io-index"
9
+ checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
10
+
11
+ [[package]]
12
+ name = "file-id"
13
+ version = "0.2.3"
14
+ source = "registry+https://github.com/rust-lang/crates.io-index"
15
+ checksum = "e1fc6a637b6dc58414714eddd9170ff187ecb0933d4c7024d1abbd23a3cc26e9"
16
+ dependencies = [
17
+ "windows-sys",
18
+ ]
19
+
20
+ [[package]]
21
+ name = "heck"
22
+ version = "0.5.0"
23
+ source = "registry+https://github.com/rust-lang/crates.io-index"
24
+ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
25
+
26
+ [[package]]
27
+ name = "indoc"
28
+ version = "2.0.8"
29
+ source = "registry+https://github.com/rust-lang/crates.io-index"
30
+ checksum = "a37b2691796cffeb8a8cd305ac66e65841559f147f4e63231d0eafa4db5384d1"
31
+ dependencies = [
32
+ "rustversion",
33
+ ]
34
+
35
+ [[package]]
36
+ name = "itoa"
37
+ version = "1.0.19"
38
+ source = "registry+https://github.com/rust-lang/crates.io-index"
39
+ checksum = "3bd1574e617a9a6c1f8f8181bd7e841e1f20e4277607ef28945765188d6284d4"
40
+
41
+ [[package]]
42
+ name = "jlogtail"
43
+ version = "0.1.0"
44
+ dependencies = [
45
+ "file-id",
46
+ "pyo3",
47
+ "serde_json",
48
+ ]
49
+
50
+ [[package]]
51
+ name = "libc"
52
+ version = "0.2.191"
53
+ source = "registry+https://github.com/rust-lang/crates.io-index"
54
+ checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
55
+
56
+ [[package]]
57
+ name = "memchr"
58
+ version = "2.8.3"
59
+ source = "registry+https://github.com/rust-lang/crates.io-index"
60
+ checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
61
+
62
+ [[package]]
63
+ name = "memoffset"
64
+ version = "0.9.1"
65
+ source = "registry+https://github.com/rust-lang/crates.io-index"
66
+ checksum = "488016bfae457b036d996092f6cb448677611ce4449e970ceaf42695203f218a"
67
+ dependencies = [
68
+ "autocfg",
69
+ ]
70
+
71
+ [[package]]
72
+ name = "once_cell"
73
+ version = "1.21.4"
74
+ source = "registry+https://github.com/rust-lang/crates.io-index"
75
+ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
76
+
77
+ [[package]]
78
+ name = "portable-atomic"
79
+ version = "1.15.0"
80
+ source = "registry+https://github.com/rust-lang/crates.io-index"
81
+ checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
82
+
83
+ [[package]]
84
+ name = "proc-macro2"
85
+ version = "1.0.107"
86
+ source = "registry+https://github.com/rust-lang/crates.io-index"
87
+ checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
88
+ dependencies = [
89
+ "unicode-ident",
90
+ ]
91
+
92
+ [[package]]
93
+ name = "pyo3"
94
+ version = "0.27.2"
95
+ source = "registry+https://github.com/rust-lang/crates.io-index"
96
+ checksum = "ab53c047fcd1a1d2a8820fe84f05d6be69e9526be40cb03b73f86b6b03e6d87d"
97
+ dependencies = [
98
+ "indoc",
99
+ "libc",
100
+ "memoffset",
101
+ "once_cell",
102
+ "portable-atomic",
103
+ "pyo3-build-config",
104
+ "pyo3-ffi",
105
+ "pyo3-macros",
106
+ "unindent",
107
+ ]
108
+
109
+ [[package]]
110
+ name = "pyo3-build-config"
111
+ version = "0.27.2"
112
+ source = "registry+https://github.com/rust-lang/crates.io-index"
113
+ checksum = "b455933107de8642b4487ed26d912c2d899dec6114884214a0b3bb3be9261ea6"
114
+ dependencies = [
115
+ "target-lexicon",
116
+ ]
117
+
118
+ [[package]]
119
+ name = "pyo3-ffi"
120
+ version = "0.27.2"
121
+ source = "registry+https://github.com/rust-lang/crates.io-index"
122
+ checksum = "1c85c9cbfaddf651b1221594209aed57e9e5cff63c4d11d1feead529b872a089"
123
+ dependencies = [
124
+ "libc",
125
+ "pyo3-build-config",
126
+ ]
127
+
128
+ [[package]]
129
+ name = "pyo3-macros"
130
+ version = "0.27.2"
131
+ source = "registry+https://github.com/rust-lang/crates.io-index"
132
+ checksum = "0a5b10c9bf9888125d917fb4d2ca2d25c8df94c7ab5a52e13313a07e050a3b02"
133
+ dependencies = [
134
+ "proc-macro2",
135
+ "pyo3-macros-backend",
136
+ "quote",
137
+ "syn 2.0.119",
138
+ ]
139
+
140
+ [[package]]
141
+ name = "pyo3-macros-backend"
142
+ version = "0.27.2"
143
+ source = "registry+https://github.com/rust-lang/crates.io-index"
144
+ checksum = "03b51720d314836e53327f5871d4c0cfb4fb37cc2c4a11cc71907a86342c40f9"
145
+ dependencies = [
146
+ "heck",
147
+ "proc-macro2",
148
+ "pyo3-build-config",
149
+ "quote",
150
+ "syn 2.0.119",
151
+ ]
152
+
153
+ [[package]]
154
+ name = "quote"
155
+ version = "1.0.47"
156
+ source = "registry+https://github.com/rust-lang/crates.io-index"
157
+ checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
158
+ dependencies = [
159
+ "proc-macro2",
160
+ ]
161
+
162
+ [[package]]
163
+ name = "rustversion"
164
+ version = "1.0.23"
165
+ source = "registry+https://github.com/rust-lang/crates.io-index"
166
+ checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
167
+
168
+ [[package]]
169
+ name = "serde"
170
+ version = "1.0.229"
171
+ source = "registry+https://github.com/rust-lang/crates.io-index"
172
+ checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
173
+ dependencies = [
174
+ "serde_core",
175
+ ]
176
+
177
+ [[package]]
178
+ name = "serde_core"
179
+ version = "1.0.229"
180
+ source = "registry+https://github.com/rust-lang/crates.io-index"
181
+ checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
182
+ dependencies = [
183
+ "serde_derive",
184
+ ]
185
+
186
+ [[package]]
187
+ name = "serde_derive"
188
+ version = "1.0.229"
189
+ source = "registry+https://github.com/rust-lang/crates.io-index"
190
+ checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
191
+ dependencies = [
192
+ "proc-macro2",
193
+ "quote",
194
+ "syn 3.0.10",
195
+ ]
196
+
197
+ [[package]]
198
+ name = "serde_json"
199
+ version = "1.0.154"
200
+ source = "registry+https://github.com/rust-lang/crates.io-index"
201
+ checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
202
+ dependencies = [
203
+ "itoa",
204
+ "memchr",
205
+ "serde",
206
+ "serde_core",
207
+ "zmij",
208
+ ]
209
+
210
+ [[package]]
211
+ name = "syn"
212
+ version = "2.0.119"
213
+ source = "registry+https://github.com/rust-lang/crates.io-index"
214
+ checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"
215
+ dependencies = [
216
+ "proc-macro2",
217
+ "quote",
218
+ "unicode-ident",
219
+ ]
220
+
221
+ [[package]]
222
+ name = "syn"
223
+ version = "3.0.10"
224
+ source = "registry+https://github.com/rust-lang/crates.io-index"
225
+ checksum = "4ae9ccbea3a7b0b09443036490c8f34a8b1b760fd345e5c0dae0aac718faea79"
226
+ dependencies = [
227
+ "proc-macro2",
228
+ "quote",
229
+ "unicode-ident",
230
+ ]
231
+
232
+ [[package]]
233
+ name = "target-lexicon"
234
+ version = "0.13.6"
235
+ source = "registry+https://github.com/rust-lang/crates.io-index"
236
+ checksum = "8c447be3a2abfa84b2d91680c56600bd6b2873866de27b36ec911be705e291da"
237
+
238
+ [[package]]
239
+ name = "unicode-ident"
240
+ version = "1.0.27"
241
+ source = "registry+https://github.com/rust-lang/crates.io-index"
242
+ checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
243
+
244
+ [[package]]
245
+ name = "unindent"
246
+ version = "0.2.4"
247
+ source = "registry+https://github.com/rust-lang/crates.io-index"
248
+ checksum = "7264e107f553ccae879d21fbea1d6724ac785e8c3bfc762137959b5802826ef3"
249
+
250
+ [[package]]
251
+ name = "windows-link"
252
+ version = "0.2.1"
253
+ source = "registry+https://github.com/rust-lang/crates.io-index"
254
+ checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
255
+
256
+ [[package]]
257
+ name = "windows-sys"
258
+ version = "0.60.2"
259
+ source = "registry+https://github.com/rust-lang/crates.io-index"
260
+ checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb"
261
+ dependencies = [
262
+ "windows-targets",
263
+ ]
264
+
265
+ [[package]]
266
+ name = "windows-targets"
267
+ version = "0.53.5"
268
+ source = "registry+https://github.com/rust-lang/crates.io-index"
269
+ checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
270
+ dependencies = [
271
+ "windows-link",
272
+ "windows_aarch64_gnullvm",
273
+ "windows_aarch64_msvc",
274
+ "windows_i686_gnu",
275
+ "windows_i686_gnullvm",
276
+ "windows_i686_msvc",
277
+ "windows_x86_64_gnu",
278
+ "windows_x86_64_gnullvm",
279
+ "windows_x86_64_msvc",
280
+ ]
281
+
282
+ [[package]]
283
+ name = "windows_aarch64_gnullvm"
284
+ version = "0.53.1"
285
+ source = "registry+https://github.com/rust-lang/crates.io-index"
286
+ checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
287
+
288
+ [[package]]
289
+ name = "windows_aarch64_msvc"
290
+ version = "0.53.1"
291
+ source = "registry+https://github.com/rust-lang/crates.io-index"
292
+ checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
293
+
294
+ [[package]]
295
+ name = "windows_i686_gnu"
296
+ version = "0.53.1"
297
+ source = "registry+https://github.com/rust-lang/crates.io-index"
298
+ checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3"
299
+
300
+ [[package]]
301
+ name = "windows_i686_gnullvm"
302
+ version = "0.53.1"
303
+ source = "registry+https://github.com/rust-lang/crates.io-index"
304
+ checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
305
+
306
+ [[package]]
307
+ name = "windows_i686_msvc"
308
+ version = "0.53.1"
309
+ source = "registry+https://github.com/rust-lang/crates.io-index"
310
+ checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
311
+
312
+ [[package]]
313
+ name = "windows_x86_64_gnu"
314
+ version = "0.53.1"
315
+ source = "registry+https://github.com/rust-lang/crates.io-index"
316
+ checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499"
317
+
318
+ [[package]]
319
+ name = "windows_x86_64_gnullvm"
320
+ version = "0.53.1"
321
+ source = "registry+https://github.com/rust-lang/crates.io-index"
322
+ checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1"
323
+
324
+ [[package]]
325
+ name = "windows_x86_64_msvc"
326
+ version = "0.53.1"
327
+ source = "registry+https://github.com/rust-lang/crates.io-index"
328
+ checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
329
+
330
+ [[package]]
331
+ name = "zmij"
332
+ version = "1.0.23"
333
+ source = "registry+https://github.com/rust-lang/crates.io-index"
334
+ checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"
@@ -0,0 +1,23 @@
1
+ [package]
2
+ name = "jlogtail"
3
+ version = "0.1.0"
4
+ edition = "2021"
5
+ description = "Tail large JSON Lines transcripts by record or byte window"
6
+ license = "MIT"
7
+ readme = "README.md"
8
+
9
+ [lib]
10
+ name = "jlogtail"
11
+ crate-type = ["cdylib", "rlib"]
12
+
13
+ [features]
14
+ extension-module = ["dep:pyo3", "pyo3/extension-module", "pyo3/abi3-py39"]
15
+
16
+ [[bin]]
17
+ name = "jlogtail"
18
+ path = "src/main.rs"
19
+
20
+ [dependencies]
21
+ pyo3 = { version = "0.27.2", optional = true }
22
+ serde_json = "1"
23
+ file-id = "0.2.3"
jlogtail-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 El Fenomeno
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,94 @@
1
+ Metadata-Version: 2.4
2
+ Name: jlogtail
3
+ Version: 0.1.0
4
+ License-File: LICENSE
5
+ Summary: Tail large JSON Lines transcripts by record or byte window.
6
+ Keywords: jsonl,tail,transcript,logs,rust
7
+ Author: El Fenomeno
8
+ License-Expression: MIT
9
+ Requires-Python: >=3.9
10
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
11
+
12
+ # jlogtail
13
+ [한국어](README.ko.md)
14
+
15
+ A Rust command-line tool and Python module that read the end of large JSON Lines transcripts without loading the whole file.
16
+
17
+ <picture>
18
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/demo/dark.gif">
19
+ <img src="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/demo/light.gif" alt="The CLI selects recent transcript fields from a small JSONL fixture" width="1200">
20
+ </picture>
21
+
22
+ [Social preview](https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/social.png)
23
+
24
+ The demo uses synthetic transcript rows. It shows field selection and filtering, not benchmark data.
25
+
26
+ ## Install
27
+
28
+ ```sh
29
+ cargo install --path .
30
+ pipx install jlogtail
31
+ # or: uv tool install jlogtail
32
+ ```
33
+
34
+ The wheel installs the `jlogtail` command and the importable `jlogtail` PyO3 module. Use Cargo to install the standalone Rust CLI from this directory. Python 3.9+ is required; source builds also require Rust.
35
+
36
+ ## Quick start
37
+
38
+ ```sh
39
+ jlogtail ~/.claude/projects/PROJECT/session.jsonl --lines 20
40
+ jlogtail ~/.codex/sessions/SESSION.jsonl --bytes 65536
41
+ jlogtail transcript.jsonl --filter payload.role=assistant --fields timestamp,payload.role
42
+ jlogtail transcript.jsonl --follow
43
+ ```
44
+
45
+ Claude Code, Codex, and Pi transcripts use the same JSONL commands. The CLI outputs original rows by default. `--fields` emits a compact object with selected dotted paths. `--filter PATH=VALUE` compares JSON values; unquoted non-JSON values are strings. A byte window skips a partial first record but keeps it when the window starts at a line boundary. Follow reads each appended byte once, keeps an incomplete row in memory, and emits it when the newline arrives.
46
+
47
+ ```console
48
+ $ jlogtail docs/demo/agents.jsonl --lines 2 --fields role,text
49
+ {"role":"assistant","text":"Checkpoint 42 finished."}
50
+ {"role":"assistant","text":"The next run is queued."}
51
+ ```
52
+
53
+ ## How it reads
54
+
55
+ <picture>
56
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/diagrams/tail-flow.en.dark.svg">
57
+ <img src="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/diagrams/tail-flow.en.light.svg" alt="The reader seeks to the requested boundary, filters complete rows, then follows appended data and resets after rotation or truncation" width="1200">
58
+ </picture>
59
+
60
+ ## Why
61
+
62
+ `tail -n 20 file.jsonl | jq .` is useful for full-file pipelines and richer JSON queries, but it reads from the start to find the last rows. This tool seeks backward to the requested records, then reads only that suffix. It is for large transcripts and repeated polling.
63
+
64
+ ## Measurements
65
+
66
+ On M5 Pro, macOS arm64, hyperfine ran 3 warmups and 10 measured runs per command against one 2.18 GB temporary copy. The read-only 272.9 MB source transcript was repeated eight times. Mean wall times were 5.0 ms for jlogtail, 66.5 ms for `tail | jq`, and 1395.6 ms for Python's full read. See the [summary](docs/bench/m5-bench.txt), [raw output](docs/bench/m5-hyperfine.txt), and [raw measurements](docs/bench/m5-hyperfine.json). Results describe this copy and host only.
67
+
68
+ <picture>
69
+ <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/diagrams/bench-results.en.dark.svg">
70
+ <img src="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/diagrams/bench-results.en.light.svg" alt="Warm-cache mean wall time across 10 runs: Rust reverse tail 5.0 milliseconds, tail plus jq 66.5 milliseconds, Python full read 1395.6 milliseconds" width="1200">
71
+ </picture>
72
+
73
+ ## Reference
74
+
75
+ | Option | Meaning |
76
+ |---|---|
77
+ | `--lines N`, `-n N` | Read the last N complete records; default 10 |
78
+ | `--bytes N`, `-c N` | Read N trailing bytes and drop a partial first record unless the window starts at a line boundary |
79
+ | `--follow`, `-f` | Emit complete appended records; restart from byte 0 after replacement or truncation |
80
+ | `--filter PATH=VALUE` | Keep rows whose dotted key path equals the JSON value |
81
+ | `--fields PATH,...` | Emit only the selected dotted paths as a compact object |
82
+ | `--poll-ms N` | Follow poll interval; default 250 ms |
83
+ | `--keep-partial-first` | Keep the first partial row in a byte window |
84
+
85
+ The Python module provides `jlogtail.tail(path, lines=20)` for raw complete rows; use `byte_window=N` to choose a suffix by bytes. `jlogtail.select_native(path)` returns a metadata dictionary and oldest-to-newest Codex message objects. `lib/native-history-tail.py` preserves feno-handoff's existing one-path command and metadata output.
86
+
87
+ ## Limits
88
+
89
+ The benchmark and demo ran on macOS arm64. Linux and Windows builds have not been exercised. Follow compares platform file IDs and resets when it observes a shorter file. The benchmark ran on macOS arm64; Linux and Windows follow behavior has not been exercised. A filter requires valid JSON. A follow poll waits for the newline that completes each row.
90
+
91
+ ## License
92
+
93
+ MIT. See [LICENSE](LICENSE).
94
+