텔레메트리 API 요청, 응답, 오류 코드

텔레메트리 API는 https://api.logbrew.co에서 HTTP로 JSON을 주고받습니다. 공개 SDK는 관리형 배치를 POST /v1/events로 보냅니다. 직접 만든 네이티브 클라이언트는 네이티브 엔벨로프를 POST /api/telemetry/ingest로 보냅니다. 두 수집 경로 모두 프로젝트 범위의 수집 bearer 토큰이 필요합니다. 읽기와 계정 소유 데이터 변경에는 계정 bearer 토큰을 사용합니다. 계정 bearer 토큰이나 브라우저 세션을 SDK 설정이나 수집 설정에 사용하지 마세요. 수집 bearer 토큰을 읽기 경로에 보내지 마세요.

범위가 정해진 요청 보내기

클라이언트가 요청을 보내기 전에 다음 체크리스트를 확인하세요.

엔드포인트 표에서 경로와 HTTP 메서드를 고르세요.
올바른 bearer 토큰을 사용하세요. 수집에는 수집 bearer 토큰을, 나머지에는 모두 계정 bearer 토큰을 사용합니다.
경로가 지원하는 프로젝트 범위를 선택하세요. 빈 응답을 받은 뒤 범위를 넓히지 마세요.
경로가 받는 쿼리 키만 추가하세요. 쿼리 필터를 참고하세요.
경로에 JSON 본문이 있으면 Content-Type: application/json을 보내세요.
재시도하기 전에 HTTP 상태와 응답 본문을 읽으세요.
bearer 토큰, 피드 티켓, 전체 응답 본문을 로그와 에이전트 프롬프트에 넣지 마세요.

엔드포인트

수집

메서드	경로	용도
`POST`	`/v1/events`	공개 LogBrew SDK가 만들어 보내는 배치를 수집합니다.
`POST`	`/api/telemetry/ingest`	직접 만든 클라이언트의 네이티브 텔레메트리 엔벨로프를 수집합니다.

/v1/events 배치는 SDK가 만들게 하세요. 직접 구성하지 마세요. 네이티브 엔벨로프는 SDK 연동을 참고하세요.

텔레메트리 읽기

메서드	경로	용도
`GET`	`/api/logs`	구조화된 로그를 나열합니다.
`GET`	`/api/logs/{log_id}`	로그 1개를 읽습니다.
`GET`	`/api/logs/attributes`	필터로 검색할 수 있는 로그 속성 경로와 유형을 나열합니다.
`GET`	`/api/telemetry/issues`	그룹으로 묶인 이슈를 나열합니다.
`GET`	`/api/telemetry/issues/{issue_id}`	그룹으로 묶인 이슈 1개를 읽습니다.
`GET`	`/api/telemetry/issues/{issue_id}/events`	그룹으로 묶인 이슈 1개의 발생 건을 나열합니다.
`PATCH`	`/api/telemetry/issues/{issue_id}`	이슈 1개의 상태, 우선순위, 담당자를 업데이트합니다.
`POST`	`/api/telemetry/issues/bulk`	한 프로젝트의 이슈 1~100개의 상태, 우선순위, 담당자를 업데이트합니다.
`GET`	`/api/telemetry/issues/assignees`	한 프로젝트에서 이슈를 할당할 수 있는 계정과 팀을 나열합니다.
`GET`	`/api/telemetry/issues/{issue_id}/owners`	이슈 1개의 추천 소유자를 나열합니다.
`GET`, `PUT`	`/api/telemetry/issues/ownership`	한 프로젝트의 소유권 규칙과 CODEOWNERS 텍스트를 읽거나 설정합니다.
`GET`	`/api/telemetry/issues/{issue_id}/activity`	이슈 1개의 변경 기록을 읽습니다.
`GET`	`/api/telemetry/issues/notifications`	다른 사람이 나나 내 팀에 할당한 이슈를 나열합니다.
`POST`	`/api/telemetry/issues/notifications/read`	내 이슈 알림을 읽음으로 표시합니다.
`PUT`	`/api/telemetry/issues/{issue_id}/triage-rule`	이슈의 심각도 규칙을 설정합니다.
`PUT`	`/api/logs/{log_id}/triage-rule`	로그 1개와 일치하는 로그의 심각도 규칙과 무시 상태를 설정합니다.
`GET`	`/api/telemetry/traces`	프로젝트 범위에서 트레이스를 검색합니다.
`GET`	`/api/telemetry/traces/{trace_id}`	트레이스 1개의 스팬을 나열합니다.
`GET`	`/api/telemetry/traces/{trace_id}/summary`	트레이스 1개의 범위가 제한된 요약을 읽습니다.
`GET`	`/api/telemetry/actions`	제품 액션을 나열합니다.
`GET`	`/api/telemetry/metrics`	메트릭 샘플을 나열합니다.
`GET`	`/api/telemetry/metrics/series`	메트릭 1개를 시간 구간별로 읽습니다.
`GET`	`/api/telemetry/releases`	릴리스 요약을 나열합니다.
`GET`	`/api/telemetry/summary/volume`	프로젝트 1개의 시그널 수를 시간 구간별로 읽습니다.

