> ## 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 옵저버빌리티 빠른 시작으로 Node.js 로깅하기

> 프로젝트를 만들고 Node.js 로깅을 설정하세요. 안전한 SDK 이벤트 1개를 보내고, 자격 증명을 노출하지 않고 저장된 로그를 읽으세요.

개발용 프로젝트를 만드세요. Node.js 로그 1개를 보내세요. LogBrew에서 그 로그를 다시 읽으세요. CLI가 프로젝트를 만들고 수집 키를 저장합니다. CLI에 유효한 계정 접근 권한이 없을 때만 브라우저 로그인이 필요합니다.

<Note>
  에이전트 워크플로에는 `--json`을 사용하세요. 자격 증명은 보호된 로컬 설정에 보관하세요. 사람, 도구, 에이전트 사이에는 변수 이름만 전달하세요.
</Note>

## <span id="first-project-success-path">시작하기 전에</span>

다음을 준비하세요.

* Node.js 18 이상
* LogBrew CLI v0.1.30 이상
* `jq`
* Bash 또는 Zsh
* 서버 측 Node.js 앱의 패키지 디렉터리

예제는 프로젝트 `quickstart-node`, 환경 `development`, 릴리스 `quickstart@1`을 사용합니다. 이 테스트는 프로덕션과 분리하세요. 다른 런타임은 [SDK 연동](/ko/guides/sdk-ingestion)을 참고하세요.

<Warning>
  수집 키 파일은 저장소 밖에 두고, 나만 읽을 수 있게 하세요. 이 서버 키를 브라우저 코드, 공개 번들, 프롬프트에 넣지 마세요.
</Warning>

## 첫 로그 보내고 읽기

