Tài liệu tham khảo LogBrew CLI: lệnh và bộ lọc

LogBrew CLI mã nguồn mở đọc telemetry và quản lý dữ liệu tài khoản từ terminal. Để cài đặt, đăng nhập và làm các tác vụ thường gặp, bắt đầu với trang Dùng CLI.

Cách CLI hoạt động

Dùng văn bản dễ đọc trong terminal. Dùng --json trong script và agent lập trình. Cần đăng nhập tài khoản để đọc dữ liệu tài khoản. Trước khi bắt đầu đăng nhập, chạy logbrew status --json. Một người phải tự hoàn tất bước cấp quyền trên trình duyệt. Khóa gửi dữ liệu của dự án dùng để gửi telemetry. Khóa này không thay thế được đăng nhập tài khoản. Tạo dự án, tạo khóa, thay đổi trạng thái, mức ưu tiên và người phụ trách của vấn đề, triển khai và cập nhật yêu cầu hỗ trợ đều thay đổi dữ liệu tài khoản. Trước khi chạy một lệnh như vậy, kiểm tra thao tác và đối tượng đích đều đúng. Chạy logbrew --help để xem mọi lệnh. Thêm --help vào một lệnh, như logbrew read logs --help, để xem các flag của lệnh đó. Chạy logbrew help json để xem quy tắc JSON.

Nhóm lệnh	Mục đích
`login`, `whoami`, `me`, `logout`	Bắt đầu đăng nhập, đọc danh tính tài khoản hoặc đóng phiên cục bộ.
`status`, `health`, `doctor`, `version`, `examples`	Đọc quyền truy cập, mức sẵn sàng của dự án, phiên bản CLI hoặc ví dụ cho lần chạy đầu.
`setup`	Đọc manifest cục bộ và in kế hoạch thiết lập SDK. Lệnh này không thay đổi tệp và không chạy lệnh cài đặt.
`projects`	Đọc danh mục dự án đang hoạt động.
`projects repositories`	Đọc các repository đã kết nối hoặc tìm thành phần trong một repository.
`projects create`, `projects keys create`	Tạo dự án, hoặc tạo khóa gửi dữ liệu cho một dự án có sẵn.
`projects setup`	Ghi lại thiết lập đã quan sát cho một dự án có sẵn.
`projects archive`, `projects delete`	Lưu trữ một dự án, hoặc xóa vĩnh viễn dự án sau khi xác nhận.
`usage`, `account usage`	Đọc mức sử dụng, giới hạn, trạng thái hạn mức và ngày đặt lại.
`mcp grants`, `mcp revoke`	Liệt kê theo tên các MCP client đã kết nối với tài khoản, hoặc thu hồi một kết nối.
`read`	Đọc log, vấn đề, hành động, bản phát hành, chỉ số, trace hoặc một mục.
`explain`	Đọc bằng chứng có giới hạn cho một vấn đề, log, hành động, trace, span, chỉ số hoặc bản phát hành.
`investigate issue`	Đọc bằng chứng điều tra vấn đề, hoặc xác minh một lần triển khai ứng viên.
`issues archive`, `issues resolve`, `issues reopen`	Đặt trạng thái cho 1 vấn đề, hoặc cho tối đa 100 vấn đề trong một dự án.
`issues priority`	Đặt mức ưu tiên cho 1 vấn đề, hoặc cho tối đa 100 vấn đề trong một dự án.
`issues assign`, `issues unassign`	Đặt hoặc bỏ người phụ trách (một tài khoản hoặc một nhóm) cho 1 vấn đề, hoặc cho tối đa 100 vấn đề trong một dự án.
`issues assignees`	Liệt kê các tài khoản và nhóm có thể được giao vấn đề trong một dự án.
`issues owners`	Liệt kê các chủ sở hữu được đề xuất của 1 vấn đề.
`issues ownership`	Đọc hoặc đặt quy tắc sở hữu và tệp CODEOWNERS của một dự án.
`issues activity`	Đọc lịch sử thay đổi của 1 vấn đề.
`issues rule`, `logs rule`	Đặt quy tắc mức độ nghiêm trọng cho 1 vấn đề hoặc 1 chữ ký log.
`inbox`	Đọc các vấn đề mà người khác đã giao cho bạn hoặc nhóm của bạn, hoặc đánh dấu chúng là đã đọc.
`set issue`, `resolve`, `close`, `ignore`, `reopen`	Đặt trạng thái cho 1 vấn đề. `close` nghĩa là `resolved`. `ignore` và `ignored` nghĩa là `archived`.
`deploy`	Ghi lại một lần triển khai đã hoàn tất.
`debug-artifacts`	Tải lên tệp gỡ lỗi native của Apple hoặc Android, hoặc tra cứu một định danh image.
`analytics`	Đọc tổng quan, thuộc tính, so sánh, đường dẫn, phễu, tỷ lệ quay lại hoặc vòng đời.
`support`	Tạo, đọc, trả lời, đóng hoặc mở lại yêu cầu hỗ trợ.
`watch`	Xem luồng trực tiếp của log, vấn đề hoặc hành động.

