> ## 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 시그널을 선택하세요.
텔레메트리는 애플리케이션이 자신의 동작에 관해 보내는 구조화된 근거입니다. 로그는 보고된 이벤트를 기록합니다. 트레이스는 작업을 서로 연결합니다. 메트릭은 값을 측정합니다. 이슈는 실패를 묶습니다. 액션은 제품 활동을 기록합니다.
프로젝트, 서비스, 환경, 릴리스, 시간 필드가 각 결과의 범위를 정합니다. SDK가 수집하는 시그널은 [SDK 연동](/ko/guides/sdk-ingestion) 문서를 참고하세요.
## 시그널 선택
| 시그널 | 용도 |
| - | - |
| 이슈 | 18번 발생한 체크아웃 예외 같은 반복 실패입니다. |
| 로그 | 결제 실패처럼 앱이 보고한 이벤트 1건입니다. |
| 트레이스 | 계측된 여러 서비스를 거치는 요청 1건의 작업과 소요 시간입니다. |
| 메트릭 | 요청 소요 시간이나 완료된 잡 수처럼 시간에 따라 측정한 값입니다. |
| 액션 | 페이지 조회, 화면 조회, 상호작용 같은 제품 활동입니다. |
실패 조사는 이슈나 로그에서 시작하세요. 실행 1회를 살펴보려면 사용할 수 있는 트레이스를 여세요. 더 넓은 기간을 살펴보려면 메트릭 추세를 보세요. 활동과 재방문은 [제품 분석](/ko/concepts/product-analytics)을 참고하세요.
조사에 필요한 필드만 수집하세요. 서비스, 작업, 메트릭 이름은 바뀌지 않게 정하세요. 자격 증명, 결제 데이터, 가공하지 않은 요청 본문은 보내지 마세요. 수집 데이터를 제어하는 방법은 [수집 데이터 관리하기](/ko/guides/safe-capture) 문서에 있습니다.
## 로그
로그는 애플리케이션이 특정 시점에 남긴 기록입니다. 유용한 로그에는 다음이 들어 있습니다.
* 이벤트의 발생 시각
* 표준 심각도
* 프로젝트와 서비스 범위
* 환경과 릴리스
* 로그에 활성 트레이스 컨텍스트가 있으면 트레이스와 스팬 식별자
* 이벤트 컨텍스트를 담은, 이름이 붙은 작은 속성
로그 응답에서는 이 값이 `occurred_at`, `severity`, `project_id`, `service_name`, `environment`, `release`, `trace_id`, `span_id`, `attributes`에 들어 있습니다. 컨텍스트는 메시지 텍스트가 아니라 이름이 붙은 속성에 넣으세요.
여러 서비스의 로그가 한 화면에 함께 보여도 트레이스 관계가 있는 것은 아닙니다. 트레이스 관계는 트레이스 컨텍스트로만 생깁니다.
## 트레이스
트레이스는 요청이나 작업 1건의 스팬으로 이루어집니다. 루트 스팬에는 부모가 없습니다. 자식 스팬은 자신의 부모를 가리킵니다. 한 트레이스의 모든 스팬은 트레이스 ID가 같고 스팬 ID는 서로 다릅니다. [분산 트레이싱](/ko/concepts/distributed-tracing)을 참고하세요.
활성 트레이스 컨텍스트 없이 보낸 로그, 이슈, 액션, 메트릭에는 수집 트레이스가 붙습니다. 이 트레이스에는 수집 스팬만 들어 있습니다. 요청 경로를 보여 주지는 않습니다. [수집 스팬](/ko/concepts/distributed-tracing#capture-spans)을 참고하세요.
## 메트릭
메트릭은 시간에 따라 측정한 값을 기록합니다. 메트릭은 항상 이름, 단위, 차원, 프로젝트, 기간, 간격과 함께 읽으세요. LogBrew는 메트릭의 `kind`와 `temporality`에 따라 각 데이터 포인트의 `value`를 정합니다.
| 메트릭 정의 | `aggregation.code` | 데이터 포인트 `value` |
| - | - | - |
| `gauge`와 `instant` | `gauge_last` | 큐 깊이처럼 간격 안의 마지막 상태입니다. |
| `counter`와 `delta` | `delta_sum` | 완료된 잡 수처럼 간격 안 변화량의 합입니다. |
| `histogram`과 `delta` | `distribution_p95` | 요청 소요 시간처럼 대략적인 95번째 백분위수입니다. |
| `cumulative` 스트림 | `raw_cumulative_last` | 마지막 원시 누적값입니다. 변화율이 아닙니다. |
| 그 밖의 조합 | `raw_last` | 마지막 원시 샘플입니다. |
예를 들어 한 간격에 값이 `2`, `3`, `5`인 delta 카운터 샘플 3개가 있으면 데이터 포인트의 `value`는 `10`, `sample_count`는 `3`입니다. 같은 값을 같은 순서로 가진 게이지 샘플 3개라면 `value`는 `5`입니다. p95 값은 평균이 아닙니다. 기록된 관측값의 약 95%가 이 값 이하입니다.
`status: "ready"`이면 계산된 집계를 쓸 수 있습니다. `status: "limited"`이면 `aggregation.limitation`을 읽고 원시 값만 사용하세요. 게이지나 누적 스트림은 합산하지 마세요. 데이터 포인트가 없는 간격은 측정값 0이 아닙니다. 쿼리 필드는 [쿼리 필터](/ko/reference/telemetry-api-filters)를 참고하세요.
`GET /api/telemetry/metrics/series`가 이 데이터 포인트를 반환합니다. 이 요청에는 `project_id`, `name`, `since`가 필요합니다. 각 시계열에는 `kind`, `unit`, `temporality`로 이루어진 `identity`가 1개 있습니다. `identity`가 다른 시계열은 따로 유지됩니다. 각 데이터 포인트에는 다음 필드도 들어갈 수 있습니다.
| 필드 | 의미 |
| - | - |
| `min`, `max`, `average` | 간격 안 샘플의 범위와 평균입니다. |
| `p50`, `p95`, `p99` | 히스토그램의 대략적인 백분위수입니다. |
| `rate_per_second` | delta 카운터의 합계를 간격 길이로 나눈 값입니다. |
| `trace_exemplars` | 이 간격에서 샘플링한 트레이스 ID입니다. 하나를 열어 그 간격의 요청을 살펴보세요. |
`series_limit` 때문에 양이 적은 시계열이 빠지면 `coverage.truncated`가 `true`입니다. 메트릭 기간을 같은 길이의 직전 기간과 비교하려면 다음을 실행하세요.
```bash theme={null}
logbrew explain metric '' --project '' --since 24h --json
```
## 이슈
이슈는 반복되는 실패를 안정적인 핑거프린트로 묶습니다. 이슈에는 심각도, 상태, 발생 횟수, 최초 발생 시각, 마지막 발생 시각이 있습니다. 이슈 상세 정보에는 예외 체인, 스택 프레임, 브레드크럼, 관련 로그, 트레이스 관계가 추가될 수 있습니다.
`last_seen_at`은 그룹에서 가장 최근 발생 건의 시각입니다. 선택한 발생 건은 이보다 오래되었을 수 있습니다. 두 시각을 모두 확인하세요.
이슈의 `status`는 `unresolved`, `resolved`, `archived` 중 하나입니다. API 응답 버전 1에서는 `archived`가 `ignored`로 표시됩니다. 응답 버전 2와 3에는 `priority`(`high`, `medium`, `low`)와 `priority_source`가 추가됩니다. 버전 3에는 `assignee`도 추가됩니다. [상태 값](/ko/guides/issue-workflow#status-values)과 [우선순위](/ko/guides/issue-workflow#priority)를 참고하세요.
## 액션
액션은 제품 활동을 기록합니다. 지원되는 분류에 따라 액션은 페이지 조회, 화면 조회, 상호작용 중 하나로 표시됩니다. 이벤트 이름만으로는 분류가 정해지지 않습니다. 이 컨텍스트를 추가하려면 [제품 이벤트 수집](/ko/guides/product-events)을 참고하세요.
세션은 사용자가 아닙니다. 익명 주체는 식별된 사용자가 아닙니다.
## 공통 필드
| 필드 | 용도 |
| - | - |
| `project_id` | 텔레메트리를 소유하고 조회 경계를 정합니다. |
| `service_name` | 시그널을 보낸 앱이나 서비스를 식별합니다. |
| `environment` | 프로덕션, 스테이징, 프리뷰, 로컬 데이터를 구분합니다. |
| `release` | 배포된 코드 버전을 식별합니다. |
| `occurred_at` | 로그나 액션 1건의 발생 시각입니다. 스팬은 `started_at`을 씁니다. |
| `trace_id` | 같은 트레이스 컨텍스트에서 수집된 시그널을 연결합니다. |
| `span_id` | 시그널이 속한 트레이스 안의 스팬을 식별합니다. |
## 심각도 값
| 표준 값 | 허용되는 입력 별칭 |
| - | - |
| `info` | `trace`, `debug`, `info` |
| `warning` | `warn`, `warning` |
| `error` | `error` |
| `critical` | `fatal`, `critical` |
LogBrew는 별칭을 대소문자 구분 없이 입력으로 받습니다. API, CLI, 실시간 이벤트는 표준 값을 사용합니다. 알 수 없는 심각도 값은 거부됩니다. 심각도는 기록된 긴급도입니다. 비즈니스 영향이나 근본 원인을 나타내지 않습니다.
사용자는 이슈나 로그에 표시되는 심각도를 바꿀 수 있습니다. 그러면 응답에 `effective_severity`가 담긴 `triage` 객체가 들어갑니다. `severity` 필드에는 수집된 원래 값이 남습니다.
## 실시간 조회와 스냅샷 조회
`logbrew read`는 선택한 프로젝트, 기간, 필터의 스냅샷을 반환합니다. 새 이벤트를 읽으려면 다시 실행하세요. `logbrew watch`는 연결이 열려 있는 동안 새 로그, 이슈, 액션을 스트리밍합니다. 트레이스와 메트릭은 스트리밍하지 않습니다. 연결에 실패했다고 해서 프로젝트가 비어 있다는 뜻은 아닙니다.
## 근거 상태
응답은 수집됨, 수집 안 됨, 가려짐, 잘림, 사용할 수 없음 상태를 서로 구분합니다. 트레이스 근거의 상태는 `available`, `not_linked`, `not_found`, `unavailable` 4가지입니다. 각 상태의 의미는 [개요](/ko/introduction#follow-exact-relationships)를, 커버리지 필드는 [근거의 한계](/ko/introduction#read-evidence-states-before-drawing-a-conclusion)를 참고하세요. SDK를 새 버전으로 올려도 이전에 보낸 이벤트에 필드가 추가되지는 않습니다.
## 프로젝트 1개 조사하기
```bash theme={null}
logbrew read issues --project '' --status unresolved --since 24h --json
```
이 명령어는 보존된 이슈 이력을 읽습니다. 목록 조회에 쓴 `--since` 필터는 적용되지 않습니다.
```bash theme={null}
logbrew investigate issue '' --json
```
선택한 발생 건이 트레이스 ID를 반환할 때만 그 ID를 사용하세요.
```bash theme={null}
logbrew read trace '' --project '' --json
```
같은 프로젝트, 서비스, 환경, 릴리스로 로그, 액션, 메트릭을 필터링하세요. 시간만으로 시그널을 연결하지 마세요.
응답 필드는 [텔레메트리 API](/ko/reference/telemetry-api)와 [응답 형식](/ko/reference/telemetry-response-shapes)을 참고하세요.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.