<Steps>
  <Step title="계정 상태 확인하기" id="confirm-account-access">
    [CLI 사용하기](/ko/guides/cli)의 명령어로 CLI를 설치하세요. 그다음 계정 상태를 확인하세요.

    ```bash theme={null}
    logbrew status --json
    ```

    **확인:** 상태에 인증된 계정 접근 권한이 표시됩니다. 표시되지 않으면 사람이 `logbrew login`을 한 번 실행합니다. 그다음 `logbrew status --json`을 다시 실행하세요. 현재 인증이 작동하면 에이전트는 새 로그인을 시작하면 안 됩니다.
  </Step>

  <Step title="CLI로 프로젝트 1개 만들기">
    소유자만 접근할 수 있는 디렉터리에 새 파일 경로를 정하세요. CLI는 성공을 보고하기 전에 프로젝트 수집 키를 그 파일에 씁니다. 키나 파일 경로는 절대 출력하지 않습니다.

    ```bash theme={null}
    install -d -m 700 "$HOME/.logbrew"

    project_result="$(
      logbrew projects create quickstart-node \
        --runtime node \
        --environment development \
        --ingest-key-file "$HOME/.logbrew/quickstart-node.ingest" \
        --json
    )"
    export LOGBREW_PROJECT_ID="$(jq -er '.project.id' <<<"$project_result")"
    jq '{status, setup_status: .setup.status, ingest_key_kind: .ingest_key.kind, next}' \
      <<<"$project_result"
    unset project_result
    ```

    프로젝트를 만들면 계정 상태가 바뀝니다. 대상 파일이 이미 있으면 안 됩니다. 결과가 분명하지 않으면 같은 명령어를 그대로 다시 실행하세요. CLI는 대기 중인 요청 식별 정보를 다시 사용합니다. 다른 시도를 시작할 때만 `--abandon-retry`를 사용하세요.

    **확인:** 출력에 `status: "created"`, 설정 상태 `created`, 수집 키 종류가 표시됩니다. 프로젝트가 생겼고 키가 저장되었습니다. 이것만으로 텔레메트리가 전송된다는 것을 확인할 수는 없습니다. [프로젝트 및 설정](/ko/concepts/projects)을 참고하세요.
  </Step>

  <Step title="Node.js SDK 설치하기">
    ```bash theme={null}
    npm install @logbrew/sdk @logbrew/node
    ```

    계정 자격 증명을 SDK 설정으로 쓰지 마세요. 프로젝트 키를 명령어 출력, 프롬프트, 티켓, 소스 파일, 패키지 설정에 넣지 마세요.
  </Step>

  <Step title="안전한 SDK 로그 1개 보내기">
    릴리스와 환경 마커를 자리표시자만 담은 `info` 로그 1개와 함께 보내세요. 키는 이 Node.js 프로세스에서만 설정됩니다. 애플리케이션 식별 정보는 `context`에 넣습니다.

    실행할 때마다 새 이벤트 ID가 만들어집니다. 같은 실행 안에서 SDK가 전송을 재시도하면 같은 본문과 같은 ID를 보냅니다. 이미 접수된 이벤트를 재시도에서 다시 보내도 LogBrew는 그 이벤트를 다시 저장하지 않습니다.

    ```bash theme={null}
    LOGBREW_SERVER_API_KEY="$(< "$HOME/.logbrew/quickstart-node.ingest")" \
      node --input-type=module <<'JS'
    import { randomUUID } from "node:crypto";
    import { SdkError } from "@logbrew/sdk";
    import { createLogBrewNodeClient } from "@logbrew/node";

    const client = createLogBrewNodeClient({
      context: {
        schemaVersion: 1,
        resource: { service: { name: "quickstart-node", version: "quickstart@1" } }
      }
    });
    const occurredAt = new Date().toISOString();

    client.release(randomUUID(), occurredAt, {
      version: "quickstart@1",
      metadata: { service: "quickstart-node" }
    });
    client.environment(randomUUID(), occurredAt, { name: "development" });
    client.log(randomUUID(), occurredAt, {
      message: "LogBrew quickstart check",
      level: "info",
      logger: "quickstart-node"
    });

    try {
      const response = await client.shutdown();
      console.log(JSON.stringify({
        ok: true,
        status_code: response.statusCode,
        attempts: response.attempts
      }));
    } catch (error) {
      console.error(JSON.stringify({
        ok: false,
        error: error instanceof SdkError ? error.code : "delivery_failed"
      }));
      process.exitCode = 1;
    }
    JS
    ```

    이벤트에 자격 증명, 헤더, 요청 본문, 고객 데이터, 로컬 경로를 넣지 마세요.

    **확인:** 스크립트가 `2xx` `status_code`와 함께 `"ok":true`를 출력합니다. 재시도했다면 `attempts`가 `1`보다 큽니다. 전송 성공이 마지막 확인은 아닙니다.

    전송에 실패하면 스크립트는 코드 `1`로 종료하고 `{"ok":false,"error":"unauthenticated"}` 같은 짧은 JSON 오류를 출력합니다. 요청 본문이나 키는 출력하지 않습니다. 프로젝트 키가 거부되면 `unauthenticated`가 나옵니다. CLI에 새로 로그인해도 해결되지 않습니다.
  </Step>

  <Step title="프로젝트 doctor 보고서 읽기" id="verify-readiness-with-the-project-doctor">
    CLI는 이 조회에 저장된 계정 접근 권한을 사용합니다. 프로젝트 수집 키를 쓰지 마세요.

    ```bash theme={null}
    : "${LOGBREW_PROJECT_ID:?set the project UUID}"

    logbrew doctor --project "$LOGBREW_PROJECT_ID" --json
    ```

    **확인:** 보고서에 `status: "ready"`가 있습니다. `checks`의 각 항목도 읽으세요. 종료 코드 `0`은 모든 검사를 통과했다는 뜻이 아닙니다. 다른 상태라면 `next`와 [doctor 보고서 레퍼런스](/ko/reference/cli#read-a-project-doctor-report)를 따르세요. 프로젝트가 `ready`여도 이 테스트 로그가 도착했다는 뜻은 아닙니다.
  </Step>

  <Step title="테스트 로그 읽기">
    SDK 배치의 프로젝트, 릴리스, 환경을 사용하세요.

    ```bash theme={null}
    logbrew read logs --project "$LOGBREW_PROJECT_ID" \
      --release quickstart@1 \
      --environment development \
      --since 1h \
      --json
    ```

    **확인:** 해당 프로젝트, 릴리스, 환경에 `LogBrew quickstart check`가 나타납니다. 이것은 테스트 로그가 전송되었다는 것만 보여 줍니다.
  </Step>
</Steps>

## <span id="understand-the-test-result">테스트 결과 읽기</span>

예제는 이벤트 3개를 보냅니다. 그중 로그는 1개뿐입니다. 릴리스와 환경 마커는 로그에 컨텍스트를 줍니다.

| 예제의 필드 | 기록되는 데이터 |
| - | - |
| `message` | 테스트가 기록하는 작업입니다. `LogBrew quickstart check`입니다. |
| `level: "info"` | 실패가 아닌 일반 테스트 이벤트입니다. |
| `logger` | 기록을 만든 애플리케이션 로거입니다. |
| `occurredAt` | 이번 실행에서 이벤트를 만든 시각입니다. UTC 타임스탬프입니다. |
| `context.resource.service` | 애플리케이션 서비스와 그 버전입니다. SDK 식별 정보가 아닙니다. |

테스트 로그는 `info`로 두세요. 찾기 쉽게 하려고 `error`로 바꾸지 마세요. 대신 프로젝트와 시간 필터를 사용하세요. [심각도 값](/ko/concepts/telemetry#severity-values)을 참고하세요.

`console.log` 줄은 전송 결과를 터미널에 출력합니다. `client.log` 호출은 로그를 LogBrew로 보냅니다. 첫 전송에 성공하면 다음이 출력됩니다.

```json theme={null}
{ "ok": true, "status_code": 200, "attempts": 1 }
```

로그를 받을 프로젝트는 수집 키가 정합니다. CLI의 `--project` 필터는 이벤트를 옮기지 않습니다.

예제가 요청 스팬을 만들지 않으므로 이 로그에는 트레이스 컨텍스트가 없습니다. 로그가 실패했다는 뜻은 아닙니다. CLI 조회는 그 시점의 스냅숏입니다. 나중에 들어온 이벤트를 읽으려면 다시 실행하거나, 실시간 스트림을 보려면 `logbrew watch logs --json`을 사용하세요.

## 자주 하는 복구 판단

| 결과 | 다음 단계 |
| - | - |
| CLI 상태가 인증되지 않음 | 사람이 `logbrew login`을 실행합니다. 그다음 상태 명령어를 다시 실행하세요. |
| 수집 키 파일이 이미 있음 | 쓰지 않은 경로를 고르세요. 알 수 없는 자격 증명을 덮어쓰지 마세요. |
| 프로젝트 생성 결과가 분명하지 않음 | 같은 생성 명령어를 그대로 다시 실행하세요. |
| `unauthenticated` | CLI 계정 자격 증명이 아니라 프로젝트 수집 키를 확인하세요. 새로 로그인해도 해결되지 않습니다. |
| `rate_limited` | 다시 보내기 전에 기다리세요. 반복 실행하거나 새 키를 만들지 마세요. |
| `transport_error` 또는 `network_failure` | 네트워크 연결을 확인하세요. 응답이 실패했다고 해서 이전 요청이 아무 영향도 없었다는 뜻은 아닙니다. |
| `delivery_failed` | 멈추고 실패 원인을 확인하세요. 시크릿이나 요청 본문을 출력하지 마세요. |
| doctor `status`가 `ready`가 아님 | [doctor 보고서](/ko/reference/cli#read-a-project-doctor-report)에서 `checks`와 `next`를 읽으세요. 같은 프로젝트를 유지하세요. |
| 로그 조회 결과가 비어 있음 | 프로젝트, 환경, 릴리스, 기간을 보낸 배치와 비교하세요. |

텔레메트리가 여전히 보이지 않으면 [첫 텔레메트리 확인](/ko/guides/troubleshooting#recover-missing-first-telemetry)을 진행하세요. 그래도 해결되지 않으면 [문제 신고](/ko/guides/report-a-problem)하세요. 자격 증명, 원시 텔레메트리, 고객 데이터, 로컬 경로, 소스 코드를 첨부하지 마세요.

## 애플리케이션에 적용하기

* 앱의 설정 코드에서 클라이언트를 한 번만 만드세요.
* 패키지 파일에서 SDK 버전을 고정하세요. 업그레이드는 프로덕션 밖에서 테스트하세요.
* 기존 시크릿 설정에서 수집 키를 불러오세요. 노출되었을 가능성이 있으면 키를 교체하세요. [수집 키 교체하기](/ko/guides/rotate-ingest-key)를 참고하세요.
* 배포 설정에서 바뀌지 않는 서비스, 환경, 릴리스 이름을 사용하세요. [릴리스](/ko/concepts/releases)를 참고하세요.
* 로그 메시지에는 `Report generation completed`처럼 작업과 결과를 적으세요. 메시지에 개인적인 값을 넣지 마세요. 요청 전체나 사용자 레코드 전체를 로그에 복사하지 마세요.
* 중복 기록을 막으려면 애플리케이션 로그마다 보내는 곳을 하나만 두세요. LogBrew를 추가하기 전에 각 기록을 이미 보내고 있는 연동을 찾으세요.
* 프로덕션에 배포하기 전에 실제 코드 경로로 안전한 이벤트 1개를 보내고 다시 읽으세요. 메시지, 서비스, 릴리스, 환경을 확인하세요. 독립 실행 예제로는 애플리케이션의 코드 경로를 테스트할 수 없습니다.

이 예제는 브라우저 수집, 소스맵, 모바일 수집을 설정하지 않습니다. 이런 항목은 [SDK 연동](/ko/guides/sdk-ingestion)에서 시작하세요.

<CardGroup cols={2}>
  <Card title="프로젝트 및 설정" icon="folder-kanban" href="/ko/concepts/projects">
    설정 상태를 확인하고 프로젝트 수집 키를 관리하세요.
  </Card>

  <Card title="SDK 연동" icon="cloud-upload" href="/ko/guides/sdk-ingestion">
    런타임에 맞는 SDK 패키지를 고르세요.
  </Card>

  <Card title="이슈 조사하기" icon="bug" href="/ko/guides/investigate-an-issue">
    이슈 1개의 트레이스와 관련 로그 근거를 따라가세요.
  </Card>

  <Card title="문제 신고" icon="life-buoy" href="/ko/guides/report-a-problem">
    안전하고 비공개인 지원 보고서를 보내세요.
  </Card>
</CardGroup>


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