jlogtail 0.1.2__tar.gz → 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 (56) hide show
  1. jlogtail-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml +45 -0
  2. jlogtail-0.2.0/.github/ISSUE_TEMPLATE/config.yml +5 -0
  3. jlogtail-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml +25 -0
  4. jlogtail-0.2.0/.github/pull_request_template.md +14 -0
  5. jlogtail-0.2.0/.github/workflows/claude.yml +26 -0
  6. jlogtail-0.2.0/.github/workflows/opencode-review.yml +66 -0
  7. {jlogtail-0.1.2 → jlogtail-0.2.0}/AGENTS.md +15 -1
  8. jlogtail-0.2.0/CHANGELOG.md +51 -0
  9. jlogtail-0.2.0/CODE_OF_CONDUCT.md +43 -0
  10. jlogtail-0.2.0/CONTRIBUTING.md +50 -0
  11. {jlogtail-0.1.2 → jlogtail-0.2.0}/Cargo.lock +1 -1
  12. {jlogtail-0.1.2 → jlogtail-0.2.0}/Cargo.toml +1 -1
  13. {jlogtail-0.1.2 → jlogtail-0.2.0}/PKG-INFO +27 -4
  14. {jlogtail-0.1.2 → jlogtail-0.2.0}/README.ko.md +27 -4
  15. {jlogtail-0.1.2 → jlogtail-0.2.0}/README.md +26 -3
  16. jlogtail-0.2.0/SECURITY.md +43 -0
  17. jlogtail-0.2.0/docs/demo/dark.gif +0 -0
  18. jlogtail-0.2.0/docs/demo/light.gif +0 -0
  19. jlogtail-0.2.0/docs/logo.svg +7 -0
  20. jlogtail-0.2.0/docs/orbit-receipts-incremental-follow.md +5 -0
  21. {jlogtail-0.1.2 → jlogtail-0.2.0}/public.json +14 -2
  22. {jlogtail-0.1.2 → jlogtail-0.2.0}/pyproject.toml +1 -1
  23. jlogtail-0.2.0/python/jlogtail/__init__.py +60 -0
  24. jlogtail-0.2.0/src/cli.rs +459 -0
  25. {jlogtail-0.1.2 → jlogtail-0.2.0}/src/lib.rs +314 -79
  26. jlogtail-0.1.2/docs/demo/dark.gif +0 -0
  27. jlogtail-0.1.2/docs/demo/light.gif +0 -0
  28. jlogtail-0.1.2/python/jlogtail/__init__.py +0 -19
  29. jlogtail-0.1.2/src/cli.rs +0 -228
  30. {jlogtail-0.1.2 → jlogtail-0.2.0}/.github/workflows/wheels.yml +0 -0
  31. {jlogtail-0.1.2 → jlogtail-0.2.0}/.gitignore +0 -0
  32. {jlogtail-0.1.2 → jlogtail-0.2.0}/LICENSE +0 -0
  33. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/bench/m5-bench.txt +0 -0
  34. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/bench/m5-hyperfine.json +0 -0
  35. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/bench/m5-hyperfine.txt +0 -0
  36. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/demo/agents.jsonl +0 -0
  37. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/demo/codex-sample.jsonl +0 -0
  38. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/demo/dark.tape +0 -0
  39. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/demo/light.tape +0 -0
  40. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/demo/setup.sh +0 -0
  41. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/bench-results.en.dark.svg +0 -0
  42. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/bench-results.en.light.svg +0 -0
  43. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/bench-results.en.mmd +0 -0
  44. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/bench-results.ko.dark.svg +0 -0
  45. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/bench-results.ko.light.svg +0 -0
  46. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/bench-results.ko.mmd +0 -0
  47. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/tail-flow.en.dark.svg +0 -0
  48. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/tail-flow.en.light.svg +0 -0
  49. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/tail-flow.en.mmd +0 -0
  50. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/tail-flow.ko.dark.svg +0 -0
  51. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/tail-flow.ko.light.svg +0 -0
  52. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/diagrams/tail-flow.ko.mmd +0 -0
  53. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/social.json +0 -0
  54. {jlogtail-0.1.2 → jlogtail-0.2.0}/docs/social.png +0 -0
  55. {jlogtail-0.1.2 → jlogtail-0.2.0}/python/jlogtail/cli.py +0 -0
  56. {jlogtail-0.1.2 → jlogtail-0.2.0}/src/main.rs +0 -0