배포

메서드	경로	CLI 명령어
`PUT`	`/api/telemetry/deployments/{deployment_id}`	`logbrew deploy`
`GET`	`/api/telemetry/deployments/{deployment_id}?project_id=<project-uuid>`	없음
`GET`	`/api/telemetry/deployments?project_id=<project-uuid>`	없음

배포가 성공하거나 실패한 뒤 릴리스 자동화에서 배포를 기록하세요. PUT 본문에는 project_id, release, environment, service_name, status(succeeded 또는 failed), started_at, finished_at, 선택 사항인 commit_sha가 있습니다. SDK가 보내는 것과 같은 release, environment, service_name 값을 사용하세요. 계정이 프로젝트를 소유해야 합니다. deployment_id는 배포에 직접 붙이는 ID입니다. 같은 ID와 같은 본문으로 재시도하면 저장된 배포를 반환합니다. 같은 ID에 다른 본문을 보내면 409와 idempotency_conflict로 실패합니다. 다른 배포에는 새 ID를 사용하세요.

조사

각 조사 경로는 대상 1개에 대한 범위가 제한된 근거 묶음을 반환합니다. CLI 레퍼런스의 logbrew explain 명령어가 이 경로를 읽고 응답을 검증합니다.

메서드	경로	CLI 명령어
`GET`	`/api/logs/{log_id}/investigation`	`logbrew explain log`
`GET`	`/api/telemetry/issues/{issue_id}/investigation`	`logbrew explain issue`
`GET`	`/api/telemetry/issues/{issue_id}/correction-verification`	`logbrew investigate issue <issue_id> verify`
`GET`	`/api/telemetry/traces/{trace_id}/investigation`	`logbrew explain trace`
`GET`	`/api/telemetry/traces/{trace_id}/spans/{span_id}/investigation`	`logbrew explain span`
`GET`	`/api/telemetry/actions/{action_id}/investigation`	`logbrew explain action`
`GET`	`/api/telemetry/metrics/investigation`	`logbrew explain metric`
`GET`	`/api/telemetry/releases/investigation`	`logbrew explain release`

제품 분석

메서드	경로	CLI 명령어
`GET`	`/api/telemetry/analytics/overview`	`logbrew analytics overview`
`GET`	`/api/telemetry/analytics/properties`	`logbrew analytics properties`
`POST`	`/api/telemetry/analytics/funnel`	`logbrew analytics funnel`
`POST`	`/api/telemetry/analytics/retention`	`logbrew analytics retention`
`POST`	`/api/telemetry/analytics/lifecycle`	`logbrew analytics lifecycle`
`POST`	`/api/telemetry/analytics/paths`	`logbrew analytics paths`
`POST`	`/api/telemetry/analytics/segments/compare`	`logbrew analytics compare`

