> ## Documentation Index
> Fetch the complete documentation index at: https://docs.logbrew.co/llms.txt
> Use this file to discover all available pages before exploring further.

# LogBrew 옵저버빌리티: 애플리케이션 문제 조사

> 옵저버빌리티와 모니터링의 차이를 알아보세요. 로그, 트레이스, 메트릭, 컨텍스트로 애플리케이션 동작을 살펴보세요.

LogBrew는 개발자와 코딩 에이전트를 위한 옵저버빌리티 플랫폼입니다. 애플리케이션이 LogBrew로 텔레메트리를 보냅니다. 웹사이트, 네이티브 `logbrew` CLI, API, 호스팅 MCP 서버 중 하나로 선택한 프로젝트의 근거를 조회하세요.

## <span id="what-is-observability">옵저버빌리티와 텔레메트리</span>

텔레메트리는 애플리케이션이 자신의 작동 상태에 관해 보내는 데이터입니다. 옵저버빌리티는 이 데이터로 애플리케이션 동작을 살펴볼 수 있는 능력입니다.

모니터링은 오류율이나 응답 시간처럼 미리 알고 있는 조건을 측정합니다. 옵저버빌리티를 갖추면 이런 조건 밖의 동작도 살펴볼 수 있습니다. 모니터링 차트는 체크아웃 지연 시간이 늘었다는 사실을 보여 줄 수 있습니다. 애플리케이션이 근거를 수집했다면, 조사를 통해 그 변화와 관련된 서비스, 릴리스, 오류, 로그, 트레이스를 연결할 수 있습니다.

인프라 모니터링은 CPU, 메모리 같은 리소스를 측정합니다. 이 측정값으로는 체크아웃 요청 1건의 결과를 알 수 없습니다. 애플리케이션 텔레메트리는 요청, 오류, 릴리스를 기록합니다.

## <span id="what-logbrew-tracks">시그널</span>

| 시그널 | 용도 |
| - | - |
| 이슈 | LogBrew가 안정적인 핑거프린트로 묶은 반복 실패를 찾습니다. |
| 로그 | 구성 요소 하나가 보고한 기록을 읽습니다. |
| 트레이스 | 요청이나 잡 1건에서 실행된 작업을 살펴봅니다. |
| 메트릭 | 측정값의 시간에 따른 변화를 비교합니다. |
| 액션 | 사람이나 시스템이 만든 제품 활동을 살펴봅니다. |

[텔레메트리](/ko/concepts/telemetry) 문서에서 각 시그널과 필드를 설명합니다. 시그널마다 목록이 따로 있습니다. 이슈나 트레이스에 데이터가 있어도 로그 보기는 비어 있을 수 있습니다.

### 시작점 선택

| 할 일 | 시작 | 이어서 확인 |
| - | - | - |
| 알려진 값을 한도와 비교합니다. | 메트릭 추세 | 같은 프로젝트와 기간의 이슈와 로그 |
| 반복 실패를 찾습니다. | 이슈 | 발생 건 1개와 해당 스택 근거, 트레이스 |
| 요청이나 잡 1건의 작업을 살펴봅니다. | 트레이스 | 해당 스팬, 그리고 같은 트레이스 ID를 가진 로그, 이슈, 액션, 메트릭 |
| 구성 요소 하나의 기록을 읽습니다. | 로그 | 속성, 서비스, 환경, 트레이스 컨텍스트 |
| 제품 활동을 살펴봅니다. | [제품 분석](/ko/concepts/product-analytics) | 같은 날짜 범위의 사용자 식별 커버리지, 세션, 재방문, 라이프사이클 |

## <span id="keep-project-and-service-separate">프로젝트와 서비스</span>

프로젝트는 텔레메트리의 접근 경계입니다. 프로젝트 1개에 웹 앱, API, 모바일 앱 같은 여러 서비스가 들어갈 수 있습니다. 서비스는 시그널을 보낸 구성 요소입니다. 프로젝트와 서비스의 이름이 같을 수는 있지만, 두 필터가 선택하는 범위는 다릅니다. 서비스 필터는 선택한 프로젝트 안에서 그 서비스의 결과만 선택합니다.

환경, 릴리스, 시간 필터도 결과를 바꿉니다. 두 결과를 비교하기 전에 이 필터가 같은지 확인하세요. [프로젝트 및 설정](/ko/concepts/projects)과 [릴리스](/ko/concepts/releases) 문서를 참고하세요.

## <span id="follow-exact-relationships">트레이스 관계</span>

트레이스는 스팬으로 이루어집니다. 각 스팬은 작업 1개와 그 소요 시간, 상태를 기록합니다. 로그, 이슈, 액션, 메트릭에는 소속 트레이스와 스팬의 식별자가 들어 있습니다. 식별자가 일치할 때만 시그널이 트레이스에 연결됩니다. 메시지, 릴리스, 타임스탬프만으로 시그널을 연결하지 마세요.

