Skip to main content
Mỗi route đọc nhận một bộ tham số truy vấn riêng. Route trong bảng bộ lọc từ chối tham số không xác định hoặc giá trị sai kiểu bằng 422 và validation_failed, trừ khi bảng có ghi chú khác. Các bí danh thân thiện như project, trace và user không phải là tham số truy vấn. Không chuyển bộ lọc của route này sang route khác.

Tạo yêu cầu có bộ lọc

Đặt query string sau đường dẫn. Dùng --data-urlencode để các ký tự đặc biệt được mã hóa an toàn. Yêu cầu này đọc các log critical của một dự án trong 24 giờ qua:
Thêm bộ lọc theo thứ tự sau:
  1. Chọn dự án bằng project_id hoặc project_ids.
  2. Thêm khoảng thời gian bằng since, và until nếu cần.
  3. Thêm bộ lọc dịch vụ, bản phát hành, môi trường, trạng thái hoặc bộ lọc riêng của từng tín hiệu.
  4. Đặt limit để có trang nhỏ hơn.
  5. Chỉ thêm các trường cursor sau khi một phản hồi cursor trả về chúng.
Mỗi dòng được trả về đều khớp với mọi bộ lọc trong yêu cầu. Bộ lọc không được gửi sẽ dùng giá trị mặc định của route. Ví dụ, GET /api/logs dùng status=active khi bạn không gửi status.

Bảng bộ lọc

Các tham số trong cột “Bắt buộc” phải có trong yêu cầu. Mọi tham số khác là tùy chọn. Với điều tra vấn đề, selection là first, latest hoặc recommended. Gửi selection hoặc occurrence_id, không gửi cả hai. Cả hai đều cần response_version từ 2 đến 13. Với phiên bản 2 trở lên và không có tham số chọn, LogBrew dùng recommended. Lấy occurrence_id từ GET /api/telemetry/issues/{issue_id}/events. Các route phân tích dùng POST nhận body JSON. Xem Phân tích sản phẩm.

Bộ lọc dùng chung và bộ lọc riêng của tín hiệu

service_name, release và environment thu hẹp mọi danh sách telemetry. Dùng đúng các giá trị mà SDK của bạn gửi. Một số bộ lọc chỉ thuộc về một loại tín hiệu:
  • Log nhận search, trace_id, severity và attribute_filters.
  • Log nhận status: active (mặc định), ignored hoặc all. ignored chọn các log mà một quy tắc log ẩn khỏi danh sách đang hoạt động.
  • Vấn đề nhận status của vấn đề: unresolved, resolved hoặc archived. ignored là tên cũ của archived và chọn cùng các vấn đề.
  • Vấn đề nhận severity: info, warning, error hoặc critical.
  • Vấn đề nhận priority: high, medium hoặc low.
  • Vấn đề nhận assignee: me cho các vấn đề được giao cho tài khoản đang đăng nhập, none cho các vấn đề chưa có người phụ trách, my_teams cho các vấn đề của nhóm bạn, một user ID, hoặc team:<team_id>.
  • Hành động và chỉ số nhận name.
  • Hành động nhận distinct_id.
  • Trace nhận status của trace và min_duration_ms.
  • Danh sách triển khai nhận status: succeeded hoặc failed.
Bộ lọc severity của log và vấn đề so sánh mức độ nghiêm trọng hiệu lực. Nếu một quy tắc đã đổi mức độ nghiêm trọng, bộ lọc dùng giá trị theo quy tắc. Xem Giá trị mức độ nghiêm trọng.

Khoảng thời gian

