Vite로 JavaScript 소스맵 업로드하기

압축된 JavaScript 파일에서는 여러 소스 줄이 한 줄에 들어갈 수 있습니다. 이 파일에서 나온 스택 프레임은 생성된 코드의 줄과 열을 가리킵니다. 소스맵은 이 위치를 원본 파일, 줄, 열에 연결합니다. 이 가이드는 @logbrew/sdk 0.1.28의 Vite 플러그인을 사용합니다. Vite 앱, 앱의 빌드 결과물에 대한 접근 권한, 프로젝트 키를 만들 권한이 필요합니다. Apple 디버그 파일은 Apple 크래시와 멈춤을 참고하세요.

빌드와 이벤트의 정보 맞추기

업로드와 앱의 런타임 이벤트에 같은 프로젝트, 릴리스, 환경, 서비스를 사용하세요. 버전 이름은 릴리스를 참고하세요. 이 가이드에서는 web@1.2.3, staging, checkout-web을 사용합니다. 빌드된 코드가 바뀌면 릴리스도 바꾸세요. 준비된 빌드를 업로드한 다음, 바로 그 빌드를 배포하세요. 업로드한 뒤에는 다시 빌드하거나 JavaScript를 수정하지 마세요.

Vite 플러그인 추가하기

앱 디렉터리에 SDK를 설치하세요.

npm install @logbrew/sdk@0.1.28

vite.config.js에 플러그인을 추가하세요. 다른 플러그인과 빌드 설정은 그대로 두세요. 프로젝트 ID를 바꾸세요.

import { createLogBrewViteReleaseArtifactsPlugin } from "@logbrew/sdk/vite-release-artifacts";

export default {
  plugins: [
    createLogBrewViteReleaseArtifactsPlugin({
      projectId: "<project_id>",
      release: "web@1.2.3",
      environment: "staging",
      service: "checkout-web",
      minifiedPathPrefix: "https://app.example.com"
    })
  ]
};

minifiedPathPrefix는 빌드 디렉터리가 배포된 URL입니다. 플러그인은 이 디렉터리 안의 각 파일 경로를 이 값 뒤에 붙입니다. 예를 들어 dist/assets/app.js는 https://app.example.com/assets/app.js가 됩니다. 빌드를 /web에서 제공한다면 접두사에 /web을 포함하세요. 접두사에 /assets는 추가하지 마세요. upload 옵션이 없으면 플러그인은 LogBrew로 아무것도 보내지 않습니다. 플러그인은 다음 작업도 합니다.

build.sourcemap을 설정하지 않으면 "hidden"으로 설정합니다. false로 설정했다면 "hidden"으로 바꾸세요.
압축 도구 옵션을 설정하지 않으면 함수 이름을 유지합니다. 직접 옵션을 설정했다면 그 옵션에서도 이름을 유지하세요.

숨긴 소스맵은 일반 파일로 빌드 결과물에 남습니다. 접근 제어가 적용되지 않습니다. 인라인 소스맵은 사용하지 마세요. 플러그인은 JavaScript 파일 안에 들어 있는 맵을 받지 않습니다.

로컬에서 빌드하고 확인하기

프로덕션 빌드를 실행하세요.

npm run build

플러그인은 각 JavaScript 파일과 그 소스맵에 같은 Debug ID를 부여합니다. 포함된 sourcesContent와 로컬 앱 루트 경로를 제거합니다. 그리고 dist/logbrew-release-artifacts.json을 작성합니다. 매니페스트를 여세요. validation.status가 ready인지, 이 빌드의 파일과 배포 URL이 나열되어 있는지 확인하세요. 숨긴 맵 때문에 sourceMappingURL comment missing 경고가 나옵니다. 이 경고는 정상입니다. 비공개 경로나 공유하고 싶지 않은 소스 텍스트가 들어 있는 맵은 업로드하지 마세요. 업로드에는 컴파일된 JavaScript도 들어가므로 앱 번들에 시크릿을 넣지 마세요. 로컬에서 업로드를 확인하세요. 이 명령어는 요청을 보내지 않으며 키도 필요 없습니다.

npx --no-install logbrew-release-artifacts upload-js \
  --build-dir dist \
  --manifest dist/logbrew-release-artifacts.json \
  --endpoint https://api.logbrew.co/api/release-artifacts \
  --allow-hosted \
  --dry-run

