Skip to main content
조회 라우트마다 받는 쿼리 키가 다릅니다. 필터 표에 있는 라우트는 알 수 없는 키나 유형이 잘못된 값을 422, validation_failed로 거부합니다. 표에 다르게 적힌 경우는 예외입니다. project, trace, user 같은 알기 쉬운 별칭은 쿼리 키가 아닙니다. 한 라우트의 필터를 다른 라우트로 옮겨 쓰지 마세요.

필터를 적용한 요청 만들기

쿼리 문자열은 경로 뒤에 붙이세요. 예약 문자가 안전하게 전달되도록 --data-urlencode를 사용하세요. 다음 요청은 프로젝트 1개에서 최근 24시간의 치명적 로그를 읽습니다.
필터는 다음 순서로 추가하세요.
  1. project_id나 project_ids로 프로젝트를 선택하세요.
  2. since로 기간을 추가하고, 필요하면 until도 추가하세요.
  3. 서비스, 릴리스, 환경, 상태, 시그널별 필터를 추가하세요.
  4. 페이지를 더 작게 받으려면 limit를 설정하세요.
  5. 커서 필드는 커서 응답이 그 값을 반환한 뒤에만 추가하세요.
반환된 각 행은 요청의 모든 필터와 일치합니다. 생략한 필터에는 라우트의 기본값이 적용됩니다. 예를 들어 GET /api/logs는 status를 생략하면 status=active를 사용합니다.

필터 표

“필수” 열의 키는 요청에 반드시 넣어야 합니다. 나머지 키는 모두 선택 사항입니다. 이슈 조사에서 selection은 first, latest, recommended 중 하나입니다. selection과 occurrence_id 중 하나만 보내세요. 둘 다 보내면 안 됩니다. 어느 쪽이든 2부터 13까지의 response_version이 필요합니다. 버전 2 이상에서 선택자를 보내지 않으면 LogBrew는 recommended를 사용합니다. occurrence_id는 GET /api/telemetry/issues/{issue_id}/events에서 가져오세요. POST 분석 라우트는 JSON 본문을 받습니다. 제품 분석을 참고하세요.

공통 필터와 시그널별 필터

service_name, release, environment는 모든 텔레메트리 목록의 범위를 좁힙니다. SDK가 보내는 값을 그대로 사용하세요. 일부 필터는 특정 시그널에만 적용됩니다.
  • 로그는 search, trace_id, severity, attribute_filters를 받습니다.
  • 로그는 status로 active(기본값), ignored, all을 받습니다. ignored는 로그 규칙 때문에 활성 보기에서 숨겨진 로그를 선택합니다.
  • 이슈는 이슈 status로 unresolved, resolved, archived를 받습니다. ignored는 archived의 이전 이름이며 같은 이슈를 선택합니다.
  • 이슈는 severity로 info, warning, error, critical을 받습니다.
  • 이슈는 priority로 high, medium, low를 받습니다.
  • 이슈는 assignee로 me(로그인한 계정에 할당된 이슈), none(담당자가 없는 이슈), my_teams(내 팀의 이슈), 사용자 ID, team:<team_id>를 받습니다.
  • 액션과 메트릭은 name을 받습니다.
  • 액션은 distinct_id를 받습니다.
  • 트레이스는 트레이스 status와 min_duration_ms를 받습니다.
  • 배포는 status로 succeeded나 failed를 받습니다.
로그와 이슈의 severity 필터는 실제 적용된 심각도를 비교합니다. 규칙이 심각도를 바꿨다면 필터는 규칙의 값을 사용합니다. 심각도 값을 참고하세요.

기간