Đọc báo cáo doctor của dự án

Dùng ID dự án lấy từ logbrew projects --json:

logbrew doctor --project "<project_id>" --json

Lệnh này đọc trạng thái dự án và một log gần đây. Lệnh không tạo dự án, không thay đổi khóa và không ghi lại thiết lập. Báo cáo có status, checks và next. Mỗi mục kiểm tra có check, status và next. Các mục kiểm tra là api, auth, project, ingest_key, setup, telemetry và logs. Mã thoát 0 nghĩa là CLI đã ghi báo cáo. Mã này không có nghĩa là dự án đã sẵn sàng. Đọc status của báo cáo và từng mục kiểm tra. Mục kiểm tra not_checked là chưa đạt.

`status` của báo cáo	Ý nghĩa và bước tiếp theo
`auth_invalid`	Thiếu quyền truy cập tài khoản hoặc quyền này không hợp lệ. Một người tự chạy `logbrew login`.
`project_missing`	Tài khoản này không truy cập được dự án. Dùng ID từ `logbrew projects --json`.
`api_unreachable`	Yêu cầu API chưa hoàn tất. Kiểm tra kết nối mạng, rồi chạy lại lệnh.
`check_failed`	Một yêu cầu thất bại hoặc phản hồi không hợp lệ. Chạy lại lệnh mà không thay đổi gì. Nếu vẫn thất bại, báo cáo sự cố.
`needs_ingest_key`	Dự án không có khóa gửi dữ liệu đang hoạt động. Chỉ tạo khóa khi bạn có quyền thay đổi dự án.
`needs_setup`	Cần thiết lập SDK. Làm theo hướng dẫn Bắt đầu nhanh.
`needs_telemetry`	Thiết lập đã bắt đầu, nhưng LogBrew chưa có telemetry cho dự án. Gửi một sự kiện thử nghiệm.
`ready`	Dự án có khóa đang hoạt động và có telemetry. Đọc tín hiệu phù hợp với tác vụ của bạn.

Khi đọc dự án thành công, mục kiểm tra logs là visible, empty, unavailable, error hoặc invalid_response. Mục kiểm tra này không thay đổi status của báo cáo. Kết quả log trống không cho biết gì về các tín hiệu khác. Lần đọc thất bại không phải là kết quả trống. Dùng next làm hướng dẫn khôi phục. Giá trị này không cấp quyền thay đổi trạng thái tài khoản hoặc dự án.

Ví dụ: thiếu quyền truy cập tài khoản

Khi không có thông tin xác thực tài khoản, lệnh không gửi yêu cầu API nào. Lệnh ghi báo cáo này ra standard output và thoát với mã 0:

{
  "checks": [
    { "check": "api", "next": "run the API reachability check first", "status": "not_checked" },
    { "check": "auth", "next": "run logbrew login", "status": "missing" },
    { "check": "project", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "ingest_key", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "setup", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "telemetry", "next": "resolve the prior check first", "status": "not_checked" },
    { "check": "logs", "next": "resolve the prior check first", "status": "not_checked" }
  ],
  "next": "run logbrew login",
  "status": "auth_invalid"
}