명령어가 코드 0으로 종료되고 "status": "dry_run"을 출력할 때만 계속 진행하세요. 이 명령어는 로컬 파일과 매니페스트를 확인합니다. 서버는 테스트하지 않습니다. 빌드가 다른 출력 디렉터리를 쓴다면 두 경로를 모두 바꾸세요. 매핑을 확인하려면 빌드된 앱을 실행하고, 생성된 스택 프레임 1개를 파일, 줄, 열과 함께 복사하세요.

npx --no-install logbrew-release-artifacts symbolicate-js \
  --build-dir dist \
  --manifest dist/logbrew-release-artifacts.json \
  --stack-frame "at checkoutTotal (https://app.example.com/assets/index-a1b2c3.js:2:780)"

결과에 "status": "resolved"가 있는지 확인하세요. original 객체는 소스 파일, 줄, 열을 보여 줍니다. 이 명령어는 로컬에서 실행되며 아무것도 업로드하지 않습니다.

아티팩트 키 만들기

LogBrew CLI로 로그인하세요. 프로젝트 ID를 찾으세요.

logbrew projects --json

프로젝트에 아티팩트 키를 만드세요. 소유자만 접근할 수 있는 디렉터리에 새 파일 경로를 지정하세요.

install -d -m 700 "$HOME/.logbrew" &&
logbrew projects keys create "<project_id>" \
  --ingest-key-file "$HOME/.logbrew/checkout-web.artifact" \
  --label "Checkout web build" \
  --kind artifact \
  --json

명령어가 성공한 뒤에만 계속 진행하세요. 결과가 분명하지 않으면 같은 인수로 같은 명령어를 다시 실행하세요. --abandon-retry는 사용하지 마세요. 아티팩트 키는 프로젝트 범위의 쓰기 전용 키입니다. 소스맵과 디버그 파일을 업로드합니다. 텔레메트리를 보내거나 아티팩트 메타데이터를 읽을 수는 없습니다. 대신 계정 자격 증명이나 런타임 SDK 키를 쓰지 마세요. 키는 빌드 환경의 시크릿 설정에 LOGBREW_RELEASE_ARTIFACT_TOKEN으로 저장하세요. 키를 출력하거나 커밋하지 마세요. VITE_*나 EXPO_PUBLIC_*처럼 클라이언트에 노출되는 변수에 넣지 마세요. 업로드를 실행하는 프로세스에 이 변수를 설정하세요. 헬퍼는 .env 파일을 읽지 않습니다. Vite도 설정 평가 중에는 이 파일을 process.env로 불러오지 않습니다.

준비된 빌드 업로드하기

확인을 마친 같은 파일과 매니페스트를 사용하세요. 이 명령어는 업로드를 LogBrew로 보냅니다.

npx --no-install logbrew-release-artifacts upload-js \
  --build-dir dist \
  --manifest dist/logbrew-release-artifacts.json \
  --endpoint https://api.logbrew.co/api/release-artifacts \
  --allow-hosted

"status": "uploaded"가 나오면 LogBrew가 업로드를 받았다는 뜻입니다. 명령어가 오류와 함께 종료되면 멈추고 아래 표를 참고하세요. 헬퍼는 네트워크 오류, 408, 429, 5xx 응답이 나오면 최대 2번 다시 시도합니다. 매번 같은 준비된 파일을 보냅니다. 횟수를 바꾸려면 --max-retries를 사용하세요. 수동 업로드가 잘 되면, 대신 Vite 빌드 중에 업로드할 수도 있습니다. 플러그인 설정에 다음 옵션을 추가하세요.

upload: {
  endpoint: "https://api.logbrew.co/api/release-artifacts",
  allowHostedUpload: true,
  tokenEnv: "LOGBREW_RELEASE_ARTIFACT_TOKEN"
}

업로드 방식은 하나만 사용하세요. 준비 오류나 업로드 오류가 나면 플러그인이 빌드를 멈춥니다. 업로드 없이 테스트하려면 dryRun: true를 추가하세요. 플러그인은 출력 디렉터리에서 소스맵을 삭제하지 않습니다. .map 파일이나 매니페스트를 공개 웹사이트나 CDN에 배포하지 마세요. 수집된 이슈의 프레임을 매핑하려면 같은 준비된 빌드를 대상으로 그 프레임과 함께 symbolicate-js를 실행하세요.

새 이슈 읽기