since는 24h나 7d처럼 양의 정수로 된 시간 수나 일 수, 또는 RFC3339 타임스탬프를 받습니다. 짧은 기간 표기는 각 요청 시각을 기준으로 합니다. until은 RFC3339 타임스탬프만 받습니다. until은 끝 시각을 포함하지 않습니다. 정확히 until 시각에 있는 행은 결과에 들어가지 않습니다. since는 시작 시각을 포함합니다. 예를 들어 since=2026-10-01T00:00:00Z와 until=2026-10-02T00:00:00Z는 정확히 1일을 선택합니다. LogBrew는 시각을 밀리초 단위로 비교합니다. until은 since보다 늦어야 합니다. 그렇지 않거나 until이 RFC3339 타임스탬프가 아니면 요청이 422, validation_failed로 실패합니다. 여러 페이지를 읽을 때는 RFC3339 시작 시각 하나를 정해 모든 페이지에서 유지하세요. until도 모든 페이지에서 같게 유지하세요. 다음 요청은 1일 동안의 오류 로그를 읽습니다.
배포 목록은 다른 시간 규칙을 사용합니다. 배포 목록의 since와 until은 RFC3339 타임스탬프만 받으며, 둘 다 해당 시각을 포함합니다. 비교 기준은 배포가 끝난 시각입니다.

이슈 응답 버전

이슈 목록과 이슈 상세 정보는 response_version=1, response_version=2, response_version=3, response_version=4을 받습니다. 기본값은 버전 1입니다. 다른 값은 422, validation_failed로 실패합니다.
  • 버전 1은 보관 상태를 ignored로 보여 줍니다. 우선순위는 보여 주지 않습니다.
  • 버전 2는 보관 상태를 archived로 보여 줍니다. priority와 priority_source가 추가됩니다.
  • 버전 3에는 버전 2의 필드가 모두 있습니다. assignee가 추가됩니다.
  • 버전 4에는 버전 3의 필드가 모두 있습니다. assignee에는 type(user 또는 team)이 있습니다.
모든 버전이 status=archived, priority, assignee를 받습니다. 이슈 응답을 참고하세요.

심각도 필터

GET /api/logs에서는 severity=info|warning|error|critical을 사용하세요. 이전 level 키는 호환용 별칭입니다. 두 키 모두 표준 값과 별칭 trace, debug, warn, fatal을 받습니다. LogBrew는 비교하기 전에 별칭을 표준 값으로 바꿉니다. 요청에 severity와 level이 모두 있으면 LogBrew는 먼저 둘 다 정규화합니다. 값이 서로 다르면 다음 오류로 거부합니다.

트레이스 필터

트레이스 검색에서 status는 error 또는 ok입니다. 둘 다 포함하려면 생략하세요. min_duration_ms는 0 이상이어야 합니다. 이 키는 트레이스 검색에만 적용됩니다. 다음 요청은 500밀리초 이상 걸린 오류 트레이스를 찾습니다.
트레이스 상세 정보와 요약에서는 trace_id를 퍼센트 인코딩해 경로 세그먼트로 넣으세요. 쿼리 키로 보내지 마세요.

프로젝트 범위

프로젝트 1개를 읽으려면 project_id=<project-uuid>를 사용하세요. 표에서 project_ids가 있는 라우트에서는 project_ids=<uuid>,<uuid>로 프로젝트 2~50개의 정확한 집합을 지정하세요. 이 라우트에서 두 키를 모두 생략하면 계정이 읽을 수 있는 모든 프로젝트를 읽습니다. project_id가 필수인 라우트는 프로젝트 1개만 받습니다.
LogBrew는 다음 선택을 422, validation_failed로 거부합니다.
  • project_id와 project_ids가 모두 있는 요청
  • ID가 2개보다 적거나 50개보다 많은 project_ids 값
  • 중복된 ID나 UUID가 아닌 ID
project_ids의 ID 중 하나가 계정이 읽을 수 없는 프로젝트이면 요청이 404, not_found로 실패합니다. 그 ID를 빼고 계속하지 마세요. 사용자에게 새 집합을 고르도록 요청하세요. 모든 커서 페이지에서 같은 프로젝트 범위를 유지하세요. 결과가 비어 있다고 프로젝트 필터를 빼지 마세요. 그러면 다른 질문을 하는 셈이 됩니다.

시간 구간별 시계열

