> ## 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는 앱이 보내는 제품 액션을 읽습니다. 여기에는 페이지 조회, 화면 조회, 상호작용이 포함됩니다. 이 이벤트를 사용자 및 세션 컨텍스트와 함께 보내려면 [제품 이벤트 수집](/ko/guides/product-events)을 사용하세요.

모든 결과는 프로젝트 1개와 기간 1개를 기준으로 합니다. 서비스 이름으로는 프로젝트를 선택할 수 없습니다. 로그와 이슈는 별개의 시그널입니다. 로그나 이슈가 있다고 해서 같은 기간에 분석 데이터가 있다는 뜻은 아닙니다.

## 이벤트, 사용자, 세션

| 단위 | 의미 |
| - | - |
| 이벤트 | 기록된 액션 1개입니다. 한 사람이 이벤트를 여러 개 보낼 수 있습니다. |
| 식별된 사용자 | 앱이 제공하는 고정된 불투명 주체 ID이며 종류는 `user`입니다. |
| 익명 주체 | 사용자가 아닌, 종류가 지정된 주체 ID입니다. 사용자로 세지 않습니다. |
| 세션 | 앱이 명시적으로 제공하는 세션 ID입니다. 한 사람에게 세션이 여러 개 있을 수 있습니다. |

예를 들어 세션 20개에서 액션 200개가 나왔다고 해서 20명이 앱을 사용했다는 뜻은 아닙니다. 이벤트 합계는 선택한 기간에 대해 정확한 값입니다. 고유 사용자, 세션, 익명 주체 수는 근사치입니다.

불투명 ID를 사용하세요. 이름, 이메일 주소 등 개인정보를 ID로 사용하지 마세요. 분석 응답은 원본 사용자 ID나 세션 ID를 반환하지 않습니다.

## 대시보드 개요 열기

1. LogBrew 대시보드에서 **분석**을 여세요.
2. 프로젝트 1개를 선택하세요.
3. **24시간**, **7일**, **14일**, **30일**, **직접 지정** 중 하나를 선택하세요.
4. 활동 차트를 읽은 다음 **상위 이벤트**와 **상위 화면**을 읽으세요.
5. 사용자 수를 읽기 전에 **범위와 한도**를 여세요.

**직접 지정**에서는 첫날과 마지막 날을 선택한 다음 **적용**을 선택하세요. 두 날짜 모두 기간에 포함됩니다. 예를 들어 4월 12일부터 4월 16일까지는 5일입니다. 대시보드는 UTC 날짜를 사용합니다. 직접 지정한 기간은 최대 31일이며 미래 날짜를 포함할 수 없습니다.

대시보드는 같은 프로젝트와 날짜에 대한 사용자 추세 2개도 보여 줍니다. \*\*사용자가 다시 돌아오나요?\*\*는 재방문을 보여 줍니다. \*\*사용자층은 어떻게 변하고 있나요?\*\*는 라이프사이클 그룹을 보여 줍니다. 두 추세 모두 식별된 사용자의 분류된 활동 전체를 사용합니다. 따로 이벤트를 선택하지 않습니다.

## <span id="use-the-analytics-api">프로젝트 개요 읽기</span>

```bash theme={null}
logbrew analytics overview --project "<project_id>" --since 7d --json
```

끝 시각(포함하지 않음)을 지정하려면 `--until <RFC3339>`를 추가하세요. `--interval`에는 `auto`, `1m`, `5m`, `15m`, `1h`, `6h`, `1d`를 쓸 수 있습니다. `--top-limit`은 각 상위 목록의 행 수를 `1`부터 `20`까지 정합니다. 기본값은 `10`입니다. 정확한 컨텍스트로 필터링하려면 `--service`, `--release`, `--environment`를 추가하세요. API 엔드포인트는 `GET /api/telemetry/analytics/overview`입니다.

개요에는 활동 합계, 시계열, 상위 액션, 분류된 활동이 들어 있습니다. 다음 발췌는 합계와 그 커버리지를 보여 줍니다.

```json theme={null}
{
  "schema_version": 3,
  "analysis_level": "user_and_session",
  "summary": {
    "actions": 120,
    "active_identified_users": 18,
    "active_anonymous_subjects": 7,
    "sessions": 24
  },
  "coverage": {
    "identified_actions": 100,
    "anonymous_actions": 20,
    "subject_coverage": {
      "index_version": 1,
      "identified_user_events": 100,
      "anonymous_subject_events": 8,
      "legacy_unknown_kind_events": 4,
      "missing_subject_events": 6,
      "historical_unindexed_events": 2
    },
    "sessionized_actions": 90,
    "traced_actions": 60,
    "top_actions_truncated": true
  },
  "next_action": { "code": "build_product_funnel" }
}
```