POST 분석 경로는 쿼리 키가 아니라 JSON 본문을 받습니다. 제품 분석을 참고하세요.

실시간 피드

메서드	경로	용도
`POST`	`/api/feed/ticket`	계정 bearer 토큰으로 수명이 짧은 실시간 피드 티켓을 만듭니다.
`GET`	`/api/feed/live?ticket=<ticket>`	그 티켓으로 WebSocket 연결을 엽니다.

계정과 로그인

사용량, 할당량, 구독, 로그아웃 경로는 계정 API에 있습니다.

성공 상태 코드

작업	성공 상태
수집, 읽기, 이슈 업데이트, 규칙, 배포, 분석, 피드 티켓	`200 OK`
실시간 피드 연결	`101 Switching Protocols` 다음에 WebSocket 메시지

200 응답이 근거가 완전하다는 것을 증명하지는 않습니다. 응답의 커버리지, 잘림, 상태 필드를 읽으세요.

쿼리 필터와 페이지네이션

읽기 경로마다 받는 쿼리 키가 다릅니다. project, trace, user 같은 알기 쉬운 별칭은 쿼리 키가 아닙니다. 목록 경로는 기본적으로 맨 배열을 반환하며, pagination=cursor를 쓰면 커서 엔벨로프를 반환합니다. 배포 목록은 항상 페이지 객체를 반환합니다. 쿼리 필터를 참고하세요.

응답과 오류

응답 형식은 응답 유형마다 예를 1개씩 보여 줍니다.
API 오류는 오류 코드와 복구 방법을 나열합니다.

사람이 읽는 메시지보다 code를 먼저 읽으세요. 프로그램 동작에는 next_action을, 사람을 위한 안내에는 next를 사용하세요. error나 next의 문구를 파싱하지 마세요.

이슈 업데이트하기

이 요청에는 계정 bearer 토큰을 사용합니다. 의도적으로 LOGBREW_INGEST_BEARER와 다른 토큰입니다. 계정에는 이슈가 속한 프로젝트의 이슈 관리 권한이 있어야 합니다. 권한이 없으면 요청이 403과 forbidden으로 실패합니다. 같은 권한으로 상태, 우선순위, 담당자 변경과 이슈 및 로그 규칙을 모두 다룹니다. 각 요청은 다음 필드 중 1개 이상을 설정합니다.

필드	값
`status`	`unresolved`, `resolved`, `archived` 중 하나입니다. `ignored`는 `archived`의 이전 이름입니다.
`priority`	`high`, `medium`, `low` 중 하나입니다.
`assignee`	사용자 ID, 로그인한 계정을 뜻하는 `me`, 팀을 뜻하는 `team:<team_id>`, 또는 담당자를 제거하는 `none`입니다.

이 필드가 하나도 없는 요청은 422와 validation_failed로 실패합니다. 이슈의 담당자는 최대 1개이며, 계정이나 팀 하나입니다. 계정은 프로젝트를 읽을 수 있어야 하고, 팀은 프로젝트의 조직에 속해야 합니다. 그렇지 않으면 요청이 422와 validation_failed로 실패하며, LogBrew는 아무것도 바꾸지 않습니다. 할당할 수 있는 계정은 담당자 나열하기로 가져오세요. 그 밖의 assignee 값도 422와 validation_failed로 실패합니다. 직접 설정한 우선순위는 고정됩니다. 직접 설정한 우선순위가 없으면 우선순위는 이슈 심각도를 따릅니다. error와 critical은 high, warning은 medium, info는 low입니다. 이미 요청한 값을 가진 필드는 바뀌지 않습니다. 시간 초과가 나면 같은 요청을 다시 보내도 됩니다. 시간 초과가 났다고 해서 변경이 일어나지 않았다는 것이 증명되지는 않습니다. 다른 변경을 보내기 전에 이슈를 다시 읽으세요.