GET /api/telemetry/metrics/series는 메트릭 1개를 시간 구간별로 반환합니다. GET /api/telemetry/summary/volume은 시그널 개수를 시간 구간별로 반환합니다. 두 라우트 모두 다음 규칙을 따릅니다.
  • since는 필수입니다. until은 선택 사항이며 기본값은 요청 시각입니다.
  • since부터 until까지의 범위는 최대 31일입니다.
  • interval은 auto, 1m, 5m, 15m, 1h, 6h, 1d 중 하나입니다. 기본값은 auto입니다. 시간 구간이 500개를 넘게 만드는 간격은 실패합니다.
  • service_name, release, environment는 정확히 일치하는 값으로 필터링합니다.
메트릭 시계열에서 name은 GET /api/telemetry/metrics에 나오는 정확한 메트릭 이름입니다. group_by는 none, service_name, release, environment 중 하나입니다. series_limit은 1~20입니다. 시그널 양에서는 until이 미래 시각이면 안 되며, response_version은 1만 받습니다.

로그 속성 필터링

GET /api/logs/attributes로 검색할 수 있는 속성 경로와 유형을 찾으세요. 그런 다음 GET /api/logs에 attribute_filters를 보내세요. 두 요청 모두 since가 필요합니다.

속성 카탈로그 읽기

다음 요청은 프로젝트 1개에서 status가 들어간 숫자 경로를 찾습니다.
응답은 맨 배열이 아니라 객체입니다. 다음은 속성 2개와 다음 페이지가 있는 가상의 예시입니다.
type은 string, number, boolean 중 하나입니다. observed_count는 범위 안에서 그 경로와 유형을 가진 로그 수입니다. last_seen_at은 그중 가장 최근 로그의 시각입니다. 로그 1개에 경로가 여러 개 있을 수 있습니다. 개수를 더해서 로그 수를 구하지 마세요. coverage는 속성 필터로 검색할 수 있는 로그를 알려 줍니다. 세 그룹을 더하면 total_logs가 됩니다. 카탈로그의 type, search, 커서는 커버리지를 바꾸지 않습니다. attributes 목록이 비어 있어도 total_logs가 0이라는 뜻은 아닙니다. 카탈로그에는 status 키가 없습니다. 카탈로그의 심각도 필터는 실제 적용된 심각도가 아니라 수집된 심각도를 비교합니다. search는 제어 문자가 없는 1~128바이트의 경로 부분 문자열입니다. limit는 한 페이지의 속성 수를 정합니다.

카탈로그 이어서 읽기

카탈로그는 pagination=cursor를 사용하지 않습니다. 모든 필터를 반복하고, next_cursor의 세 필드를 모두 복사하세요. next_cursor가 null이면 멈추세요.

유형별 필터 적용하기

카탈로그에서 경로와 유형을 복사하세요. 경로는 점으로 구분한 키가 아니라 JSON Pointer 구문을 사용합니다. 경로에 있는 ~0이나 ~1 이스케이프는 그대로 두세요. 다음 요청은 숫자 응답 상태가 500 이상인 로그를 읽습니다.
attribute_filters는 필터 1~4개로 이루어진 JSON 배열입니다. 로그는 모든 필터와 일치해야 합니다. 각 필터에는 path, type, operator, value가 있습니다. value의 JSON 유형은 type과 일치해야 합니다. 숫자 500은 문자열 "500"과 다릅니다. ne는 해당 경로가 있는 로그에만 일치합니다. 경로가 없는 로그는 ne와 일치하지 않습니다. string에서 case_sensitive는 선택 사항이며 기본값은 false입니다. LogBrew는 number와 boolean에 대한 "case_sensitive": true를 거부합니다. 다음 한도가 적용됩니다.
  • JSON 배열은 최대 4,096바이트입니다.
  • 문자열 값은 최대 1,024바이트입니다.
  • contains와 starts_with에는 비어 있지 않은 문자열이 필요합니다.
  • 숫자는 유한한 값이어야 하며 -9,007,199,254,740,992부터 9,007,199,254,740,992까지입니다.
인덱스로 검색할 수 없는 로그는 필터와 일치하지 않습니다. 이런 로그도 attribute_filters 없는 요청에는 나타날 수 있습니다. 로그 응답은 로그 응답을 참고하세요.

