추천 발생 건 읽기
LogBrew CLI를 설치하고logbrew login을 실행하세요. 이슈 목록에서 이슈 UUID를 복사하세요. CLI는 응답을 출력하기 전에 검증합니다.
--json을 사용하세요. logbrew explain issue "<issue_id>"도 같은 조회입니다. API로 직접 읽으려면 응답 버전 13을 요청하세요. CLI도 같은 버전을 요청합니다.
response_version 1부터 13까지 받습니다. 발생 건을 선택하려면 버전 2 이상이 필요합니다. 이 가이드는 버전 13을 설명합니다.
추천 발생 건은 쓸모 있는 컨텍스트가 있는 최근의 보존된 발생 건입니다. 가장 최근 발생 건보다 오래되었을 수 있습니다. LogBrew는 보존된 발생 건 중 가장 최근 것부터 occurrence_selection.recommendation.candidate_limit개까지 비교합니다. 그중 조사 컨텍스트가 가장 많은 발생 건을 고릅니다. 두 발생 건의 컨텍스트가 같으면 더 최근 것을 고릅니다. occurrence_selection.recommendation.candidate_window_truncated가 true이면, 추천에서 평가하지 않은 더 오래된 발생 건이 이슈에 있습니다.
조사 범위 확인하기
이슈 목록 필터는 조사에 적용되지 않습니다. 이슈 ID가 그룹을 선택하고, 응답에는 그룹의 보존된 이력이 들어갈 수 있습니다. 정확한 발생 건 ID를 지정해도 이 이력은 빠지지 않습니다. 작업에서 이 이력을 허용하지 않으면 조사를 요청하지 마세요. 오류를 해석하기 전에 다음을 확인하세요.subject.project_id가 의도한 프로젝트입니다.event.id가 선택한 발생 건입니다.event.occurred_at이 장애 기간 안에 있습니다.- 서비스, 환경, 릴리스가 검토 중인 배포와 일치합니다.
schema_version이13입니다.
다른 발생 건 선택하기
선택자를 하나 보내세요.selection과 occurrence_id를 함께 보내지 마세요. subject의 first_seen_at과 last_seen_at은 그룹을 설명합니다. 자세한 근거는 선택한 event에 속합니다.
occurrence_selection은 first, latest, recommended, selected 발생 건의 요약도 반환합니다. occurrence_selection.reason은 LogBrew가 그 발생 건을 고른 이유를 알려 줍니다.
응답을 순서대로 읽기
- 그룹은
subject에서, 선택한 발생 건은event에서 읽으세요. - 그룹 이력은
grouping,lifecycle,occurrence_analysis에서 읽으세요. - 코드 위치는
fix에서 읽으세요. 파일, 함수, 줄, 열과 함께provenance도 기록해 두세요. 관측된 프레임은 살펴볼 코드를 보여 줄 뿐, 원인이 증명된 것은 아닙니다. cause.status와 그 근거를 읽으세요. 어떤 원인 값도 근본 원인을 증명하지 않습니다.impact.user_impact는impact.occurrence_count와 따로 읽으세요. 개수와 함께count_method,coverage,limitations도 기록해 두세요. 사용자 1명이 발생 건 여러 개를 일으킬 수 있습니다.reproduction.status를 읽고 그다음correlations를 읽으세요.
코드 위치와 원인
fix.status는 코드 위치의 출처를 알려 줍니다.
cause.status는 reported_hypothesis, evidence_only, unknown 중 하나입니다. reported_hypothesis는 앱이 보낸 값이며 검증되지 않았습니다. cause.signals에는 unhandled_exception이나 error_trace_span 같은 관측된 시그널이 나열됩니다. provenance는 backend_observed 또는 application_reported입니다. 둘을 구분하세요.
소스 파일 찾기
프로젝트 설정에서 서비스에 저장소를 연결했다면source_locator가 코드 위치를 저장소와 연결합니다. 파일을 열려면 repository_full_name, revision, repository_relative_file을 사용하세요. revision_source는 deployment_commit 또는 setup_snapshot입니다.
source_locator.status가 not_found이면 서비스에 연결된 저장소 구성 요소가 없다는 뜻입니다. 파일이 없다는 뜻은 아닙니다. 파일 이름으로 구성 요소를 추측하지 마세요.
영향받은 사용자
known_affected_users는 상태가 complete여도 근사치입니다. 익명 사용자나 사용자 컨텍스트가 없는 발생 건은 세지 않습니다. null 개수는 0이 아닙니다. impact.reported에는 앱이 보고한 값이 들어 있습니다. 이 값을 측정된 개수에 더하지 마세요.
재현 상태
트리거는
event.request 또는 impact.reported.failed_action에서 옵니다. 예상 실패는 event.exception 또는 event.request.response_status_code에서 옵니다. 코드 위치는 fix.location입니다. reproduction.baseline_occurrence_id는 선택한 발생 건입니다. reproduction.evidence 기록에는 각 입력값이 reproduction.trigger, reproduction.expected_failure, reproduction.code_location으로 남습니다. ready 상태라고 해서 재현에 성공했다는 증명은 아닙니다. 요청 본문, 가려진 값, 재현 단계를 절대 지어내지 마세요.
라이프사이클과 회귀
lifecycle.persisted_status는 저장된 상태입니다. 이슈가 해결된 뒤에 발생 건이 들어오면 lifecycle.effective_status는 regressed가 됩니다. 사람이 이슈를 다시 열기 전까지 저장된 상태는 resolved로 유지됩니다. lifecycle.regression.first_reappeared_occurrence는 다시 나타난 첫 번째 발생 건을 가리킵니다.
조사 응답은 보관된 이슈를 subject.status와 lifecycle에서 ignored로 표시합니다. 상태 값을 참고하세요.
누락되거나 제한된 근거 다루기
correlations.trace.status의 값은 다음과 같습니다.
not_linked이면 예외, 프레임, 브레드크럼 등 반환된 다른 근거로 계속 진행하세요. not_found이면 정확한 트레이스 ID를 기록해 두세요. unavailable이면 나중에 다시 시도하세요. 어떤 상태도 앱에 트레이스가 없다는 뜻은 아닙니다. available 트레이스에 이슈의 수집 스팬만 있을 수도 있습니다. 수집 스팬을 참고하세요.
correlations.logs에는 같은 릴리스와 환경에서 발생 시각 전후에 나온 로그가 들어 있습니다. 발생 건에 트레이스 ID가 있으면 그 트레이스의 로그를 가져옵니다. 트레이스 ID가 없으면 같은 서비스의 로그를 가져옵니다. actions, metrics, related_issues에는 트레이스 ID가 필요합니다. 각 컬렉션에는 status, items, truncated가 있습니다.
captured_fields, missing_fields, redacted_fields, truncated_fields를 구분하세요. 가려진 데이터는 누락된 것이 아닙니다. 잘린 데이터는 완전하지 않습니다. 필수 필드가 누락되었거나, 가려졌거나, 잘렸거나, 사용할 수 없으면 evidence.status는 partial입니다. SDK를 업데이트해도 과거 이벤트에 근거가 추가되지는 않습니다.
관련 로그, 이슈, 릴리스는 정확한 ID로 따라가세요. 시각이 가깝다고 해서 연결된 것은 아닙니다.
다음 액션 따르기
클라이언트가 정확한code와 target 조합을 지원하면 next_actions를 priority 순서대로 처리하세요. 각 액션에는 reason도 있습니다.
후보 배포 검증하기
실패한 발생 건 ID를 기준으로 사용하세요. 후보 배포 ID는 배포 근거나 릴리스 프로세스에서 구하세요.logbrew deploy는 배포를 기록합니다.
422로 실패합니다.
응답은 배포가 끝난 뒤부터 요청 시각까지 LogBrew가 받은 같은 이슈의 발생 건을 셉니다(observed_after, observed_until). 후보 릴리스의 트레이스 수도 셉니다.
absence_is_proof는 항상 false입니다. 이 기간에 재발하지 않았다고 해서 영구적으로 고쳐졌다는 증명은 아닙니다. 팀이 근거를 받아들인 뒤에만 이슈 워크플로에서 상태를 바꾸세요.
안전하게 복구하기
오류 응답에는
error, code, next, next_action이 들어 있습니다. 프로그램 제어에는 code와 next_action을 사용하세요. next는 안내로 보여 주세요. 명령어로 실행하지 마세요. 조회에 실패했을 때 요청한 발생 건을 다른 발생 건으로 바꾸지 마세요. API 오류와 텔레메트리 API를 참고하세요.