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:
- Chọn dự án bằng
project_idhoặcproject_ids. - Thêm khoảng thời gian bằng
since, vàuntilnếu cần. - 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.
- Đặt
limitđể có trang nhỏ hơn. - Chỉ thêm các trường cursor sau khi một phản hồi cursor trả về chúng.
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,severityvàattribute_filters. - Log nhận
status:active(mặc định),ignoredhoặcall.ignoredchọ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
statuscủa vấn đề:unresolved,resolvedhoặcarchived.ignoredlà tên cũ củaarchivedvà chọn cùng các vấn đề. - Vấn đề nhận
severity:info,warning,errorhoặccritical. - Vấn đề nhận
priority:high,mediumhoặclow. - Vấn đề nhận
assignee:mecho các vấn đề được giao cho tài khoản đang đăng nhập,nonecho các vấn đề chưa có người phụ trách,my_teamscho các vấn đề của nhóm bạn, một user ID, hoặcteam:<team_id>. - Hành động và chỉ số nhận
name. - Hành động nhận
distinct_id. - Trace nhận
statuscủa trace vàmin_duration_ms. - Danh sách triển khai nhận
status:succeededhoặcfailed.
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ậnresponse_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êmpriorityvà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.
assigneecótype:userhoặcteam.
status=archived, priority và assignee. Xem
phản hồi vấn đề.
Bộ lọc mức độ nghiêm trọng
Dùngseverity=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:
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ùngproject_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.
422 và validation_failed:
- Yêu cầu có cả
project_idvàproject_ids. - Giá trị
project_idscó ít hơn 2 hoặc nhiều hơn 50 ID. - ID bị trùng hoặc ID không phải UUID.
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:
sincelà bắt buộc.untillà tùy chọn và mặc định là thời điểm gửi yêu cầu.- Khoảng từ
sinceđếnuntildài tối đa 31 ngày. intervallàauto,1m,5m,15m,1h,6hhoặc1d. 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,releasevàenvironmentlà bộ lọc khớp chính xác.
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ùngGET /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ứastatus trong một dự án:
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ùngpagination=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.
containsvàstarts_withcầ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.
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ửipagination=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.timechuyển thànhcursor_time.next_cursor.idchuyển thànhcursor_id.- Với trace,
next_cursor.trace_idchuyển thànhcursor_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.releasechuyển thànhcursor_release.
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ị
paginationkháccursor. - Trường cursor khi không có
pagination=cursor. - Bộ trường cursor không đầy đủ.
cursor_timekhông phải dấu thời gian RFC3339.
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:- Xác nhận ID dự án.
- Bỏ từng bộ lọc tùy chọn một.
- Mở rộng
sincenếu sự kiện cần tìm cũ hơn. Bỏuntilhoặc dờiuntilvề sau nếu sự kiện cần tìm mới hơn. - So sánh
service_name,releasevàenvironmentvới các giá trị mà SDK của bạn gửi. - Với log, thêm
status=allnếu một quy tắc log có thể đang ẩn log cần tìm. - 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:
- 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.