속성 오류 고치기

아래 오류는 모두 422, validation_failed를 반환합니다. 다시 시도하기 전에 요청을 고치세요. 필터를 빼지 마세요. 필터를 빼면 결과가 달라집니다.

커서 기반 페이지네이션

커서 모드는 직접 켜야 합니다. 커서 모드가 아니면 목록 라우트는 맨 배열을 반환합니다. 첫 페이지에는 커서 필드 없이 pagination=cursor를 보내세요. 다음 페이지마다 모든 필터를 반복하고 커서 필드를 빠짐없이 보내세요. 반환된 next_cursor 필드를 다음 요청에 다음과 같이 넣으세요.
  • next_cursor.time은 cursor_time에 넣습니다.
  • next_cursor.id는 cursor_id에 넣습니다.
  • 트레이스에서는 next_cursor.trace_id를 cursor_trace_id에 넣습니다.
  • 릴리스에서는 반환된 각 필드 이름 앞에 cursor_를 붙입니다. 예를 들어 next_cursor.release는 cursor_release에 넣습니다.
next_cursor가 null이면 멈추세요. 마지막 행으로 커서를 계산하지 마세요. 릴리스 커서는 선택한 프로젝트를 바꾸지 않습니다. 원래의 project_id나 project_ids를 유지하세요.
limit는 페이지 크기를 정합니다. 페이지에 이보다 적은 행이 들어 있을 수 있습니다. 이 라우트는 page나 page_number를 받지 않습니다. 대부분의 라우트에서 LogBrew는 최댓값을 넘는 limit를 최댓값으로 바꿉니다. 배포 목록은 1~100 범위를 벗어난 limit를 422로 거부합니다. 배포 목록은 pagination=cursor가 없어도 항상 next_cursor가 있는 페이지 객체를 반환합니다. LogBrew는 다음 요청을 422, validation_failed로 거부합니다.
  • pagination 값이 cursor가 아닌 요청
  • pagination=cursor 없이 커서 필드를 보낸 요청
  • 커서 필드가 빠짐없이 들어 있지 않은 요청
  • cursor_time이 RFC3339 타임스탬프가 아닌 요청
커서는 위치를 표시할 뿐 데이터를 고정하지 않습니다. 최신 상태를 보려면 첫 페이지부터 새로 시작하세요. CLI도 같은 필드를 사용합니다.

빈 결과 진단하기

목록이 비어 있으면 모든 필터와 일치하는 행이 없다는 뜻입니다. 다른 시그널에 대해서는 아무것도 알려 주지 않습니다. 다음 순서로 요청을 확인하세요.
  1. 프로젝트 ID를 확인하세요.
  2. 선택 필터를 하나씩 빼 보세요.
  3. 찾는 이벤트가 더 오래되었다면 since를 넓히세요. 찾는 이벤트가 더 최근이라면 until을 빼거나 더 늦은 시각으로 옮기세요.
  4. service_name, release, environment를 SDK가 보내는 값과 비교하세요.
  5. 로그라면, 로그 규칙이 찾는 로그를 숨길 수 있을 때 status=all을 추가하세요.
  6. 라우트가 각 필터를 받는지 확인하세요.

거부된 쿼리 복구하기

거부된 쿼리는 표준 오류 형식을 반환합니다. 알 수 없는 키나 유형이 잘못된 값은 422를 반환합니다.
자주 쓰는 해결 방법은 다음과 같습니다.
  • 알기 쉬운 별칭을 필터 표에 있는 키로 바꾸세요.
  • 라우트에 필요한 이어 읽기 커서 필드를 모두 보내세요.
  • 첫 페이지 요청에서는 커서 필드를 빼세요.
  • 프로젝트 선택자는 하나만 사용하세요.
  • 지원되지 않는 심각도나 트레이스 상태는 표준 값으로 바꾸세요.
오류 코드와 복구 방법은 API 오류를 참고하세요. 응답 본문은 응답 형식을 참고하세요.