`subject_coverage`의 다섯 값을 더하면 `summary.actions`가 됩니다. 사용자 수에 들어가는 값은 `identified_user_events`뿐입니다. `anonymous_actions`에는 나머지 네 상태가 포함됩니다. 이 예에서 익명 주체 이벤트 8개는 서로 다른 익명 주체 약 7개에서 나옵니다. 두 숫자 모두 사용자 수가 아닙니다. 상위 목록이 잘렸다고 해서 양이 적은 이벤트가 없다는 뜻은 아닙니다.

`analysis_level`은 `no_data`, `event_only`, `user_level`, `user_and_session` 중 하나입니다. 데이터로 답할 수 있는 질문의 수준을 보여 줍니다. 이 수준은 `summary`와 `classified_activity` 중 어느 한쪽이 뒷받침하는 가장 높은 수준입니다. 두 그룹 모두에 사용자나 세션이 있다는 뜻은 아닙니다.

### 두 활동 그룹을 섞지 마세요

| 응답 필드 | 세는 이벤트 |
| - | - |
| `summary`, `coverage`, `series`, `top_actions` | 제품 액션 이벤트입니다. 지원되는 분류가 없는 액션도 포함합니다. |
| `classified_activity` | 페이지 조회, 화면 조회, 상호작용입니다. 페이지 조회는 액션이 아닙니다. |

분류된 화면 조회와 상호작용은 액션이기도 합니다. `summary.actions`와 `classified_activity.summary.events`를 더하지 마세요. 사용하는 그룹의 커버리지를 읽으세요. `classified_activity.coverage.subject_coverage`의 주체 수를 더하면 `classified_activity.summary.events`가 됩니다.

분류된 페이지 조회가 사용자 수와 세션 수를 제공하는 동안에도 `summary.actions`는 `0`일 수 있습니다. 제품 활동이 없다고 판단하기 전에 `classified_activity`를 확인하세요.

### 다음 액션 따르기

`next_action`에는 `code`, `target`, `reason`이 있습니다. 가장 중요한 수집 공백이나 다음 분석 단계를 보여 줍니다.

| `next_action.code` | 의미 |
| - | - |
| `capture_product_activity` | 범위에 맞는 제품 이벤트가 없습니다. |
| `classify_product_activity` | 이벤트는 있지만 페이지 조회, 화면 조회, 상호작용이 하나도 없습니다. |
| `identify_product_users` | 종류가 `user`인 주체를 가진 이벤트가 없습니다. |
| `sessionize_product_activity` | 세션 ID가 있는 이벤트가 없습니다. |
| `capture_funnel_steps` | 이름이 있는 분류된 이벤트가 2개보다 적습니다. |
| `build_product_funnel` | 데이터로 퍼널을 만들 수 있습니다. |

앱에서 수집 방식을 바꾼 다음 새 이벤트를 확인하세요. 이전 이벤트로는 변경이 효과가 있는지 알 수 없습니다.

### API 직접 호출하기

계정 bearer 토큰을 보내세요. CLI가 읽는 것과 같은 응답을 받으려면 `response_version=3`을 보내세요. `response_version`을 생략하면 API는 버전 `1`을 반환하며, 여기에는 익명 주체 수와 `subject_coverage`가 없습니다.

```bash theme={null}
curl -sS -G "https://api.logbrew.co/api/telemetry/analytics/overview" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  --data-urlencode "project_id=<project_id>" \
  --data-urlencode "since=7d" \
  --data-urlencode "response_version=3"
```

`since`는 `24h`, `7d`, `30d` 같은 양의 기간이거나 RFC3339 타임스탬프입니다. `until`은 선택 사항인 RFC3339 타임스탬프입니다. 기간에는 `since`가 포함되고 `until`은 포함되지 않습니다. `until`을 생략하면 요청 시각에 기간이 끝납니다. 기간은 31일보다 길 수 없습니다.

2026년 4월 12일부터 4월 16일까지라면 `since`로 `2026-04-12T00:00:00Z`를, `until`로 `2026-04-17T00:00:00Z`를 보내세요.

기간이 31일보다 길면 HTTP `422`를 반환합니다.

```json theme={null}
{
  "error": "product analytics range must not exceed 31 days",
  "code": "validation_failed",
  "next": "use a shorter range or query consecutive bounded windows",
  "next_action": { "code": "fix_request", "target": "request" }
}
```

프로그램 로직에서는 `code`와 `next_action`을 읽으세요. 사람에게는 `error`와 `next`를 보여 주세요. 다른 오류 응답은 [API 오류](/ko/reference/api-errors)에 나와 있습니다.

