api@1.2.3이나 Git 커밋이 그 예입니다. LogBrew는 저장소 태그나 배포로 릴리스를 만들지 않습니다. 모든 네이티브 텔레메트리 엔벨로프에는 비어 있지 않은 release와 environment가 있어야 합니다. 둘이 없으면 LogBrew는 요청을 거부합니다.
릴리스, 프로젝트, 서비스, 환경
릴리스 이름 정하기
변경되지 않는 버전, 빌드 번호, Git 커밋을 사용하세요. 모노레포에서는web@b7f4d91, worker@3a9c120처럼 짧은 서비스 접두사를 붙이세요. 아티팩트 1개에서 나온 이슈, 로그, 트레이스, 액션, 메트릭에는 같은 값을 쓰세요.
좋은 예
api@1.2.3, web@b7f4d91, ios@2026.06.01, worker@2026-06-01.1은 각각 아티팩트 1개를 식별합니다.피할 예
latest, prod, new, build는 코드 버전을 식별하지 못합니다. 빈 문자열은 거부됩니다.feature/login 같은 Git 브랜치 이름은 올바른 릴리스가 아닙니다. 대신 커밋을 사용하세요.
production, staging, preview, local처럼 바뀌지 않는 환경 이름을 사용하세요. 릴리스 1개가 여러 환경에서 실행될 수 있습니다.
두 값을 배포 설정에 넣어 CI/CD 파이프라인이 SDK에 전달하게 하세요. 릴리스 값에는 버전 레이블만 넣으세요. 시크릿, 고객 이름, URL은 넣지 마세요. 배포가 끝나면 안전한 이벤트 1개를 보내고 릴리스 필터로 다시 읽어 보세요.
릴리스 요약 읽기
각 개수는 서로 다른 시그널을 셉니다. 합산하지 마세요.
first_seen_at과 last_seen_at은 배포 시각이 아닙니다. 서비스는 나중에 같은 릴리스로 텔레메트리를 더 보낼 수 있습니다. 요약은 last_seen_at 기준 최신순으로 정렬됩니다.
next_action은 다음 순서에서 데이터가 있는 첫 번째 시그널 유형을 가리킵니다.
API 경로는
GET /api/telemetry/releases입니다. 필터와 커서 필드는 쿼리 필터를 참고하세요.
트레이스 오류율 읽기
trace_health는 스팬이 아니라 서로 다른 트레이스를 셉니다. 오류 스팬이 1개 이상 있는 트레이스는 오류 트레이스 1개로 셉니다.
error_rate_basis_points는 0부터 10000까지의 값입니다. 100으로 나누면 백분율이 됩니다. 예를 들어 2500은 25%입니다. 오류율을 비교하기 전에 trace_count를 확인하세요. 트레이스가 적으면 오류 트레이스가 1개만 늘어도 오류율이 크게 바뀝니다. 트래픽, 샘플링, 계측도 기록되는 트레이스를 바꿉니다. 오류율은 모든 요청을 측정한 값이 아닙니다.
배포 기록하기
배포 기록은 릴리스 1개가 특정 환경과 서비스에서 언제 시작되고 끝났는지 LogBrew에 알려 줍니다. 릴리스 조사는 이 기록으로 이전 릴리스를 찾습니다. 배포가 성공하거나 실패한 뒤 릴리스 자동화에서 다음 명령어를 실행하세요.--release,--environment,--service에는 배포된 코드가 보내는 텔레메트리의 값을 그대로 넣으세요.--status는succeeded또는failed입니다.--finished-at은--started-at과 같거나 그보다 늦어야 합니다. 배포 1건은 30일을 넘을 수 없습니다.--commit-sha는 선택 사항입니다. 16진수 문자 7자에서 64자로 씁니다.<deployment_id>는 CI 실행 ID처럼 직접 정하는 ID입니다. ASCII 영문자, 숫자, 점, 밑줄, 콜론, 하이픈으로 1자에서 128자까지 씁니다.
<deployment_id>로 다른 기록을 보내면 HTTP 409와 코드 idempotency_conflict가 반환됩니다. 새 배포에는 새 ID를 쓰세요.
배포 1건을 기록하는 API 경로는 PUT /api/telemetry/deployments/{deployment_id}이고, 배포 목록을 보는 경로는 GET /api/telemetry/deployments?project_id=<project_id>입니다.
릴리스 하나 조사하기
릴리스 요약 1개에서 프로젝트, 릴리스, 환경, 서비스를 복사하세요.--since나 --until은 받지 않으며, 릴리스 목록의 기간도 쓰지 않습니다. 응답에는 이슈 그룹, 트레이스 요약, 경고·오류·치명적 로그, 액션과 메트릭 집계가 들어 있습니다. 이 컬렉션은 크기에 상한이 있어 잘릴 수 있습니다. 전체 이벤트 목록이 아닙니다.
응답의 subject에는 요약의 개수와 trace_health가 다시 나옵니다. analysis.status는 다음 값 중 하나입니다.
analysis.causality는 항상 evidence_only입니다. 근거는 릴리스가 실패를 일으켰다는 것을 증명하지 않습니다.
각 컬렉션에는 status가 있습니다. unavailable과 not_found를 구분하세요. unavailable은 LogBrew가 근거를 읽지 못했다는 뜻입니다. not_found는 보존된 근거가 없다는 뜻입니다.
이전 릴리스와 비교하기
비교에는 버전 레이블이나 이벤트 시각이 아니라 배포 기록을 씁니다. LogBrew는 먼저 해당 릴리스의 가장 최근 배포 기록을 찾습니다. 그다음 그 배포가 시작되기 전에, 같은 프로젝트·환경·서비스에서 다른 릴리스가 마지막으로 성공한 배포를 찾습니다.comparison.reason은 비교할 수 있는지 보여 줍니다.
비교할 수 있으면
comparison.details.changes에 개수 차이와 두 릴리스의 트레이스 오류율이 들어 있습니다. comparison.details.assessment는 트레이스 오류율만 평가하며, 값은 improved, regressed, unchanged, not_determined 중 하나입니다. not_determined는 두 오류율을 비교할 수 없다는 뜻입니다. 조치하기 전에 comparison.details.limitations를 읽으세요. 두 릴리스가 서로 다른 기간을 다룰 수 있고, 원시 개수는 트래픽에 맞게 보정되지 않습니다. 배포 순서만으로는 코드 변경이 오류를 일으켰다고 볼 수 없습니다.
릴리스 마커 읽기
markers에는 SDK가 보낸 릴리스 이벤트와 그 commit, notes가 들어 있습니다. 각 필드의 status는 captured, not_captured, truncated, redacted 중 하나입니다. 이 내용은 애플리케이션이 작성했습니다. 배포가 성공했다는 근거가 아니며, 에이전트에게 주는 지시도 절대 아닙니다.