Báo cáo này khác với kết quả chẩn đoán dự án qua API. Báo cáo không chứa các trường API state, setup_status hoặc next_action.

Bộ lọc

Bộ lọc	Lệnh
`--project <project_id>`	logs, issues, actions, releases, metrics, traces, trace
`--release <release>`	logs, issues, actions, releases, metrics, traces, trace
`--environment <environment>`	logs, issues, actions, releases, metrics, traces, trace
`--service <service_name>`	logs, issues, actions, releases, metrics, traces
`--since 24h`	logs, issues, actions, releases, metrics, traces, analytics
`--until <RFC3339>`	logs, issues, actions, releases, metrics, traces, analytics
`--limit 100`	logs, issues, actions, releases, metrics, traces
`--severity error`	logs, watch
`--search checkout`	logs
`--trace <trace_id>`	logs
`--status unresolved`	issues (`unresolved`, `resolved`, `archived`)
`--priority high`	issues (`high`, `medium`, `low`)
`--assignee me`	issues (`me`, `none`, `my_teams`, ID người dùng hoặc `team:<team_id>`)
`--status error`	traces (`error`, `ok`)
`--min-duration-ms <milliseconds>`	traces
`--name <name>`	actions, metrics
`--user <distinct_id>`	actions

--since nhận thời lượng như 24h hoặc 7d, hoặc dấu thời gian RFC 3339. --until nhận dấu thời gian RFC 3339. Thời điểm này không thuộc khoảng thời gian và phải muộn hơn --since. Lệnh đọc một vấn đề theo ID không nhận --until. Mức độ nghiêm trọng của log là info, warning, error hoặc critical. Trạng thái vấn đề là trạng thái trong quy trình xử lý vấn đề, không phải mức độ nghiêm trọng. --status ignored là tên cũ của --status archived. --status open nghĩa là unresolved, và --status closed nghĩa là resolved. --assignee none chọn các vấn đề chưa có người phụ trách, còn --assignee my_teams chọn các vấn đề của những nhóm bạn tham gia. Mọi giá trị --assignee khác đều thất bại với invalid_assignee. CLI cũng nhận các bí danh sau: --project-id, --env, --service-name, --trace-id, --distinct-id, và --level cho --severity. Dùng các tên trong bảng cho script mới. Lệnh này đọc các lỗi trong 1 ngày:

logbrew read logs --severity error \
  --since 2026-10-01T00:00:00Z --until 2026-10-02T00:00:00Z --json

ID dự án chọn dự án. Tên dịch vụ chọn một thành phần trong dự án đó. Đặt giá trị có khoảng trắng trong dấu ngoặc kép:

logbrew read logs --project "<project_id>" \
  --service checkout-api --since 24h \
  --severity error --search "checkout failed" --json

Với văn bản tìm kiếm bắt đầu bằng dấu gạch ngang, đặt -- trước văn bản:

logbrew logs --json -- --timeout

Chọn một lần xảy ra của vấn đề

Một vấn đề gộp nhóm các lần xảy ra khớp nhau. Đọc vấn đề để biết trạng thái, số lần xảy ra, thời điểm lần đầu xuất hiện và lần cuối xuất hiện:

logbrew read issue "<issue_id>" --json

Dùng explain issue hoặc investigate issue để lấy bằng chứng từ một lần xảy ra. Nếu không có --occurrence, LogBrew chọn lần xảy ra được đề xuất. Lần này không phải lúc nào cũng là sự kiện mới nhất. Để đọc sự kiện mới nhất:

logbrew explain issue "<issue_id>" --occurrence latest --json

--occurrence cũng nhận recommended, first hoặc ID lần xảy ra mà LogBrew đã trả về. Các lệnh này từ chối bộ lọc dự án, bản phát hành, môi trường và thời gian. Trước khi so sánh bằng chứng, đọc dấu thời gian của lần xảy ra đã chọn. Xem Điều tra một vấn đề để biết các trường bằng chứng.

Thay đổi trạng thái và mức ưu tiên của vấn đề

Dùng 1 ID vấn đề để thay đổi 1 vấn đề:

logbrew issues archive "<issue_id>" --json
logbrew issues priority high "<issue_id>" --json