아래 `POST` 분석 경로는 같은 `project_id`, `since`, `until`, `service_name`, `release`, `environment` 필드가 담긴 JSON 본문을 받습니다. 알 수 없는 본문 필드는 거부됩니다.

## <span id="measure-a-funnel">퍼널 측정하기</span>

퍼널은 순서가 정해진 단계 2\~8개를 거치는 전환을 측정합니다.

```bash theme={null}
logbrew analytics funnel --project "<project_id>" --since 7d \
  --step page-view /pricing \
  --step interaction checkout_started \
  --step interaction checkout_completed \
  --json
```

뒤 단계는 앞 단계보다 늦은 타임스탬프를 가져야 합니다. 이벤트 1개로 두 단계를 완료할 수 없습니다. 기본 단위는 세션입니다. 여러 세션에 걸쳐 사용자를 세려면 `--unit identified-user`를 사용하세요. 이벤트 이름은 개요에서 복사하세요. 서로 관련 없는 두 합계의 비율은 전환율이 아닙니다.

마지막 단계는 첫 단계에서 시작하는 전환 기간 안에 일어나야 합니다. 이 기간은 `--conversion-window`로 설정하세요. 예를 들면 `30m`이나 `1h`입니다. 기본값은 24시간이며, 전체 기간이 이보다 짧으면 전체 기간입니다. 전환 기간은 전체 기간보다 길 수 없습니다.