since nhận số giờ hoặc số ngày là số nguyên dương, chẳng hạn 24h hoặc 7d, hoặc một dấu thời gian RFC3339. Thời lượng dạng rút gọn được tính tương đối so với thời điểm của từng yêu cầu. until chỉ nhận dấu thời gian RFC3339. Đây là thời điểm kết thúc không bao gồm: dòng có thời điểm đúng bằng until không nằm trong kết quả. since thì bao gồm. Ví dụ, since=2026-10-01T00:00:00Z và until=2026-10-02T00:00:00Z chọn trọn 1 ngày. LogBrew so sánh thời gian đến từng mili giây. until phải muộn hơn since. Nếu không, hoặc nếu until không phải dấu thời gian RFC3339, yêu cầu thất bại với 422 và validation_failed. Khi đọc nhiều trang, chọn một thời điểm bắt đầu RFC3339 và giữ nguyên ở mọi trang. Cũng giữ nguyên until ở mọi trang. Yêu cầu này đọc các log lỗi trong 1 ngày:
Danh sách triển khai dùng quy tắc thời gian khác. since và until của danh sách này chỉ nhận dấu thời gian RFC3339, và cả hai đều bao gồm. Chúng được so sánh với thời điểm lần triển khai hoàn tất.

Phiên bản phản hồi của vấn đề

Danh sách vấn đề và chi tiết vấn đề nhận response_version=1, response_version=2, response_version=3 hoặc response_version=4. Phiên bản 1 là mặc định. Giá trị khác sẽ thất bại với 422 và validation_failed.
  • Phiên bản 1 hiển thị trạng thái đã lưu trữ là ignored. Phiên bản này không hiển thị mức ưu tiên.
  • Phiên bản 2 hiển thị trạng thái đã lưu trữ là archived. Phiên bản này thêm priority và priority_source.
  • Phiên bản 3 có mọi trường của phiên bản 2. Phiên bản này thêm assignee.
  • Phiên bản 4 có mọi trường của phiên bản 3. assignee có type: user hoặc team.
Mọi phiên bản đều nhận status=archived, priority và assignee. Xem phản hồi vấn đề.

Bộ lọc mức độ nghiêm trọng

Dùng severity=info|warning|error|critical với GET /api/logs. Tham số level cũ hơn là bí danh để tương thích. Cả hai tham số đều nhận các giá trị chuẩn và các bí danh trace, debug, warn và fatal. LogBrew đổi bí danh thành giá trị chuẩn trước khi so sánh. Nếu yêu cầu gửi cả severity và level, LogBrew chuẩn hóa cả hai trước. Các giá trị xung đột bị từ chối với thông điệp:

Bộ lọc trace

Khi khám phá trace, status là error hoặc ok. Bỏ tham số này để lấy cả hai. min_duration_ms phải lớn hơn hoặc bằng 0. Tham số này chỉ áp dụng khi khám phá trace. Yêu cầu này tìm các trace lỗi kéo dài ít nhất 500 mili giây:
Với chi tiết và tóm tắt trace, mã hóa phần trăm (percent-encode) trace_id để dùng làm một đoạn của đường dẫn. Không gửi nó dưới dạng tham số truy vấn.

Phạm vi dự án

Dùng project_id=<project-uuid> để đọc một dự án. Trên các route có project_ids trong bảng bộ lọc, dùng project_ids=<uuid>,<uuid> cho một tập chính xác gồm 2 đến 50 dự án. Trên các route đó, bỏ cả hai tham số để đọc mọi dự án mà tài khoản có quyền đọc. Route bắt buộc project_id chỉ nhận 1 dự án.
LogBrew từ chối các lựa chọn sau với 422 và validation_failed:
  • Yêu cầu có cả project_id và project_ids.
  • Giá trị project_ids có ít hơn 2 hoặc nhiều hơn 50 ID.
  • ID bị trùng hoặc ID không phải UUID.
Nếu một ID trong project_ids là dự án mà tài khoản không có quyền đọc, yêu cầu thất bại với 404 và not_found. Đừng bỏ ID đó rồi tiếp tục. Đề nghị người dùng chọn một tập dự án mới. Giữ nguyên phạm vi dự án ở mọi trang cursor. Đừng bỏ bộ lọc dự án sau khi nhận kết quả trống, vì làm vậy là đặt một câu hỏi khác.