archive đặt archived, resolve đặt resolved, và reopen đặt unresolved. Mức ưu tiên là high, medium hoặc low. Mức ưu tiên do bạn đặt sẽ giữ cố định. Nếu không đặt, mức ưu tiên theo mức độ nghiêm trọng của vấn đề. Để thay đổi nhiều hơn 1 vấn đề, thêm --project. Mọi vấn đề phải thuộc dự án đó. Một lệnh thay đổi được tối đa 100 vấn đề:

logbrew issues resolve "<issue_id_1>" "<issue_id_2>" \
  --project "<project_id>" --json

Kết quả có 1 mục cho mỗi vấn đề. Mỗi mục là updated, unchanged hoặc not_found. Vấn đề unchanged đã có sẵn giá trị được yêu cầu. Bạn có thể chạy lại cùng lệnh sau khi gặp lỗi mạng. Các lệnh này không hỏi xác nhận. Kiểm tra ID vấn đề trước. Khi đọc và thay đổi vấn đề, kết quả hiển thị archived thay vì ignored, cùng priority, priority_source và assignee của từng vấn đề. Xem phản hồi vấn đề.

Giao vấn đề

Một vấn đề có 0 hoặc 1 người phụ trách: một tài khoản hoặc một nhóm. Liệt kê các tài khoản và nhóm mà bạn có thể giao trong một dự án:

logbrew issues assignees --project "<project_id>" --json

Giao 1 vấn đề cho một tài khoản, cho chính bạn bằng me, hoặc cho một nhóm:

logbrew issues assign "<user_id>" "<issue_id>" --json
logbrew issues assign me "<issue_id>" --json
logbrew issues assign "team:<team_id>" "<issue_id>" --json

Bỏ người phụ trách:

logbrew issues unassign "<issue_id>" --json

Thêm --project để thay đổi tối đa 100 vấn đề của dự án đó, giống như với trạng thái và mức ưu tiên. Tài khoản phải có quyền đọc dự án, còn nhóm phải thuộc tổ chức của dự án. Để tìm các vấn đề được giao cho bạn hoặc cho nhóm của bạn:

logbrew read issues --project "<project_id>" --assignee my_teams \
  --status unresolved --json

Đầu ra dạng văn bản hiển thị tên người phụ trách, hoặc team #<slug> nếu đó là một nhóm. Nếu tài khoản không có tên, đầu ra hiển thị địa chỉ email, rồi đến ID người dùng. Vấn đề chưa có người phụ trách hiển thị unassigned.

Chủ sở hữu, lịch sử và hộp thư đến

logbrew issues owners "<issue_id>" --json
logbrew issues ownership --project "<project_id>" --json
logbrew issues ownership set --project "<project_id>" \
  --rules ownership.txt --codeowners .github/CODEOWNERS --json
logbrew issues activity "<issue_id>" --limit 50 --json
logbrew inbox --json
logbrew inbox read --json

issues owners liệt kê các chủ sở hữu được đề xuất và bằng chứng mà lệnh đã kiểm tra. issues ownership set gửi các tệp cục bộ, mỗi tệp tối đa 128 KiB. Gửi tệp trống để xóa nội dung đã lưu của tệp đó. issues activity và inbox nhận --limit từ 1 đến 200, cùng --cursor-time và --cursor-id lấy từ next_cursor. Xem Tìm chủ sở hữu của vấn đề.

Đặt quy tắc mức độ nghiêm trọng

logbrew issues rule "<issue_id>" warning --json
logbrew logs rule "<log_id>" info --ignore --json

Mức độ nghiêm trọng là info, warning, error, critical hoặc source. source hiển thị lại mức độ nghiêm trọng đã ghi nhận. --ignore ẩn các log khớp khỏi danh sách log mặc định. Khi không có --ignore, quy tắc vẫn hiển thị các log đó.

Đọc trang tiếp theo

Log, vấn đề, hành động, chỉ số và trace hỗ trợ phân trang bằng cursor. Bản phát hành thì không. Dùng --pagination cursor cho trang đầu tiên:

logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 --json