이슈 1개 업데이트하기

응답에서 archived, 우선순위, 담당자를 받으려면 response_version=4를 추가하세요. 버전 4에서 assignee는 { "type": "user", "user_id", "name", "email" }, { "type": "team", "team_id", "slug", "name" }, null 중 하나입니다. 버전 3은 팀 담당자를 null로 보여 줍니다.

curl -X PATCH "$LOGBREW_API_URL/api/telemetry/issues/$ISSUE_ID?response_version=4" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  --data '{ "status": "archived", "priority": "low", "assignee": "me" }'

응답은 업데이트된 이슈입니다. 이슈 상태 응답 예를 참고하세요.

이슈 여러 개 한꺼번에 업데이트하기

project_id와, 그 프로젝트에 속한 서로 다른 이슈 ID 1~100개를 보내세요.

curl -X POST "$LOGBREW_API_URL/api/telemetry/issues/bulk" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  --data '{
    "project_id": "<project-uuid>",
    "issue_ids": ["<issue-uuid-1>", "<issue-uuid-2>"],
    "assignee": "<user-uuid>"
  }'

요청은 모든 이슈에 같은 변경을 적용합니다. 응답에는 project_id와 results가 있으며, results에는 이슈 ID마다 결과가 1개씩 요청 순서대로 들어 있습니다. 각 결과에는 issue_id, outcome, issue가 있습니다. issue는 응답 버전 3에서 현재 이슈이며, not_found이면 null입니다. 각 이슈를 응답 버전 4로 받으려면 본문에 "response_version": 2를 추가하세요.

`outcome`	의미
`updated`	LogBrew가 변경을 적용했습니다.
`unchanged`	이슈가 이미 요청한 값을 가지고 있었습니다.
`not_found`	프로젝트에 이 ID의 이슈가 없습니다. LogBrew는 이 ID에 대해 아무것도 바꾸지 않았습니다.

빈 목록, 100개를 넘는 ID, 중복된 ID는 422와 validation_failed로 실패합니다. 더 많은 이슈는 여러 요청으로 나누세요. 계정이 프로젝트를 읽을 수 없으면 요청이 404와 not_found로 실패합니다.

담당자 나열하기

프로젝트 ID를 보내면 그 프로젝트에서 이슈를 할당할 수 있는 모든 계정을 받을 수 있습니다.

curl "$LOGBREW_API_URL/api/telemetry/issues/assignees?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER"

목록에는 프로젝트를 읽을 수 있는 모든 계정이 들어 있습니다. 각 항목에는 user_id, name, email이 있습니다. 계정에 이름이 없으면 name은 null입니다. response_version=2를 추가하면 teams도 받습니다. teams에는 프로젝트가 속한 조직의 모든 팀이 team_id, slug, name과 함께 들어 있습니다. 담당자 목록 응답을 참고하세요. 프로젝트를 읽을 수 있는 계정이면 누구나 이 목록을 가져올 수 있습니다. 계정이 프로젝트를 읽을 수 없으면 요청이 404와 not_found로 실패합니다. 멤버가 프로젝트 접근 권한을 잃으면 그 멤버에게 할당된 이슈는 담당자 없음으로 표시됩니다. 그 멤버가 다시 접근 권한을 얻으면, 그 사이에 누군가 담당자를 바꾸거나 제거하지 않은 한 이슈에 다시 그 멤버가 표시됩니다.

소유권과 추천 소유자

