TECHDEV · Công cụ open-source

logtrim

Build log của bạn dài 40.000 dòng. Cửa sổ ngữ cảnh của agent thì không. logtrim nằm trong một pipe và thu gọn log dài dòng cùng output công cụ xuống theo ngân sách token — giữ phần đầu, phần cuối và mọi dòng lỗi, đồng thời gom phần lặp lại ở giữa thành các marker một dòng ghi rõ đã bỏ gì. Không phụ thuộc thư viện, Node.js thuần, chạy trên stdin hoặc file.

Xem trên GitHub →Đọc bài viết →

Node.js 18+ · Không phụ thuộc thư viện · MIT

Trước / sau

File examples/sample.log đi kèm là một build log 62 dòng (ước tính 715 token) đầy spam tiến trình, cảnh báo lặp lại và một lỗi thật:

node bin/logtrim.js examples/sample.log --stats --budget 300

Starting build: my-app@1.4.2 (node v24.20.0)
Resolving dependencies...
Installing 184 packages...
Compiling module 1/184: utils
Compiling module 2/184: config
... [10 similar lines omitted] ...
warning: unused variable 'tmp' in src/reports.js:42
warning: unused variable 'tmp' in src/reports.js:42
... [6 identical lines omitted] ...
✗ billing: 3 failing
Error: Cannot find module './currency' in /app/src/billing/rates.js
    at Module._resolveFilename (node:internal/modules/cjs/loader:1140:15)
    ...
ERROR: upload failed after 3 attempts: connection reset by peer
Build finished with errors (exit code 1)

Kết quả: 62 → 23 dòng, 715 → 251 token, bỏ 41 dòng — và cả hai lỗi, stack trace cùng phần đầu log đều còn nguyên. Với ngân sách mặc định (2000 token), cùng file đó còn 48 dòng / 559 token, chỉ bỏ các phần lặp đã gom. Output đầy đủ nằm ở examples/trimmed-example.txt.

Log mẫu và output rút gọn sao chép y nguyên từ README của logtrim ("Before / after").

Bắt đầu nhanh

# cần Node.js 18+
git clone https://github.com/techdevfun/logtrim.git
cd logtrim
npm link   # logtrim dùng được ở mọi nơi

# hoặc chạy mà không cần cài
node bin/logtrim.js --help

# rút gọn một build lỗi trước khi dán cho agent
npm run build 2>&1 | logtrim --budget 1500

# rút gọn một file log đã lưu, xem đã cắt gì
logtrim --budget 800 --stats deploy.log

# từ stdin, rõ ràng
cat deploy.log | logtrim --budget 800

Các lệnh sao chép y nguyên từ README của logtrim ("Install" + "Usage"). Mã thoát: 0 ok · 1 file input không tồn tại / không đọc được · 2 tham số sai.

Tùy chọn

Tùy chọn	Mặc định	Tác dụng
`--budget N`	2000	Ngân sách token cho output (ước tính ~1 token = 4 ký tự)
`--head N`	40	Số dòng luôn giữ ở đầu
`--tail N`	60	Số dòng luôn giữ ở cuối
`--max-line N`	500	Cắt các dòng dài hơn N ký tự, kèm ghi chú
`--no-errors`	tắt	Không ưu tiên dòng lỗi khi vượt ngân sách
`--no-dedupe`	tắt	Không gom các dòng lặp / tương tự
`--stats`	tắt	In JSON `{inputLines, outputLines, inputTokens, outputTokens, omittedLines}` ra stderr
`--help`, `--version`		Hiện trợ giúp / phiên bản

Bảng tùy chọn sao chép y nguyên từ README của logtrim ("Usage").

Cách rút gọn

Gom các cụm dòng trống — 5 dòng trống thành 1.
Gom các cụm dòng giống hệt — 8 bản sao của cùng một cảnh báo thành 2 bản cộng ... [6 identical lines omitted] ....
Gom các cụm dòng tương tự — 12 dòng Processed N/1000 records thành 2 cộng ... [10 similar lines omitted] .... "Tương tự" nghĩa là cùng cấu trúc, chỉ khác số. Dòng lỗi không bao giờ bị gom kiểu này.
Cắt các dòng dài phi lý — một blob JSON một dòng 3 KB bị cắt còn --max-line ký tự kèm ghi chú [truncated, N chars].
Nếu vẫn vượt ngân sách — giữ đầu + dòng lỗi + cuối, bỏ phần giữa, đánh dấu mỗi khoảng trống bằng ... [N lines omitted to fit B-token budget] .... Dòng ở giữa bị bỏ trước để đầu và cuối còn nguyên.
Biện pháp cuối — nếu riêng các dòng lỗi đã vượt ngân sách, chúng được cắt bớt để chia nhau ngân sách. Output không bao giờ vượt ngân sách.

Các bước từ README của logtrim ("How trimming works"), diễn giải lại.

Sao không dùng `head` / `tail`?

head -100 cắt mất lỗi ở cuối. tail -100 cắt mất ngữ cảnh ở đầu. grep -i error cắt mất mọi thứ giải thích vì sao lỗi xảy ra. logtrim giữ cả ba: phần dựng, phần lỗi và phần sau lỗi — và cho bạn biết chính xác đã bỏ bao nhiêu.

Từ README của logtrim ("Why not just head / tail?").

Giới hạn

Số token chỉ là ước tính (số ký tự / 4). Đủ chính xác để quyết định giữ gì, và giữ công cụ không phụ thuộc thư viện. Nếu cần đếm chính xác theo tokenizer, hãy pipe qua một tokenizer thật trước rồi truyền kết quả vào --budget.
Việc gom dòng "tương tự" dựa trên hình dạng (cùng dòng chỉ khác số) — các dòng thật sự khác nhau nhưng trông giống nhau có thể bị gom chung.
Rút gọn là phá hủy dữ liệu: phần giữa bị bỏ sẽ mất hẳn trừ khi chạy lại với ngân sách lớn hơn. Luôn giữ log gốc nếu cần audit trail đầy đủ.

Giới hạn từ chính các ghi chú trong README của logtrim.

Lộ trình — chưa phát hành

--format json passthrough: giữ nguyên các dòng log JSON thay vì cắt giữa object
--keep PATTERN: regex do người dùng cung cấp cho các dòng bắt buộc phải giữ
--watch: theo dõi file log đang lớn dần và rút gọn lại khi thay đổi

Lộ trình sao chép từ README của logtrim; cả ba mục vẫn đang mở ở upstream.

Giấy phép

MIT — xem LICENSE trong repository.

Công cụ liên quan

Các công cụ mã nguồn mở khác của TECHDEV: sessguard, runverdict, gheist-guard, vetgate, context-diet, ci-failure-detective, agent-seatbelt, devsecops-os, env-doctor, skill-audit, testguard, breakcheck, keymap, memgraph, ggufit, leaseguard, factfence, jsonfold

Đóng góp ý kiến

Bình chọn cho công cụ này, đề xuất tính năng, hoặc thảo luận với các vận hành khác trên bảng cộng đồng.