Chuỗi theo khoảng gộp

GET /api/telemetry/metrics/series trả về một chỉ số theo các khoảng gộp thời gian. GET /api/telemetry/summary/volume trả về số lượng tín hiệu theo các khoảng gộp thời gian. Cả hai route dùng các quy tắc sau:
  • since là bắt buộc. until là tùy chọn và mặc định là thời điểm gửi yêu cầu.
  • Khoảng từ since đến until dài tối đa 31 ngày.
  • interval là auto, 1m, 5m, 15m, 1h, 6h hoặc 1d. Mặc định là auto. Giá trị interval tạo ra hơn 500 khoảng gộp sẽ thất bại.
  • service_name, release và environment là bộ lọc khớp chính xác.
Với chuỗi chỉ số, name là tên chỉ số chính xác lấy từ GET /api/telemetry/metrics. group_by là none, service_name, release hoặc environment. series_limit từ 1 đến 20. Với số lượng tín hiệu, until không được nằm ở tương lai, và response_version chỉ nhận 1.

Lọc thuộc tính log

Dùng GET /api/logs/attributes để tìm các đường dẫn thuộc tính và kiểu dữ liệu mà bạn có thể tìm kiếm. Sau đó gửi attribute_filters đến GET /api/logs. Cả hai yêu cầu đều cần since.

Đọc danh mục thuộc tính

Yêu cầu này tìm các đường dẫn kiểu số có chứa status trong một dự án:
Phản hồi là một đối tượng, không phải mảng trần. Ví dụ giả lập này có 2 thuộc tính và còn một trang nữa:
type là string, number hoặc boolean. observed_count là số log trong khoảng thời gian có đường dẫn và kiểu đó. last_seen_at là thời điểm của log mới nhất trong số đó. Một log có thể có nhiều đường dẫn. Đừng cộng các con số này để ra số log. coverage cho biết bộ lọc thuộc tính có thể tìm trong những log nào: Tổng của 3 nhóm này bằng total_logs. type, search và cursor của danh mục không làm thay đổi độ bao phủ. Danh sách attributes trống không có nghĩa là total_logs bằng 0. Danh mục không có tham số status. Bộ lọc mức độ nghiêm trọng của danh mục so sánh mức độ nghiêm trọng đã ghi nhận, không phải mức độ nghiêm trọng hiệu lực. search là chuỗi con của đường dẫn, dài từ 1 đến 128 byte và không chứa ký tự điều khiển. limit đặt số thuộc tính trên một trang.

Đọc tiếp danh mục

Danh mục không dùng pagination=cursor. Lặp lại mọi bộ lọc, và chép cả 3 trường từ next_cursor: Dừng khi next_cursor là null.

Áp dụng bộ lọc có kiểu

Chép đường dẫn và kiểu từ danh mục. Đường dẫn dùng cú pháp JSON Pointer, không dùng khóa nối bằng dấu chấm. Giữ nguyên mọi chuỗi thoát ~0 hoặc ~1 trong đường dẫn. Yêu cầu này đọc các log có trạng thái phản hồi dạng số từ 500 trở lên:
attribute_filters là một mảng JSON gồm 1 đến 4 bộ lọc. Log phải khớp với mọi bộ lọc. Mỗi bộ lọc có path, type, operator và value. Kiểu JSON của value phải khớp với type: số 500 không phải là chuỗi "500". ne chỉ khớp với các log có đường dẫn đó. Log không có đường dẫn đó không khớp với ne. Với string, case_sensitive là tùy chọn và mặc định là false. LogBrew từ chối "case_sensitive": true với number và boolean. Các giới hạn sau được áp dụng:
  • Mảng JSON dài tối đa 4.096 byte.
  • Giá trị chuỗi dài tối đa 1.024 byte.
  • contains và starts_with cần một chuỗi không rỗng.
  • Số phải hữu hạn và nằm trong khoảng từ -9.007.199.254.740.992 đến 9.007.199.254.740.992.