@@ -0,0 +1,45 @@
1
+ name: Bug report
2
+ description: Something did not work the way this repository says it should.
3
+ labels: ["bug"]
4
+ body:
5
+ - type: markdown
6
+ attributes:
7
+ value: |
8
+ Do not report a security problem here. Use the private advisories form instead.
9
+ - type: textarea
10
+ id: happened
11
+ attributes:
12
+ label: What happened
13
+ description: The command you ran and its output, copied as text.
14
+ placeholder: |
15
+ $ jlogtail
16
+ ...
17
+ validations:
18
+ required: true
19
+ - type: textarea
20
+ id: expected
21
+ attributes:
22
+ label: What you expected
23
+ validations:
24
+ required: true
25
+ - type: input
26
+ id: version
27
+ attributes:
28
+ label: Version
29
+ description: '`jlogtail --version`, or the commit you built.'
30
+ validations:
31
+ required: true
32
+ - type: input
33
+ id: platform
34
+ attributes:
35
+ label: Platform
36
+ description: 'OS and version, and whether you used the CLI or the Python module.'
37
+ validations:
38
+ required: true
39
+ - type: textarea
40
+ id: extra
41
+ attributes:
42
+ label: Anything else
43
+ description: A small reproduction, or what you already tried.
44
+ validations:
45
+ required: false
@@ -0,0 +1,5 @@
1
+ blank_issues_enabled: true
2
+ contact_links:
3
+ - name: Report a security vulnerability
4
+ url: https://github.com/elfenomenokim/jlogtail/security/advisories/new
5
+ about: Please report security problems privately, not in a public issue.
@@ -0,0 +1,25 @@
1
+ name: Feature request
2
+ description: A task this tool should do and does not.
3
+ labels: ["enhancement"]
4
+ body:
5
+ - type: textarea
6
+ id: problem
7
+ attributes:
8
+ label: The problem
9
+ description: What you were doing when this got in the way. A command and its output help.
10
+ validations:
11
+ required: true
12
+ - type: textarea
13
+ id: proposal
14
+ attributes:
15
+ label: What you suggest
16
+ description: The command, flag or output you expect. Small and concrete is easier to build.
17
+ validations:
18
+ required: true
19
+ - type: textarea
20
+ id: alternatives
21
+ attributes:
22
+ label: What you use instead
23
+ description: Another tool, a shell wrapper, or nothing. Optional.
24
+ validations:
25
+ required: false
@@ -0,0 +1,14 @@
1
+ ## What and why
2
+
3
+ <!-- What was wrong or missing, and how this change fixes it. Link the issue: Fixes #123 -->
4
+
5
+ ## How to check it
6
+
7
+ <!-- The commands that show the change working, with their output. -->
8
+
9
+ ## Checklist
10
+
11
+ - [ ] `cargo build --release` passes
12
+ - [ ] The fixture commands in the pull request print complete records
13
+ - [ ] `CHANGELOG.md` has a line under Unreleased if users will notice the change
14
+ - [ ] Anything I could not test is written above (another OS, a browser, a router)
@@ -0,0 +1,26 @@
1
+ name: Claude on request
2
+ on:
3
+ issue_comment:
4
+ types: [created]
5
+ pull_request_review_comment:
6
+ types: [created]
7
+ jobs:
8
+ claude:
9
+ # Runs only when a maintainer mentions @claude (for example "@claude review").
10
+ if: contains(github.event.comment.body, '@claude')
11
+ runs-on: ubuntu-latest
12
+ timeout-minutes: 20
13
+ permissions:
14
+ contents: read
15
+ pull-requests: write
16
+ issues: write
17
+ id-token: write
18
+ actions: read
19
+ steps:
20
+ - uses: actions/checkout@v6
21
+ with:
22
+ fetch-depth: 1
23
+ - uses: anthropics/claude-code-action@v1
24
+ with:
25
+ claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
26
+ claude_args: "--max-turns 30"
@@ -0,0 +1,66 @@
1
+ name: opencode-review
2
+
3
+ on:
4
+ pull_request:
5
+ types: [opened, synchronize, reopened, ready_for_review]
6
+
7
+ concurrency:
8
+ group: opencode-review-${{ github.event.pull_request.number }}
9
+ cancel-in-progress: true
10
+
11
+ permissions:
12
+ contents: read
13
+ pull-requests: write
14
+ issues: write
15
+
16
+ jobs:
17
+ review:
18
+ if: ${{ github.event.pull_request.draft == false }}
19
+ runs-on: ubuntu-latest
20
+ timeout-minutes: 20
21
+ steps:
22
+ # Three OpenCode Go keys share one credit pool each; spread pull requests over them.
23
+ - name: Pick an OpenCode Go key
24
+ id: go
25
+ env:
26
+ KEY_1: ${{ secrets.OPENCODE_GO_1 }}
27
+ KEY_2: ${{ secrets.OPENCODE_GO_2 }}
28
+ KEY_3: ${{ secrets.OPENCODE_GO_3 }}
29
+ run: |
30
+ case $((GITHUB_RUN_NUMBER % 3)) in
31
+ 0) echo "value=$KEY_1" >> "$GITHUB_OUTPUT" ;;
32
+ 1) echo "value=$KEY_2" >> "$GITHUB_OUTPUT" ;;
33
+ *) echo "value=$KEY_3" >> "$GITHUB_OUTPUT" ;;
34
+ esac
35
+ - uses: actions/checkout@v6
36
+ with:
37
+ persist-credentials: false
38
+ - name: Git identity for the review action
39
+ run: |
40
+ git config --global user.name "opencode-review"
41
+ git config --global user.email "opencode-review@users.noreply.github.com"
42
+ - name: Run OpenCode review
43
+ uses: anomalyco/opencode/github@latest
44
+ env:
45
+ OPENCODE_API_KEY: ${{ steps.go.outputs.value }}
46
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
47
+ with:
48
+ model: opencode-go/deepseek-v4.1-flash
49
+ use_github_token: true
50
+ prompt: |
51
+ Review this pull request for real defects only.
52
+
53
+ Report a finding only when the change produces a wrong result, an unhandled
54
+ error, a leaked process, handle or temporary file, a broken edge case (empty,
55
+ huge, unicode, concurrent, interrupted), data loss, a security problem, or a
56
+ behaviour that contradicts the README or AGENTS.md contract.
57
+ Do not report style, naming, formatting, comment wording, missing tests, or
58
+ speculative refactors. The repository AGENTS.md "Code Review Rules" section
59
+ lists what counts as a real defect for this tool.
60
+
61
+ For each finding give one line: severity (P0 blocker, P1 real defect),
62
+ file:line, what breaks, and the smallest correct fix.
63
+ If nothing qualifies, reply with one short line saying no real defects were found.
64
+ Keep the whole comment under 40 lines. Do not edit code, do not push commits,
65
+ do not run the test suite. Read the code only: do not execute the project's
66
+ scripts or binaries, make network calls, or run git commands that change state.
@@ -19,6 +19,7 @@ Run `cargo build --release` in this directory. Install the Rust command with `ca
19
19
  - Read only the requested suffix. Do not replace reverse scanning with a full-file read.
20
20
  - Emit only complete records in follow mode. Keep an unterminated suffix for the next poll, including the one already present when follow starts, and compare file IDs to detect rotation.
21
21
  - Classify an oversized record from its own first bytes, not from the scan segment that happens to hold them; a record can start in the last byte of a block.
22
+ - Enforce the `max_bytes` ceiling (`DEFAULT_MAX_BYTES`, 64 MiB) across `read_tail` / `read_tail_bounded`, follow-mode chunk reads, and incomplete-record buffering; skip oversized records with a clear marker instead of growing an unbounded buffer.
22
23
  - Keep Python `tail()` on the shared Rust suffix reader. Preserve `native-history-tail.py` metadata keys and oldest-to-newest output order.
23
24
  - Demo records must be synthetic. Benchmarks may read a temporary copy of a real transcript, never its live source.
24
25
  - Do not publish to GitHub, PyPI or crates.io from this checkout.
@@ -29,4 +30,17 @@ Run `cargo build --release` in this directory. Install the Rust command with `ca
29
30
 