GET /api/telemetry/issues/ownership?project_id=<project-uuid>는 rules, codeowners, updated_at, unresolved_owners를 반환합니다. 프로젝트를 읽을 수 있는 계정이면 누구나 읽을 수 있습니다. project_id와 함께 rules, codeowners 또는 둘 다를 PUT으로 보내면 그 텍스트를 바꿉니다. 이때는 이슈 관리 권한이 필요합니다. 보내지 않은 필드는 기존 텍스트를 유지하고, 빈 문자열은 텍스트를 지웁니다. 각 텍스트는 최대 128 KiB입니다. 잘못된 텍스트는 422로 실패하며, 문제가 있는 줄을 알려 줍니다. GET /api/telemetry/issues/{issue_id}/owners?response_version=2는 suggested_assignee, owners, inputs를 반환합니다. 각 소유자에는 type(user 또는 team), source(ownership_rule, codeowners, recent_activity), rule, line, matched가 있습니다. 기본값인 버전 1은 계정만 나열합니다.

이슈 변경 기록

GET /api/telemetry/issues/{issue_id}/activity?response_version=2는 최신순으로 정렬된 activity와 next_cursor를 반환합니다. 각 항목에는 type(status, priority, assigned, unassigned, severity_rule, first_seen), value, actor_id, actor, assignee_id, assignee, team, at이 있습니다. limit은 1~200이며 기본값은 50입니다. 다음 페이지를 읽으려면 next_cursor의 cursor_time과 cursor_id를 보내세요.

알림

GET /api/telemetry/issues/notifications는 notifications, unread, read_at, next_cursor를 반환합니다. 각 알림은 다른 계정이 이슈를 나나 내 팀에 할당한 기록입니다. POST /api/telemetry/issues/notifications/read에 빈 JSON 객체나 read_at을 보내면 읽음 표시를 옮깁니다. 읽음 표시는 뒤로 돌아가지 않습니다.

이슈 규칙과 로그 규칙 설정하기

규칙은 LogBrew가 일치하는 시그널을 보여 주는 방식을 바꿉니다. 데이터를 삭제하지는 않습니다. 수집된 severity는 그대로 유지되며, 응답의 triage에 규칙이 표시됩니다.

요청	JSON 본문
`PUT /api/telemetry/issues/{issue_id}/triage-rule`	`{ "severity": "<value>" }`
`PUT /api/logs/{log_id}/triage-rule`	`{ "severity": "<value>", "ignored": true }`

severity는 info, warning, error, critical, source 중 하나입니다. source는 재정의를 제거하고 수집된 심각도를 다시 보여 줍니다. 로그 규칙에서 ignored: true는 일치하는 로그를 기본 로그 목록에서 숨깁니다. 숨긴 로그는 status=ignored 또는 status=all로 읽으세요. 규칙은 보존된 시그널과 앞으로 들어올 일치하는 시그널에 적용됩니다. 다른 값은 422와 validation_failed로 실패합니다.

비어 있는 릴리스를 보내지 마세요. 릴리스 추적을 믿을 수 있도록 LogBrew는 빈 릴리스를 거부합니다.

​범위가 정해진 요청 보내기

​엔드포인트

​수집

​텔레메트리 읽기

​배포

​조사

​제품 분석

​실시간 피드

​계정과 로그인

​성공 상태 코드

​쿼리 필터와 페이지네이션

​응답과 오류

​이슈 업데이트하기

​이슈 1개 업데이트하기

​이슈 여러 개 한꺼번에 업데이트하기

​담당자 나열하기

​소유권과 추천 소유자

​이슈 변경 기록

​알림

​이슈 규칙과 로그 규칙 설정하기

범위가 정해진 요청 보내기

엔드포인트

수집

텔레메트리 읽기

배포

조사

제품 분석

실시간 피드

계정과 로그인

성공 상태 코드

쿼리 필터와 페이지네이션

응답과 오류

이슈 업데이트하기

이슈 1개 업데이트하기

이슈 여러 개 한꺼번에 업데이트하기

담당자 나열하기

소유권과 추천 소유자

이슈 변경 기록

알림

이슈 규칙과 로그 규칙 설정하기