Log mà chỉ mục không tìm được sẽ không khớp với bộ lọc. Log đó vẫn có thể xuất hiện trong yêu cầu không có attribute_filters. Về phản hồi log, xem Phản hồi log.

Sửa lỗi thuộc tính

Mỗi lỗi dưới đây trả về 422 kèm validation_failed: Sửa yêu cầu trước khi thử lại. Đừng bỏ bộ lọc, vì làm vậy sẽ thay đổi kết quả.

Phân trang bằng cursor

Chế độ cursor phải được bật chủ động. Khi không bật, các route danh sách trả về mảng trần. Với trang đầu tiên, gửi pagination=cursor mà không kèm trường cursor. Với mỗi trang tiếp theo, lặp lại mọi bộ lọc và gửi đầy đủ bộ trường cursor: Ánh xạ các trường next_cursor được trả về sang yêu cầu tiếp theo:
  • next_cursor.time chuyển thành cursor_time.
  • next_cursor.id chuyển thành cursor_id.
  • Với trace, next_cursor.trace_id chuyển thành cursor_trace_id.
  • Với bản phát hành, thêm cursor_ vào trước mỗi tên trường được trả về, ví dụ next_cursor.release chuyển thành cursor_release.
Dừng khi next_cursor là null. Đừng tự tính cursor từ dòng cuối cùng. Cursor của bản phát hành không thay đổi các dự án đã chọn. Giữ nguyên project_id hoặc project_ids ban đầu.
limit đặt kích thước trang. Một trang có thể chứa ít dòng hơn. Các route này không nhận page hay page_number. Trên phần lớn các route, LogBrew đổi limit vượt mức tối đa thành mức tối đa. Danh sách triển khai từ chối limit nằm ngoài khoảng 1 đến 100 bằng 422. Danh sách triển khai luôn trả về đối tượng trang có next_cursor, kể cả khi không có pagination=cursor. LogBrew từ chối các yêu cầu sau với 422 và validation_failed:
  • Giá trị pagination khác cursor.
  • Trường cursor khi không có pagination=cursor.
  • Bộ trường cursor không đầy đủ.
  • cursor_time không phải dấu thời gian RFC3339.
Cursor đánh dấu một vị trí; nó không cố định dữ liệu. Bắt đầu lại từ trang đầu tiên khi bạn cần dữ liệu mới. CLI dùng các trường tương tự:

Chẩn đoán kết quả trống

Danh sách trống nghĩa là không có dòng nào khớp với mọi bộ lọc. Nó không nói gì về các tín hiệu khác. Kiểm tra yêu cầu theo thứ tự sau:
  1. Xác nhận ID dự án.
  2. Bỏ từng bộ lọc tùy chọn một.
  3. Mở rộng since nếu sự kiện cần tìm cũ hơn. Bỏ until hoặc dời until về sau nếu sự kiện cần tìm mới hơn.
  4. So sánh service_name, release và environment với các giá trị mà SDK của bạn gửi.
  5. Với log, thêm status=all nếu một quy tắc log có thể đang ẩn log cần tìm.
  6. Xác nhận route nhận từng bộ lọc.

Khắc phục khi truy vấn bị từ chối

Truy vấn bị từ chối trả về envelope lỗi chuẩn. Tham số không xác định hoặc giá trị sai kiểu trả về 422:
Cách sửa thường gặp:
  • Thay bí danh thân thiện bằng tham số trong bảng bộ lọc.
  • Gửi mọi trường cursor để đọc tiếp mà route cần.
  • Bỏ các trường cursor khỏi yêu cầu trang đầu tiên.
  • Chỉ dùng một tham số chọn dự án.
  • Thay mức độ nghiêm trọng hoặc trạng thái trace không được hỗ trợ bằng giá trị chuẩn.
Về mã lỗi và cách khắc phục, xem Lỗi API. Về body của phản hồi, xem Định dạng phản hồi.