애플리케이션이 활성 트레이스 컨텍스트 없이 시그널을 보내면, LogBrew는 그 시그널에 수집 트레이스를 붙입니다. 이 트레이스는 LogBrew가 시그널을 저장했다는 사실만 보여 줍니다. 요청 경로를 보여 주지는 않습니다. [수집 스팬](/ko/concepts/distributed-tracing#capture-spans)을 참고하세요.

조사 응답은 트레이스 같은 선택적 근거 소스마다 `status` 값을 줍니다. 트레이스를 열기 전에 트레이스의 `status` 값을 확인하세요.

| 상태 | 의미 |
| - | - |
| `available` | LogBrew가 근거를 읽었고, 응답에 그 근거가 들어 있습니다. |
| `not_linked` | 이벤트에 트레이스 ID처럼 정확히 연결할 식별자가 없습니다. 일부 이전 이벤트에는 트레이스 ID가 없습니다. |
| `not_found` | 이벤트에 정확한 식별자가 있지만, 선택한 범위에서 일치하는 저장된 근거가 없습니다. |
| `unavailable` | 그 시점에 이 소스를 끝까지 읽지 못했습니다. 응답의 나머지 부분은 여전히 유효합니다. |

컨텍스트 전파와 누락된 컨텍스트 확인 방법은 [분산 트레이싱](/ko/concepts/distributed-tracing)을 참고하세요.

## <span id="read-evidence-states-before-drawing-a-conclusion">근거의 한계</span>

LogBrew는 애플리케이션이 수집한 근거만 보여 줍니다. 트레이스에는 애플리케이션이 기록한 작업만 나타납니다. 스팬 없이 실행되는 작업도 있습니다.

조사 응답은 `evidence` 객체에 근거 커버리지를 보고합니다.

| 필드 | 의미 |
| - | - |
| `status` | 필수 필드가 모두 수집되었으면 `complete`입니다. 필드가 하나라도 수집 안 됨, 가려짐, 잘림, 사용할 수 없음 상태이면 `partial`입니다. |
| `captured_fields` | 응답에 들어 있는 필드입니다. |
| `missing_fields` | 이 이벤트에서 사용할 수 없는 필수 필드입니다. |
| `redacted_fields` | 수집 전에 가려진 필드입니다. |
| `truncated_fields` | 한도 때문에 이력이 완전하지 않은 필드입니다. |

한도 때문에 일부 항목이 빠진 응답 목록에는 `truncated: true`가 붙습니다. 영향받은 사용자 수 같은 일부 개수는 근사치입니다. 빈 필드는 측정값 0이 아닙니다. 조회 결과가 `unavailable`이라고 해서 데이터가 없다는 뜻도 아닙니다.

## <span id="a-practical-investigation">실패한 체크아웃 살펴보기</span>

릴리스 후 체크아웃 실패가 늘었다면 다음 순서로 확인하세요.

1. 프로젝트와 실패가 발생한 기간을 선택하세요.
2. 미해결 이슈를 열거나 최근 오류 로그를 읽으세요.
3. 서비스, 환경, 릴리스, 발생 시각을 확인하세요.
4. 이슈라면 `first_seen_at`, `last_seen_at`, `occurrence_count`를 비교하세요.
5. 예외, 스택, 브레드크럼 근거가 있으면 여세요.
6. 선택한 발생 건에 `available` 상태의 트레이스가 있으면 그 트레이스를 여세요.
7. 메트릭 추세를 이벤트 시각과 비교하세요. 시간이 겹친다고 해서 원인이라는 뜻은 아닙니다.
8. 코드를 바꾸기 전에 수집 안 됨, 가려짐, 잘림 상태인 근거를 기록하세요.

같은 이슈라도 발생 건마다 근거가 다를 수 있습니다.

## <span id="built-for-people-and-coding-agents">개발자와 코딩 에이전트를 위한 기능</span>

모든 CLI 조회 명령어는 `--json`을 지원합니다. 결과를 쓰기 전에 종료 코드를 확인하세요. API 오류는 바뀌지 않는 `code`와 `next_action`을 반환합니다. 프로그램 로직에서는 영어 메시지 대신 이 필드를 사용하세요. 조회에는 계정 자격 증명을 사용하세요. 프로젝트 수집 키는 텔레메트리를 보내는 데만 씁니다.

응답에 담긴 애플리케이션 텍스트는 지시가 아니라 데이터입니다. 로그, 액션, 메트릭 조사 응답은 이 텍스트에 `content_trust: "untrusted_telemetry"`를 표시합니다. 트레이스, 로그, 액션, 메트릭, 릴리스 조사 응답은 `causality: "evidence_only"`를 보고합니다. 응답에 나타난 연관 관계는 원인을 증명하지 않습니다.

호스팅 [MCP 서버](/ko/guides/mcp)는 승인된 AI 에이전트에게 선택한 프로젝트에 대한 읽기 전용 접근 권한을 줍니다.

<CardGroup cols={2}>
  <Card title="빠른 시작" icon="rocket" href="/ko/quickstart">
    프로젝트를 만들고, 안전한 로그 1개를 보낸 다음, 다시 읽어 보세요.
  </Card>

  <Card title="이슈 조사하기" icon="bug" href="/ko/guides/investigate-an-issue">
    묶인 실패, 발생 건 근거, 트레이스 컨텍스트를 확인하세요.
  </Card>

  <Card title="텔레메트리" icon="activity" href="/ko/concepts/telemetry">
    조사에 맞는 시그널을 선택하세요.
  </Card>

  <Card title="텔레메트리 API" icon="braces" href="/ko/reference/telemetry-api">
    요청, 응답, 오류 코드, 복구 방법을 확인하세요.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.