API 경로는 `POST /api/telemetry/analytics/funnel`입니다. 요청 본문과 응답은 [순서가 있는 퍼널 응답](/ko/reference/telemetry-response-shapes#ordered-funnel-response)에 나와 있습니다.

## 이벤트 1개 전후의 경로 살펴보기

경로는 기준 이벤트 1개 뒤나 앞에서 가장 자주 나오는, 이름이 있는 이벤트의 순서를 보여 줍니다.

```bash theme={null}
logbrew analytics paths following --project "<project_id>" --since 24h \
  --anchor-kind page-view --anchor-event /pricing \
  --json
```

기준 이벤트 앞의 이벤트를 보려면 `following` 대신 `preceding`을 사용하세요. `--depth`는 그쪽 이벤트 수를 `1`부터 `8`까지 정합니다. 기본값은 `4`입니다. `--path-limit`은 경로 수를 `1`부터 `20`까지 정합니다. 기본값은 `10`입니다. 연달아 나온 같은 이벤트는 1개로 셉니다. 각각을 유지하려면 `--keep-repeated`를 추가하세요.

경로는 세션 ID를 사용합니다. 뒤쪽 경로는 각 세션의 첫 기준 이벤트에서 시작합니다. 앞쪽 경로는 마지막 기준 이벤트에서 끝납니다. 경로는 사용자를 세지 않으며, 액션이 왜 실패했는지도 보여 주지 않습니다. API 경로는 `POST /api/telemetry/analytics/paths`입니다.

## 재방문 읽기

재방문은 식별된 사용자가 시작 이벤트 뒤에 다시 돌아오는지 보여 줍니다.

```bash theme={null}
logbrew analytics retention --project "<project_id>" --since 30d \
  --start-kind page-view --start-event /signup \
  --return-kind interaction --return-event report_opened \
  --json
```

`--interval`은 `hour`, `day`, `week`, `thirty-day` 중 하나입니다. `thirty-day`는 달력상의 한 달이 아니라 30일입니다. `--interval-count`는 `1`부터 `31`까지입니다. 기본값은 `10`입니다. `--mode return-on`은 각 기간 안의 재방문만 셉니다. `return-on-or-after`는 각 기간 안이나 그 뒤의 재방문을 셉니다.

재방문은 사용자의 시작 이벤트 뒤에 일어나야 합니다. 각 사용자는 기간 안의 첫 시작 이벤트에서 한 번만 시작합니다. 이 이벤트가 그 사용자의 맨 첫 이벤트라는 보장은 없습니다. 한 기간에 여러 번 돌아온 사용자는 그 기간에 한 번만 셉니다.

각 기간의 재방문 수는 대상 사용자 수와 함께 읽으세요. 아직 기간이 끝나지 않은 사용자는 대상이 아닙니다. 이탈한 사용자로 세지 않습니다. 예를 들어 대상 사용자 100명 중 40명이 돌아왔다면 재방문율은 40%입니다. 재방문율이 낮아도 사람들이 떠난 이유는 알 수 없습니다.

### 모든 활동의 재방문 요청하기

API 경로는 `POST /api/telemetry/analytics/retention`입니다. 이벤트 이름 없이 재방문을 측정하려면 `response_version`으로 `2`를 보내고 `start_event`와 `return_event`를 생략하세요.

```bash theme={null}
curl -sS "https://api.logbrew.co/api/telemetry/analytics/retention" \
  -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project_id>",
    "since": "14d",
    "response_version": 2,
    "interval": "day",
    "interval_count": 10,
    "mode": "return_on",
    "cohort_mode": "first_in_range"
  }'
```

응답은 `query.activity_scope`를 `all_classified_activity`로 설정합니다. 뒤에 일어난 페이지 조회, 화면 조회, 상호작용은 모두 재방문으로 셉니다. 이벤트를 선택하려면 `response_version`을 생략하고 `start_event`와 `return_event`를 모두 `{ "kind": "page_view", "event_name": "/signup" }` 형식으로 보내세요.

전체 기간을 간격으로 나눈 값에 `interval_count`를 곱한 결과는 500 이하여야 합니다. 예를 들어 14일에 `day`와 기간 `10`개를 쓰면 140입니다. `interval`을 생략하면 API는 48시간까지의 기간에는 `hour`를, 더 긴 기간에는 `day`를 사용합니다.

## 라이프사이클 읽기

라이프사이클은 이벤트 1개를 수행한 식별된 사용자를 기간마다 그룹 1개에 넣습니다.

```bash theme={null}
logbrew analytics lifecycle --project "<project_id>" --since 30d \
  --event-kind interaction --event report_opened \
  --json
```

| 그룹 | 의미 |
| - | - |
| 관측 기록 내 신규 | 지금 활동 중이며, 기록 기간 안에 이전 이벤트가 없습니다. |
| 계속 활동 | 지금과 이전 기간 모두 활동했습니다. |
| 복귀 | 공백 뒤에 지금 다시 활동 중입니다. |
| 휴면 | 이전 기간에는 활동했지만 지금은 활동하지 않습니다. |

관측 기록 내 신규는 처음 온 고객이라는 뜻이 아닙니다. 이전 활동이 `--history-periods`로 설정한 기록 기간 밖에 있을 수 있습니다. 전체 기간의 고유 사용자를 세려고 기간별 합계를 더하지 마세요.

`--history-periods`는 `since` 이전의 기간 `2`\~`31`개입니다. 기본값은 `2`입니다. 기록은 62일보다 길 수 없습니다. 전체 기간에는 최대 100개의 기간이 들어갈 수 있습니다. 각 기간에는 `fully_observed`가 있으며, 기간이 끝나지 않았으면 `false`입니다. 휴면은 현재 기간에 활동하지 않았다는 뜻이지, 영구적으로 이탈했다는 뜻이 아닙니다.

API 경로는 `POST /api/telemetry/analytics/lifecycle`입니다. 이벤트 1개 대신 분류된 활동 전체를 사용하려면 `response_version`으로 `2`를 보내고 `event`를 생략하세요.

```json theme={null}
{
  "project_id": "<project_id>",
  "since": "30d",
  "response_version": 2,
  "interval": "day",
  "history_period_count": 7
}
```

## 두 기간 비교하기

각 기간을 따로 요청하세요. 같은 프로젝트, 같은 길이, 같은 이벤트 이름과 필터를 사용하세요. 사용자 수를 비교하기 전에 활동, 이벤트 구성, 식별 및 세션 커버리지를 먼저 비교하세요. 끝나지 않은 기간은 끝난 기간보다 활동이 적게 보일 수 있습니다.

| 관찰 | 다음 확인 | 한계 |
| - | - | - |
| 이벤트 1개가 늘었습니다 | 그 이벤트의 세션과 커버리지를 확인하세요. | 이벤트가 늘었다고 사람이 늘었다는 뜻은 아닙니다. |
| 전환율이 바뀌었습니다 | 두 기간에 같은 퍼널 단계와 단위를 사용하세요. | 정의가 다른 퍼널끼리 비교하지 마세요. |
| 계속 활동 사용자가 줄었습니다 | 대상 사용자와 끝난 기간을 확인하세요. | 최근 코호트는 오래된 코호트보다 나빠 보일 수 있습니다. |
| 사용자가 한 단계에서 멈춥니다 | 그 단계의 이슈와 로그를 읽으세요. | 기간이 겹친다고 원인이 드러나지는 않습니다. |

결과가 실패를 가리키면 같은 프로젝트와 시간대의 관련 이슈와 로그를 읽으세요. 이벤트에 정확한 트레이스 링크가 있을 때만 트레이스를 여세요. 기간이 겹친다고 해서 오류가 감소의 원인이라는 뜻은 아닙니다.

비교를 반복하려면 프로젝트 ID, 두 UTC 기간, 간격, 필터, 단위, 커버리지, 잘림 상태를 기록하세요. 원본 사용자 ID는 기록하지 마세요.

응답 필드와 오류는 [텔레메트리 API](/ko/reference/telemetry-api)와 [API 오류](/ko/reference/api-errors)를 읽으세요.


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