Phản hồi có logs và next_cursor. next_cursor khác null có time và id. Gửi hai giá trị này bằng --cursor-time và --cursor-id:

logbrew read logs --project "<project_id>" --since 24h \
  --pagination cursor --limit 100 \
  --cursor-time "<returned_time>" \
  --cursor-id "<returned_id>" --json

Giữ nguyên bộ lọc và giới hạn trên mọi trang. Dừng khi next_cursor là null. Dùng cursor, không dùng số dòng, để quyết định còn trang nữa hay không. Trang cuối có thể trống:

{
  "logs": [],
  "next_cursor": null
}

Vấn đề, hành động và chỉ số dùng cùng cấu trúc, với issues, actions hoặc metrics thay cho logs.

Theo dõi trực tiếp

logbrew watch --json truyền trực tiếp log, vấn đề và hành động. Thêm logs, issues hoặc actions để chỉ truyền một loại. tail, follow và stream là bí danh của watch. Watch không hỗ trợ trace hoặc span. Watch cần --json. Nếu thiếu, lệnh ghi watch streams JSON for agents và thoát với mã 1. Sự kiện vấn đề trong watch hiển thị vấn đề đã lưu trữ là ignored, không kèm mức ưu tiên. Đọc vấn đề để lấy trạng thái và mức ưu tiên hiện tại. Watch chỉ nhận --severity, như --severity error,critical. logbrew watch actions không nhận --severity. CLI áp dụng bộ lọc này sau khi nhận sự kiện. Bộ lọc không làm giảm lượng dữ liệu máy chủ gửi. Watch không có bộ lọc dự án, bản phát hành, môi trường hoặc thời gian. Để dùng các bộ lọc đó, dùng lệnh read. Sau khi mất kết nối tạm thời, CLI chờ rồi kết nối lại.

Đọc kết quả và lỗi

Đặt --json trước hoặc sau lệnh. Đọc mã thoát trước khi dùng đầu ra. Không phân tích cú pháp đầu ra dành cho người đọc. Đầu ra này có thể thay đổi giữa các phiên bản.

Mã thoát	Ý nghĩa
`0`	Thành công. JSON nằm trên standard output.
`1`	Lệnh thất bại khi đang chạy, ví dụ do lỗi API hoặc lỗi mạng.
`2`	CLI từ chối lệnh trước khi chạy.

Đầu ra thành công giữ nguyên cấu trúc phản hồi của API. Đầu ra có thể là mảng hoặc đối tượng. Khi không dùng phân trang bằng cursor, lệnh đọc log trả về một mảng. Mảng trống nghĩa là không có log nào khớp. Đây không phải là lỗi. Lỗi được ghi ra standard error. Ngoại lệ là debug-artifacts --json: lệnh này ghi lỗi ra standard output. Lỗi JSON có ok, error, message và next. Dùng error làm mã lỗi ổn định. Xem xét next trước khi chạy lệnh mà nó gợi ý. Ví dụ, logbrew watch traces --json thoát với mã 2 và ghi:

{
  "ok": false,
  "error": "unknown_resource",
  "message": "unknown resource: traces",
  "next": "use logbrew traces for recent traces, or logbrew trace <trace_id> for one trace"
}

logbrew read logs --limit 0 --json thoát với mã 2 và ghi:

{
  "ok": false,
  "error": "invalid_limit",
  "message": "invalid limit: 0",
  "next": "use --limit with a positive whole number"
}

Sửa giá trị và chạy lại lệnh. Lệnh bị từ chối không phải là kết quả trống. Xem Lỗi API cho lỗi HTTP và Telemetry API cho yêu cầu API trực tiếp.

​Cách CLI hoạt động

​Đọc báo cáo doctor của dự án

​Ví dụ: thiếu quyền truy cập tài khoản

​Bộ lọc

​Chọn một lần xảy ra của vấn đề

​Thay đổi trạng thái và mức ưu tiên của vấn đề

​Giao vấn đề

​Chủ sở hữu, lịch sử và hộp thư đến

​Đặt quy tắc mức độ nghiêm trọng

​Đọc trang tiếp theo

​Theo dõi trực tiếp

​Đọc kết quả và lỗi