> ## 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.

# API 키 교체: LogBrew 수집 키 교체하기

> LogBrew 수집 키를 교체하세요. 계획된 해지 전에 새 키를 테스트하고, 자격 증명을 노출하지 않고 오류에서 복구하세요.

키 교체는 프로젝트의 수집 키를 새 키로 바꿉니다. 프로젝트나 저장된 텔레메트리는 바뀌지 않습니다. 키는 계정 인증으로 관리하세요. 수집 키는 텔레메트리를 보내는 데만 쓸 수 있으며, 키를 관리할 수는 없습니다.

시작하기 전에 [CLI를 설치하고 로그인](/ko/guides/cli)하세요. `LOGBREW_PROJECT_ID`를 프로젝트 UUID로 설정하세요. `LOGBREW_API_URL`을 `https://api.logbrew.co`로 설정하세요. 예제는 Bash, curl 7.76.0 이상, jq를 사용합니다.

계획된 교체라면 이전 키를 해지하기 전에 새 키를 만들고, 배포하고, 테스트하세요. 교체 주기는 보안 정책에서 정하세요. 키에 만료일이 있으면 그 전에 교체하세요.

<Warning>
  노출된 키는 보안 사고입니다. 새 키를 배포하기 전이라도 즉시 해지하세요. 해지된 키를 계속 사용하는 애플리케이션은 텔레메트리를 보낼 수 없습니다.
</Warning>