같은 준비된 빌드를 테스트 환경에 배포하세요. 이슈 수집 경로로 안전한 테스트 오류 1개를 일으키세요. 이 테스트에서는 사용자 입력, 자격 증명, 원시 스택을 보내지 마세요. 같은 프로젝트와 빌드 컨텍스트로 새 이슈를 찾으세요.

logbrew read issues --project "<project_id>" \
  --release "web@1.2.3" --environment staging \
  --service checkout-web --since 1h --json

결과에서 이슈 ID를 복사하세요. 가장 최근 발생 건을 읽으세요.

logbrew investigate issue "<issue_id>" --occurrence latest --json

먼저 이벤트 시각, 프로젝트, 서비스, 환경, 릴리스를 확인하세요. 그다음 event.stack_frames를 읽으세요. source: "symbolicated"인 프레임에는 업로드한 소스맵에서 가져온 원본 파일, 줄, 열이 들어 있습니다. source: "captured"인 프레임에는 앱이 보낸 위치가 들어 있습니다. logbrew read issue "<issue_id>" --json도 symbolication 객체를 반환합니다. 이 객체의 각 프레임에는 resolved, artifact_not_found, source_not_resolved, invalid_metadata, unavailable 중 하나인 status가 있습니다. resolved 프레임에만 원본 위치가 있습니다. LogBrew는 이슈를 읽을 때 프레임을 매핑합니다. 오류가 난 뒤에 업로드해도 같은 Debug ID를 가진 이전 이벤트를 매핑할 수 있습니다. 매핑된 프레임은 살펴볼 코드를 가리킵니다. 오류의 원인을 보여 주지는 않습니다. 다른 필드는 이슈 조사하기를 참고하세요.

확인 실패 시 복구하기

결과	다음 단계
매니페스트 상태가 `ready`가 아님	`validation.errors`를 읽으세요. 빌드 설정을 고치고 다시 빌드하세요. 매니페스트를 직접 수정하지 마세요.
소스맵이 없거나 인라인이라 빌드가 멈춤	`build.sourcemap`을 `"hidden"`이나 `true`로 설정하세요. 다시 빌드하세요.
`auth_missing`	업로드 프로세스에 `LOGBREW_RELEASE_ARTIFACT_TOKEN`을 설정하세요. 드라이 런으로는 키를 테스트할 수 없습니다.
`auth_failed` (`401` 또는 `403`)	같은 프로젝트의 아티팩트 키를 사용하세요. 런타임 키나 계정 키를 쓰지 마세요.
`validation_failed` (`400` 또는 `413`)	준비된 파일과 그 크기를 확인하세요. 같은 업로드를 다시 보내지 마세요.
로컬 오류가 있는 `validation_failed`	`validation.errors`를 읽으세요. 빌드 후 파일이 바뀌었다면 다시 빌드하고 확인하세요.
`retryable_error`	네트워크 오류, `408`, `429`, 서버 오류 후 재시도가 모두 실패했습니다. 나중에 같은 준비된 파일로 다시 시도하세요.
`upload_failed`	서버가 다른 상태를 반환했습니다. `--endpoint` 값을 확인하세요.
프레임이 매핑되지 않음	Debug ID, 배포 URL 접두사, 빌드를 확인하세요. 다른 빌드나 릴리스의 맵을 사용하지 마세요.
새 이슈가 나타나지 않음	소스맵을 테스트하기 전에 이슈 수집, 런타임 키, 시간 필터를 확인하세요.

지원 메시지에는 소스 파일, 키, 비공개 경로를 넣지 마세요. 문제 해결과 API 오류를 참고하세요.

시작하기

개념

설치 및 데이터 전송

조사

CLI 및 에이전트

지원

Vite로 JavaScript 소스맵 업로드하기

빌드와 이벤트의 정보 맞추기

Vite 플러그인 추가하기

로컬에서 빌드하고 확인하기

아티팩트 키 만들기

준비된 빌드 업로드하기

새 이슈 읽기

확인 실패 시 복구하기

​빌드와 이벤트의 정보 맞추기

​Vite 플러그인 추가하기

​로컬에서 빌드하고 확인하기

​아티팩트 키 만들기

​준비된 빌드 업로드하기

​새 이슈 읽기

​확인 실패 시 복구하기

빌드와 이벤트의 정보 맞추기

Vite 플러그인 추가하기

로컬에서 빌드하고 확인하기

아티팩트 키 만들기

준비된 빌드 업로드하기

새 이슈 읽기

확인 실패 시 복구하기