30
31
  ## Checks
31
32
 
32
- 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.
33
+ Run `cargo test -j 1` and `cargo build --release` in this directory. Inspect the actual output with a small synthetic JSONL fixture under `docs/demo/`.
34
+
35
+ ## Code Review Rules
36
+
37
+ A change is a real defect when it:
38
+
39
+ - reads the whole file instead of the requested suffix or byte window.
40
+ - drifts a byte window off a line boundary, exposing a partial last line as a record.
41
+ - emits an incomplete record in follow mode, drops the unterminated suffix it must keep, or misses a rotation because file IDs are not compared.
42
+ - classifies an oversized record from the segment holding it instead of from its own first bytes.
43
+ - moves Python `tail()` off the shared Rust suffix reader, or changes the `native-history-tail.py` metadata keys or oldest-to-newest order.
44
+ - changes a CLI flag, JSON field or exit code that the README documents.
45
+
46
+ Not defects: wording, formatting, comment style, requested extra tests, or a renamed helper.
@@ -0,0 +1,51 @@
1
+ # Changelog
2
+
3
+ All notable changes to this project are documented here. The format follows
4
+ [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses `MAJOR.MINOR.PATCH`.
5
+
6
+ ## [0.2.0] - 2026-11-19
7
+
8
+ ### Added
9
+
10
+ - Caller-set memory ceiling across `read_tail_bounded`, `--max-bytes` (default 64 MiB), follow-mode
11
+ appended reads, and incomplete trailing-record buffering.
12
+ - `jlogtail.tail(..., max_bytes=DEFAULT_MAX_BYTES, keep_partial_first=False)` and
13
+ `jlogtail.tail_window(...)` returning `(meta, rows)` with `end_offset`, `max_bytes`,
14
+ `skipped_oversized`, `ceiling_reached`, and `trailing_oversized`.
15
+ - Clear markers when a record exceeds the ceiling or caps the window: `stderr` diagnostics in the
16
+ CLI, `RuntimeWarning` in Python `tail()`, and explicit fields on `TailWindow`.
17
+ - `--version` / `-V` CLI flag matching `SECURITY.md`.
18
+
19
+ ### Changed
20
+
21
+ - `read_tail` and Python `tail()` enforce the safe 64 MiB default ceiling (`DEFAULT_MAX_BYTES`)
22
+ instead of unbounded `read_to_end` and backward scans.
23
+ - Follow mode reads appended bytes in bounded chunks and discards oversized records until the next
24
+ newline instead of growing `pending` without limit.
25
+
26
+ ## [0.1.2] - 2026-11-18
27
+
28
+ ### Fixed
29
+
30
+ - Follow mode keeps an unfinished record that is already in the file when the follow starts, so
31
+ the first poll emits the whole row instead of a fragment. `--lines 0` had the same problem.
32
+ - An oversized record that begins near the end of a scan block is classified from its own prefix
33
+ instead of from the partial block, so older messages stay eligible.
34
+
35
+ ## [0.1.1] - 2026-11-18
36
+
37
+ ### Fixed
38
+
39
+ - The Codex selector matches the reference `native-history-tail` behaviour on user barriers and a
40
+ byte-order mark.
41
+
42
+ ### Changed
43
+
44
+ - Wheels are built as abi3-py39: one wheel per platform for Python 3.9 and newer.
45
+
46
+ ## [0.1.0] - 2026-11-17
47
+
48
+ ### Added
49
+
50
+ - Rust CLI and PyO3 module that read the end of a JSON Lines file without loading it.
51
+ - `--lines`, `--bytes`, `--filter`, `--fields`, `--follow` and the Codex message selector.
@@ -0,0 +1,43 @@
1
+ # Code of conduct
2
+
3
+ ## Our pledge
4
+
5
+ We want jlogtail to be a welcoming project for everyone, whatever their age, body, disability,
6
+ ethnicity, gender identity and expression, level of experience, education, nationality, personal
7
+ appearance, race, religion, or sexual identity and orientation.
8
+
9
+ ## Our standards
10
+
11
+ Things that make the project better:
12
+
13
+ - Being kind, patient and respectful, including in disagreement.
14
+ - Giving and taking constructive criticism gracefully. Criticize code and ideas, not people.
15
+ - Assuming good intent, and asking when something is unclear.
16
+ - Owning mistakes and learning from them.
17
+
18
+ Things that are not acceptable:
19
+
20
+ - Harassment, insults, or personal or political attacks.
21
+ - Sexualized language or imagery, or unwelcome attention.
22
+ - Publishing someone's private information without their permission.
23
+ - Anything else that would reasonably be considered inappropriate in a professional setting.
24
+
25
+ ## Scope
26
+
27
+ This applies in every project space (issues, pull requests, discussions, reviews) and when
28
+ someone represents the project elsewhere.
29
+
30
+ ## Enforcement
31
+
32
+ Reports go to the maintainer, [@elfenomenokim](https://github.com/elfenomenokim), through GitHub.
33
+ For something you would rather not post in public, use
34
+ [Report a vulnerability](https://github.com/elfenomenokim/jlogtail/security/advisories/new) and say
35
+ it is a conduct report. Every report is reviewed and the reporter's privacy is respected.
36
+
37
+ The maintainer may remove, edit or reject comments, commits, code, issues and other contributions
38
+ that break this code, and may ban, temporarily or permanently, anyone whose behavior is harmful.
39
+
40
+ ## Attribution
41
+
42
+ This code of conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
43
+ version 2.1.
@@ -0,0 +1,50 @@
1
+ # Contributing to jlogtail
2
+
3
+ Fixes and reports are welcome. You do not need to ask before opening a pull request for a bug fix.
4
+
5
+ ## Before you start
6
+
7
+ - **A bug:** open an [issue](https://github.com/elfenomenokim/jlogtail/issues/new/choose) with the
8
+ command, its output, the record shape (make one up if yours is private) and your platform.
9
+ - **A change to what counts as a message:** open an issue first. The Codex selector follows
10
+ observed transcript shapes, and a wrong classification silently drops history.
11
+ - **A security problem:** do not open a public issue. See [SECURITY.md](SECURITY.md).
12
+
13
+ ## Set up
14
+
15
+ ```sh
16
+ git clone https://github.com/elfenomenokim/jlogtail
17
+ cd jlogtail
18
+ cargo test -j 1
19
+ cargo build --release
20
+ ./target/release/jlogtail docs/demo/agents.jsonl --lines 2 --fields role,text
21
+ ```
22
+
23
+ Run `cargo test -j 1` and verify the CLI output against a synthetic file under `docs/demo/`. The Python module is
24
+ built by maturin; `python3 -m pip wheel --no-deps --wheel-dir target/wheels .` after the Rust
25
+ build passes.
26
+
27
+ ## Rules a patch must keep
28
+
29
+ - Read only the requested suffix within `max_bytes`. A full-file or unbounded read is not an acceptable implementation of a tail.
30
+ - Emit complete records only. A row that starts inside a byte window is skipped, and a follow poll
31
+ keeps an unterminated row up to `max_bytes` until the newline arrives (oversized records are skipped with a clear marker).
32
+ - Classify an oversized record from its own first bytes, not from the scan block that happens to
33
+ hold them.
34
+ - Keep the Python `tail()` on the shared Rust reader, so both editions agree.
35
+
36
+ ## What a good patch has
37
+
38
+ - **A fixture that shows the bug**, and the same command passing after the fix.
39
+ - **A line under Unreleased** in [CHANGELOG.md](CHANGELOG.md) when a user will notice.
40
+ - **The platforms you did not test** written in the pull request. The benchmark and demo ran on
41
+ macOS arm64; Linux and Windows follow behaviour has not been exercised.
42
+
43
+ ## Review
44
+
45
+ Every pull request runs an automatic DeepSeek review. Ask for another pass with `@codex review` or
46
+ `@claude review` in a comment. If a finding looks wrong, say why in the pull request.
47
+
48
+ ## Licence
49
+
50
+ Contributions are licensed under the MIT licence in [LICENSE](LICENSE).
@@ -40,7 +40,7 @@ checksum = "3bd1574e617a9a6c1f8f8181bd7e841e1f20e4277607ef28945765188d6284d4"
40
40
 
41
41
  [[package]]
42
42
  name = "jlogtail"
43
- version = "0.1.2"
43
+ version = "0.2.0"
44
44
  dependencies = [
45
45
  "file-id",
46
46
  "pyo3",
@@ -1,6 +1,6 @@
1
1
  [package]
2
2
  name = "jlogtail"
3
- version = "0.1.2"
3
+ version = "0.2.0"
4
4
  edition = "2021"
5
5
  description = "Tail large JSON Lines transcripts by record or byte window"
6
6
  license = "MIT"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: jlogtail
3
- Version: 0.1.2
3
+ Version: 0.2.0
4
4
  License-File: LICENSE
5
5
  Summary: Tail large JSON Lines transcripts by record or byte window.
6
6
  Keywords: jsonl,tail,transcript,logs,rust
@@ -9,15 +9,32 @@ License-Expression: MIT
9
9
  Requires-Python: >=3.9
10
10
  Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
11
11
 
12
+ <div align="center">
13
+
14
+ <img src="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/logo.svg" width="96" height="96" alt="jlogtail: the last lines of a file, measured from the end">
15
+
12
16
  # jlogtail
13
17
  [한국어](README.ko.md)
14
18
 
15
19
  A Rust command-line tool and Python module that read the end of large JSON Lines transcripts without loading the whole file.
16
20
 
21
+ Rust · Python 3.9+
22
+
23
+ [![pypi](https://img.shields.io/pypi/v/jlogtail?label=pypi)](https://pypi.org/project/jlogtail/)
24
+ [![license](https://img.shields.io/github/license/elfenomenokim/jlogtail)](https://github.com/elfenomenokim/jlogtail/blob/main/LICENSE)
25
+
26
+ 5.0 ms for the tail of a 2.18 GB transcript, against 66.5 ms for `tail | jq` and 1395.6 ms for a full Python read, from the saved 10-run file.
27
+
28
+ [Install](#install) · [Quick start](#quick-start) · [How it reads](#how-it-reads)
29
+
30
+ </div>
31
+
32
+ <p align="center">
17
33
  <picture>
18
34
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/demo/dark.gif">
19
35
  <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
36
  </picture>
37
+ </p>
21
38
 
22
39
  [Social preview](https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/social.png)
23
40
 
@@ -42,7 +59,7 @@ jlogtail transcript.jsonl --filter payload.role=assistant --fields timestamp,pay
42
59
  jlogtail transcript.jsonl --follow
43
60
  ```
44
61
 
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. A row that is already unfinished when follow starts is kept from its first byte, so the first poll emits the whole row rather than a fragment.
62
+ 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. Every read path—initial `read_tail`, appended `--follow` reads, and incomplete trailing-record buffering—enforces `--max-bytes` (default 64 MiB). When a record exceeds `--max-bytes`, `jlogtail` skips it and prints a marker to `stderr` instead of growing an unbounded buffer. A row that is already unfinished when follow starts is kept from its first byte when within `--max-bytes`, so the first poll emits the whole row rather than a fragment.
46
63
 
47
64
  ```console
48
65
  $ jlogtail docs/demo/agents.jsonl --lines 2 --fields role,text
@@ -80,13 +97,19 @@ On M5 Pro, macOS arm64, hyperfine ran 3 warmups and 10 measured runs per command
80
97
  | `--filter PATH=VALUE` | Keep rows whose dotted key path equals the JSON value |
81
98
  | `--fields PATH,...` | Emit only the selected dotted paths as a compact object |
82
99
  | `--poll-ms N` | Follow poll interval; default 250 ms |
100
+ | `--max-bytes N` | Memory ceiling in bytes for `read_tail`, follow reads, and pending incomplete records; default 67108864 (64 MiB) |
83
101
  | `--keep-partial-first` | Keep the first partial row in a byte window |
102
+ | `--version`, `-V` | Print the `jlogtail` version and exit |
84
103
 
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.
104
+ The Python module provides `jlogtail.tail(path, lines=10, byte_window=None, max_bytes=jlogtail.DEFAULT_MAX_BYTES, keep_partial_first=False)` for raw complete rows (emitting a `RuntimeWarning` if a record is skipped or the window hits `max_bytes`). `jlogtail.tail_window(...)` returns `(meta, rows)` with `end_offset`, `max_bytes`, `skipped_oversized`, `ceiling_reached`, and `trailing_oversized`. `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
105
 
87
106
  ## Limits
88
107
 
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.
108
+ 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. Records larger than `--max-bytes` (default 64 MiB) are skipped with a clear `stderr` marker (or Python `RuntimeWarning` and metadata count) rather than buffering past the ceiling.
109
+
110
+ ## Contributing
111
+
112
+ Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the build, the fixture check and the review process.
90
113
 
91
114
  ## License
92
115
 
@@ -1,12 +1,29 @@
1
+ <div align="center">
2
+
3
+ <img src="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/logo.svg" width="96" height="96" alt="파일 끝에서부터 마지막 줄만 읽는 모습을 나타낸 아이콘">
4
+
1
5
  # jlogtail
2
6
  [English](README.md)
3
7
 
4
8
  큰 JSON Lines 대화 기록에서 파일 전체를 메모리에 올리지 않고 끝부분을 읽는 Rust 명령줄 도구이자 Python 모듈입니다.
5
9
 
10
+ Rust · Python 3.9+
11
+
12
+ [![pypi](https://img.shields.io/pypi/v/jlogtail?label=pypi)](https://pypi.org/project/jlogtail/)
13
+ [![license](https://img.shields.io/github/license/elfenomenokim/jlogtail)](https://github.com/elfenomenokim/jlogtail/blob/main/LICENSE)
14
+
15
+ 2.18GB 대화 기록의 끝을 읽는 데 5.0ms입니다. `tail | jq`는 66.5ms, Python으로 전체를 읽으면 1395.6ms입니다. 저장된 10회 측정에서 가져왔습니다.
16
+
17
+ [설치](#설치) · [시작하기](#시작하기) · [읽는 순서](#읽는-순서)
18
+
19
+ </div>
20
+
21
+ <p align="center">
6
22
  <picture>
7
23
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/demo/dark.gif">
8
24
  <img src="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/demo/light.gif" alt="작은 JSONL 예시에서 최근 대화 필드를 고르는 CLI" width="1200">
9
25
  </picture>
26
+ </p>
10
27
 
11
28
  [소셜 미리보기 이미지](https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/social.png)
12
29
 
@@ -31,7 +48,7 @@ jlogtail transcript.jsonl --filter payload.role=assistant --fields timestamp,pay
31
48
  jlogtail transcript.jsonl --follow
32
49
  ```
33
50
 
34
- Claude Code, Codex, Pi 대화 기록에 같은 명령을 쓸 수 있습니다. CLI는 기본적으로 원래 JSONL 행을 출력합니다. `--fields`는 선택한 점 경로만 간결한 객체로 출력합니다. `--filter PATH=VALUE`는 JSON 값과 비교하며, JSON 문법이 아닌 값은 문자열로 처리합니다. 바이트 창은 첫 행이 잘린 경우에만 건너뜁니다. `--follow`는 추가된 바이트를 한 번씩 읽고, 끝이 잘린 행을 메모리에 보관했다가 줄바꿈이 오면 출력합니다. follow를 시작할 때 이미 끝나지 않은 행이 있으면 첫 바이트부터 보관하므로, 첫 확인에서 조각이 아니라 완성된 행을 출력합니다.
51
+ Claude Code, Codex, Pi 대화 기록에 같은 명령을 쓸 수 있습니다. CLI는 기본적으로 원래 JSONL 행을 출력합니다. `--fields`는 선택한 점 경로만 간결한 객체로 출력합니다. `--filter PATH=VALUE`는 JSON 값과 비교하며, JSON 문법이 아닌 값은 문자열로 처리합니다. 바이트 창은 첫 행이 잘린 경우에만 건너뜁니다. 초기 `read_tail`, `--follow` 추가 읽기, 끝나지 않은 마지막 행 버퍼링 모두 `--max-bytes`(기본 64 MiB) 상한을 지킵니다. 상한을 넘는 행은 버퍼를 무한정 키우지 않고 건너뛴 뒤 `stderr`에 알림을 남깁니다. follow를 시작할 때 이미 끝나지 않은 행이 있으면 `--max-bytes` 안에서 첫 바이트부터 보관해, 첫 확인에서 조각이 아니라 완성된 행을 출력합니다.
35
52
 
36
53
  ```console
37
54
  $ jlogtail docs/demo/agents.jsonl --lines 2 --fields role,text
@@ -69,14 +86,20 @@ M5 Pro macOS arm64에서 hyperfine으로 명령마다 예열 3회와 측정 10
69
86
  | `--filter PATH=VALUE` | 점으로 구분한 경로의 값이 일치하는 행만 남깁니다. |
70
87
  | `--fields PATH,...` | 선택한 경로만 간결한 객체로 출력합니다. |
71
88
  | `--poll-ms N` | follow 확인 간격입니다. 기본값은 250ms입니다. |
89
+ | `--max-bytes N` | `read_tail`, follow 추가 읽기, 미완성 행 버퍼의 메모리 상한(바이트)입니다. 기본값은 67108864(64 MiB)입니다. |
72
90
  | `--keep-partial-first` | 바이트 창에서 첫 행의 일부도 유지합니다. |
91
+ | `--version`, `-V` | `jlogtail` 버전을 출력하고 종료합니다. |
73
92
 
74
- Python 모듈의 `jlogtail.tail(path, lines=20)`은 완성된 원본 행을 반환합니다. `byte_window=N`으로 바이트 창을 지정할 수도 있습니다. `jlogtail.select_native(path)`는 메타데이터 사전과 오래된 순서의 최근 Codex 메시지 객체를 반환합니다. `lib/native-history-tail.py`는 기존 feno-handoff의 단일 경로 인자와 메타데이터 출력을 유지합니다.
93
+ Python 모듈의 `jlogtail.tail(path, lines=10, byte_window=None, max_bytes=jlogtail.DEFAULT_MAX_BYTES, keep_partial_first=False)`는 완성된 원본 행을 반환하며, 상한 초과로 행을 건너뛰거나 창이 잘리면 `RuntimeWarning`을 발생시킵니다. `jlogtail.tail_window(...)`는 `end_offset`, `max_bytes`, `skipped_oversized`, `ceiling_reached`, `trailing_oversized`가 담긴 메타데이터 사전과 행 목록을 함께 반환합니다. `jlogtail.select_native(path)`는 메타데이터 사전과 오래된 순서의 최근 Codex 메시지 객체를 반환합니다. `lib/native-history-tail.py`는 기존 feno-handoff의 단일 경로 인자와 메타데이터 출력을 유지합니다.
75
94
 
76
95
  ## 제한
77
96
 
78
- macOS arm64에서 빌드와 예시를 확인했습니다. Linux와 Windows 빌드는 아직 실행하지 않았습니다. follow는 플랫폼 파일 ID를 비교하고 파일 크기가 줄어든 것을 확인하면 위치를 초기화합니다. 성능 측정은 macOS arm64에서만 했으며, Linux와 Windows의 follow 동작은 실행하지 않았습니다. 필터는 올바른 JSON 행이 필요합니다. follow는 각 행의 줄바꿈이 기록될 때까지 기다립니다.
97
+ macOS arm64에서 빌드와 예시를 확인했습니다. Linux와 Windows 빌드는 아직 실행하지 않았습니다. follow는 플랫폼 파일 ID를 비교하고 파일 크기가 줄어든 것을 확인하면 위치를 초기화합니다. 성능 측정은 macOS arm64에서만 했으며, Linux와 Windows의 follow 동작은 실행하지 않았습니다. 필터는 올바른 JSON 행이 필요합니다. follow는 각 행의 줄바꿈이 기록될 때까지 기다립니다. `--max-bytes`(기본 64 MiB)를 넘는 행은 무제한으로 버퍼링하지 않고 건너뛴 뒤 `stderr` 경고(Python에서는 `RuntimeWarning` 및 메타데이터)로 알립니다.
98
+
99
+ ## 기여
100
+
101
+ 이슈와 풀 리퀘스트를 환영합니다. 빌드, 픽스처 확인, 리뷰 방식은 [CONTRIBUTING.md](CONTRIBUTING.md)에 있습니다.
79
102
 
80
103
  ## 라이선스
81
104
 
82
- MIT. 자세한 내용은 [LICENSE](LICENSE)를 참조하세요.
105
+ MIT입니다. [LICENSE](LICENSE)를 보세요.
@@ -1,12 +1,29 @@
1
+ <div align="center">
2
+
3
+ <img src="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/logo.svg" width="96" height="96" alt="jlogtail: the last lines of a file, measured from the end">
4
+
1
5
  # jlogtail
2
6
  [한국어](README.ko.md)
3
7
 
4
8
  A Rust command-line tool and Python module that read the end of large JSON Lines transcripts without loading the whole file.
5
9
 
10
+ Rust · Python 3.9+
11
+
12
+ [![pypi](https://img.shields.io/pypi/v/jlogtail?label=pypi)](https://pypi.org/project/jlogtail/)
13
+ [![license](https://img.shields.io/github/license/elfenomenokim/jlogtail)](https://github.com/elfenomenokim/jlogtail/blob/main/LICENSE)
14
+
15
+ 5.0 ms for the tail of a 2.18 GB transcript, against 66.5 ms for `tail | jq` and 1395.6 ms for a full Python read, from the saved 10-run file.
16
+
17
+ [Install](#install) · [Quick start](#quick-start) · [How it reads](#how-it-reads)
18
+
19
+ </div>
20
+
21
+ <p align="center">
6
22
  <picture>
7
23
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/demo/dark.gif">
8
24
  <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">
9
25
  </picture>
26
+ </p>
10
27
 
11
28
  [Social preview](https://raw.githubusercontent.com/elfenomenokim/jlogtail/main/docs/social.png)
12
29
 
@@ -31,7 +48,7 @@ jlogtail transcript.jsonl --filter payload.role=assistant --fields timestamp,pay
31
48
  jlogtail transcript.jsonl --follow
32
49
  ```
33
50
 
34
- 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. A row that is already unfinished when follow starts is kept from its first byte, so the first poll emits the whole row rather than a fragment.
51
+ 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. Every read path—initial `read_tail`, appended `--follow` reads, and incomplete trailing-record buffering—enforces `--max-bytes` (default 64 MiB). When a record exceeds `--max-bytes`, `jlogtail` skips it and prints a marker to `stderr` instead of growing an unbounded buffer. A row that is already unfinished when follow starts is kept from its first byte when within `--max-bytes`, so the first poll emits the whole row rather than a fragment.
35
52
 
36
53
  ```console
37
54
  $ jlogtail docs/demo/agents.jsonl --lines 2 --fields role,text
@@ -69,13 +86,19 @@ On M5 Pro, macOS arm64, hyperfine ran 3 warmups and 10 measured runs per command
69
86
  | `--filter PATH=VALUE` | Keep rows whose dotted key path equals the JSON value |
70
87
  | `--fields PATH,...` | Emit only the selected dotted paths as a compact object |
71
88
  | `--poll-ms N` | Follow poll interval; default 250 ms |
89
+ | `--max-bytes N` | Memory ceiling in bytes for `read_tail`, follow reads, and pending incomplete records; default 67108864 (64 MiB) |
72
90
  | `--keep-partial-first` | Keep the first partial row in a byte window |
91
+ | `--version`, `-V` | Print the `jlogtail` version and exit |
73
92
 
74
- 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.
93
+ The Python module provides `jlogtail.tail(path, lines=10, byte_window=None, max_bytes=jlogtail.DEFAULT_MAX_BYTES, keep_partial_first=False)` for raw complete rows (emitting a `RuntimeWarning` if a record is skipped or the window hits `max_bytes`). `jlogtail.tail_window(...)` returns `(meta, rows)` with `end_offset`, `max_bytes`, `skipped_oversized`, `ceiling_reached`, and `trailing_oversized`. `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.
75
94
 
76
95
  ## Limits
77
96
 
78
- 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.
97
+ 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. Records larger than `--max-bytes` (default 64 MiB) are skipped with a clear `stderr` marker (or Python `RuntimeWarning` and metadata count) rather than buffering past the ceiling.
98
+
99
+ ## Contributing
100
+
101
+ Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the build, the fixture check and the review process.
79
102
 
80
103
  ## License
81
104
 
@@ -0,0 +1,43 @@
1
+ # Security policy
2
+
3
+ ## Supported versions
4
+
5
+ Security fixes go into the latest release. Upgrade before reporting, in case the problem is
6
+ already fixed.
7
+
8
+ | Version | Supported |
9
+ | --- | --- |
10
+ | 0.2.0 | Yes |
11
+ | Older | No |
12
+
13
+ ## Reporting a vulnerability
14
+
15
+ Report it privately, not in a public issue: use the
16
+ [Report a vulnerability](https://github.com/elfenomenokim/jlogtail/security/advisories/new) form on
17
+ the repository's Security tab.
18
+
19
+ Include the command, the version (`jlogtail --version`), your platform, and what an attacker could
20
+ do with the result. You get a reply within a few days. Say how you want to be credited if you want a
21
+ name in the release note.
22
+
23
+ ## In scope
24
+
25
+ - Reading bytes outside the requested file and offset, including through a symlink, a rotation or a
26
+ relative path that resolves somewhere unexpected.
27
+ - Emitting a record that another process appended later, or data from a file the caller did not
28
+ name.
29
+ - Memory that grows with the file rather than with the requested window, so a large transcript can
30
+ exhaust the process.
31
+ - `--follow` resuming at an offset that skips or repeats a record after a rotation.
32
+
33
+ ## Not a vulnerability
34
+
35
+ - Content of the transcript reaching your own terminal or your own pipeline. The tool prints the
36
+ records you asked for.
37
+ - A filter that returns nothing, or a byte window that starts mid-record and skips that row.
38
+ - Reading a file your user account can already read.
39
+
40
+ ## Disclosure
41
+
42
+ Once a fix is released, the advisory is published with credit to the reporter unless they prefer
43
+ otherwise.
Binary file
Binary file
@@ -0,0 +1,7 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" width="96" height="96" role="img" aria-label="jlogtail: the last lines of a file, measured from the end">
2
+ <rect width="96" height="96" rx="20" fill="#ECEBFB"/>
3
+ <g fill="none" stroke="#4338CA" stroke-width="6" stroke-linecap="round" stroke-linejoin="round">
4
+ <path d="M22 30h34M22 46h34M22 62h22"/>
5
+ <path d="M66 26v44M66 26h8M66 70h8"/>
6
+ </g>
7
+ </svg>