<Steps>
  <Step title="새 키 만들기">
    `POST /api/projects/{project_id}/ingest-keys`는 120자 이하의 비어 있지 않은 `label`을 받습니다. `kind`는 `cli`, `sdk`, `browser`, `server`, `artifact` 중 하나입니다. `artifact` 키로는 텔레메트리를 보낼 수 없습니다. 선택 사항인 `expires_at`은 미래의 RFC3339 시각이어야 합니다.

    이전 키와 같은 `kind`를 사용하세요. CLI는 `--kind`를 생략하면 `sdk`를, `--label`을 생략하면 `CLI-created SDK key`를 사용합니다. CLI에는 만료 플래그가 없습니다. `expires_at`을 설정하려면 API를 사용하세요.

    CLI는 한 번만 표시되는 토큰을 소스 관리 밖에 있는, 소유자만 접근할 수 있는 새 파일에 저장합니다. 토큰이 아니라 메타데이터를 출력합니다.

    ```bash theme={null}
    : "${LOGBREW_PROJECT_ID:?set LOGBREW_PROJECT_ID}" &&
    : "${LOGBREW_REPLACEMENT_KEY_FILE:?choose a new private key file}" &&
    logbrew projects keys create "$LOGBREW_PROJECT_ID" \
      --ingest-key-file "$LOGBREW_REPLACEMENT_KEY_FILE" \
      --label "checkout production rotation" --kind server --json
    ```

    명령어가 성공한 뒤에만 다음 단계로 넘어가세요. `NEW_KEY_ID`를 반환된 `ingest_key.id`로 설정하세요.

    결과가 불확실하면 같은 명령어를 그대로 다시 실행하세요. CLI는 대기 중인 재시도 키를 다시 사용합니다. 이 재시도에는 `--abandon-retry`를 사용하지 마세요.

    API를 직접 호출하는 클라이언트는 응답에서 토큰을 한 번만 받습니다. 재시도하려면 같은 본문과 함께 같은 `Idempotency-Key` 헤더를 보내세요. 24시간 동안 이 재시도는 같은 키를 반환합니다. 토큰을 출력하거나 커밋하거나 공유하지 마세요.
  </Step>

  <Step title="이전 키를 활성 상태로 둔 채 새 키 배포하기">
    새 토큰을 보호된 배포 설정에 넣으세요. 앱을 배포하세요. 이전 키는 활성 상태로 두세요. 두 토큰 모두 소스, 빌드 출력, 로그에 들어가지 않게 하세요.
  </Step>

  <Step title="테스트 이벤트 1개 보내기">
    새 토큰을 `new_ingest_key` 셸 변수에 불러오세요. 출력하지 마세요. 새 키로 테스트 로그 1개를 보낸 다음 다시 읽으세요.

    ```bash theme={null}
    occurred_at="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"

    curl --fail-with-body -sS "$LOGBREW_API_URL/api/telemetry/ingest" \
      -H "Authorization: Bearer $new_ingest_key" \
      -H "Content-Type: application/json" \
      --data @- <<JSON &&
    {
      "project_id": "$LOGBREW_PROJECT_ID",
      "environment": "production",
      "release": "ingest-key-rotation@1",
      "service_name": "checkout-api",
      "sdk_name": "native-api",
      "sdk_version": "0.1.0",
      "items": [
        {
          "type": "log",
          "data": {
            "level": "info",
            "message": "ingest key rotation check",
            "source": "setup",
            "attributes": {},
            "occurred_at": "$occurred_at"
          }
        }
      ]
    }
    JSON

    logbrew read logs --project "$LOGBREW_PROJECT_ID" \
      --release ingest-key-rotation@1 \
      --environment production \
      --since "$occurred_at" \
      --json
    ```

    읽기 결과에 같은 `occurred_at`을 가진 이 로그가 나올 때만 다음 단계로 넘어가세요. 이전에 보낸 교체 확인 로그로는 새 키가 작동한다는 것을 증명할 수 없습니다. 배포된 앱이 텔레메트리를 보내는지도 확인하세요. 명령어가 실패하면 멈추고 응답을 읽으세요. 이전 키가 노출되지 않았다면 활성 상태로 두세요.
  </Step>

  <Step title="시크릿이 없는 키 메타데이터 나열하기">
    계정 인증 정보로 `LOGBREW_ACCOUNT_BEARER`를 설정하세요. 이전 키 ID를 찾으세요. `NEW_KEY_ID`가 `active`인지 확인하세요.

    ```bash theme={null}
    (
      set -o pipefail
      curl --fail-with-body -sS "$LOGBREW_API_URL/api/projects/$LOGBREW_PROJECT_ID/ingest-keys" \
        -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
        | jq -e 'select(type == "array") | map({id, label, kind, token_prefix, status, created_at, expires_at, revoked_at})'
    )
    ```

    응답은 토큰이 없는 키 메타데이터 배열입니다. 상태는 `active`, `expired`, `revoked` 중 하나입니다. `expires_at` 시각이 지나면 키는 `expired`가 됩니다.
  </Step>

  <Step title="이전 키만 해지하기">
    목록에서 찾은 값으로 `OLD_KEY_ID`를 설정하세요. 이 명령어는 두 ID가 다를 때만 이전 키를 해지합니다.

    ```bash theme={null}
    if [ -n "${OLD_KEY_ID:-}" ] && [ -n "${NEW_KEY_ID:-}" ] \
      && [ "$OLD_KEY_ID" != "$NEW_KEY_ID" ]; then
      (
        set -o pipefail
        curl --fail-with-body -sS -X DELETE \
          "$LOGBREW_API_URL/api/projects/$LOGBREW_PROJECT_ID/ingest-keys/$OLD_KEY_ID" \
          -H "Authorization: Bearer $LOGBREW_ACCOUNT_BEARER" \
          | jq -e --arg id "$OLD_KEY_ID" \
            'select(.id == $id and .status == "revoked") | {id, label, kind, token_prefix, status, created_at, expires_at, revoked_at}'
      )
    else
      printf '%s\n' 'Set different old and replacement key IDs before revocation.' >&2
      false
    fi
    ```

    `DELETE`는 멱등입니다. `status: "revoked"`와 `revoked_at`이 설정된 키 메타데이터를 반환합니다. 응답이 불확실하면 안전하게 반복할 수 있습니다.

    `unset new_ingest_key`를 실행하세요. 키 파일은 시크릿 정책에 따라 처리하세요.
  </Step>
</Steps>

## 안전하게 복구하기

| 응답 | 다음 단계 |
| - | - |
| `404`, `code: "not_found"` | 계정이 해당 프로젝트 ID와 키 ID를 소유하는지 확인하세요. `next_action.code: "check_resource"`를 따르세요. 다른 ID를 시도하지 마세요. |
| `code: "validation_failed"` | 표시된 필드, 값, 타임스탬프를 고치세요. `next`와 `next_action`을 따르세요. |
| 키 관리에서 `401` 또는 `403` | 수집 키가 아니라 계정 인증을 사용하세요. |
| 수집 요청에서 `401`, `code: "ingest_key_invalid"` | 키가 해지되었거나, 만료되었거나, 텔레메트리에 쓸 수 없는 키입니다. 선택한 프로젝트의 새 활성 키를 사용하세요. `next_action.code: "configure_ingest_key"`를 따르세요. |
| 수집 요청에서 `401` 또는 `403` | 선택한 프로젝트의 새 수집 키를 사용하세요. 계정 자격 증명을 사용하지 마세요. |

그래도 교체에 실패하면 [문제 신고](/ko/guides/report-a-problem)하세요. 키 메타데이터만 공유하세요. 자격 증명, 헤더, 원본 텔레메트리, 고객 데이터, 로컬 경로, 소스 코드는 넣지 마세요.


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