콘텐츠로 이동

스크립트로 SourceMap 업로드

RUM 애플리케이션에서 공용 네트워크 DataWay 방식을 사용하는 경우, 애플리케이션 실행 데이터가 공용 네트워크 DataWay로 직접 보고됩니다. 해당 SourceMap 파일은 해당 사이트의 OpenAPI 인터페이스를 통해 스크립트로 업로드할 수 있습니다.

즉, 다음과 같습니다.

  • RUM 데이터를 보고할 때는 애플리케이션 연동 페이지의 datawayUrl과 clientToken을 사용합니다.
  • SourceMap 파일을 업로드할 때는 사이트의 OpenAPI 주소와 OPEN_API_KEY를 사용합니다.

이 문서에서는 공용 네트워크 DataWay 환경에서 스크립트를 통해 SourceMap을 업로드하는 방법을 설명합니다.

사전 준비

  1. 현재 애플리케이션이 해당 단말의 연동 문서에 따라 공용 네트워크 DataWay 초기화를 완료했는지 확인합니다.
  2. 현재 사이트에 해당하는 OpenAPI 주소를 확인합니다.
  3. 현재 사이트에 해당하는 OPEN_API_KEY를 확인합니다.
    • Guance 워크스페이스에 접속한 후 관리 > API Key 관리 > Key 생성을 클릭합니다.
    • 생성이 완료되면 API Key 상세 페이지에서 Key를 확인하고, 이를 스크립트에서 DF_API_KEY로 사용합니다.
    • 환경이나 버전을 구분하지 않을 경우 app_id만 전달해도 되지만, 매칭 범위가 넓어져 env, version을 함께 전달하는 것이 정확합니다.
  4. 대상 RUM 애플리케이션의 app_id, env, version을 확인합니다.
    • app_id는 현재 RUM 애플리케이션의 고유 식별자입니다.
    • env, version은 SDK 초기화 또는 실제 오류 데이터의 해당 필드와 일치해야 합니다.
  5. SourceMap 설정의 요구 사항에 따라 미리 sourcemap.zip을 패키징합니다.
  6. Shell 버전을 사용하는 경우 환경에 bash, curl, jq, split, mktemp, wc가 설치되어 있어야 합니다.
  7. Python 버전을 사용하는 경우 환경에 python3가 설치되어 있어야 합니다.

스크립트 업로드

스크립트 업로드는 OpenAPI를 통해 이루어지며, 공용 네트워크 DataWay 연동 환경에서의 자동 업로드에 적합합니다.

스크립트 설명

업로드 스크립트 저장소 주소: sourcemap-upload-scripts.

현재 두 가지 업로드 스크립트를 제공합니다.

  • Shell 버전: upload-sourcemap.sh
  • Python 버전: upload_sourcemap.py

두 스크립트 모두 이미 패키징 완료된 sourcemap.zip 파일을 업로드하는 용도로, SourceMap 생성 또는 압축을 담당하지 않습니다.

예제 명령을 실행하기 전에 위 저장소에서 해당 스크립트를 가져와 현재 명령 실행 디렉터리에 두거나, 명령에 스크립트의 실제 경로를 입력하세요.

파라미터 설명

필수 파라미터

  • --endpoint: 사이트에 해당하는 OpenAPI 주소입니다.
  • --api-key: 사이트에 해당하는 OPEN_API_KEY로, 요청 시 DF-API-KEY 요청 헤더에 기록됩니다.
  • --app-id: RUM 애플리케이션의 app_id입니다.
  • --file: 업로드할 sourcemap.zip 파일 경로이며, 파일 크기는 500 MB를 초과할 수 없습니다.

선택 파라미터

  • --version: 애플리케이션 버전 번호입니다.
  • --env: 애플리케이션 환경 식별자입니다 (예: daily, gray, prod).
  • --need-cover: 동일한 이름의 파일을 덮어쓸지 여부입니다. 선택 가능한 값은 true 또는 false이며, 기본값은 false입니다.
  • --chunk-size-mb: 청크 업로드 크기(단위: MB)이며, 기본값은 10, 최대값은 10입니다.
  • --merge-path: 사용자 정의 병합 인터페이스 경로입니다. 현재 사이트의 병합 인터페이스 경로가 스크립트 기본값과 다른 경우에만 사용합니다.
  • --cancel-path: 사용자 정의 업로드 취소 인터페이스 경로입니다. 현재 사이트의 취소 인터페이스 경로가 스크립트 기본값과 다른 경우에만 사용합니다.

사용 방법

sh ./upload-sourcemap.sh \
  --endpoint https://openapi.guance.com \
  --api-key "$DF_API_KEY" \
  --app-id app_id_from_studio \
  --version 1.0.2 \
  --env daily \
  --file ./sourcemap.zip \
  --need-cover true

python3 ./upload_sourcemap.py \
  --endpoint https://openapi.guance.com\
  --api-key "$DF_API_KEY" \
  --app-id app_id_from_studio \
  --version 1.0.2 \
  --env daily \
  --file ./sourcemap.zip \
  --need-cover true

예상 출력

실행이 성공하면 다음과 유사한 로그가 표시됩니다.

  • Init succeeded, uploadId=...
  • Uploading part x/y
  • Merge succeeded via /api/v1/rum_sourcemap/part_merge
  • Upload complete

환경 변수 방식

환경 변수를 통해 동일한 파라미터를 전달할 수도 있습니다.

export DF_OPENAPI_ENDPOINT="https://openapi.guance.com"
export DF_API_KEY="your-api-key"
export DF_APP_ID="app_id_from_studio"
export DF_VERSION="1.0.2"
export DF_ENV="daily"
export DF_SOURCEMAP_FILE="./sourcemap.zip"
export DF_NEED_COVER="true"

환경 변수와 명령줄 파라미터의 대응 관계는 다음과 같습니다.

  • DF_OPENAPI_ENDPOINT는 --endpoint에 해당합니다.
  • DF_API_KEY는 --api-key에 해당합니다.
  • DF_APP_ID는 --app-id에 해당합니다.
  • DF_VERSION은 --version에 해당합니다.
  • DF_ENV는 --env에 해당합니다.
  • DF_SOURCEMAP_FILE은 --file에 해당합니다.
  • DF_NEED_COVER는 --need-cover에 해당합니다.

그런 다음 다음을 실행합니다.

sh ./upload-sourcemap.sh

또는:

python3 ./upload_sourcemap.py

주의 사항

  1. 스크립트 업로드는 공용 네트워크 DataWay 연동 환경에 적합합니다.
  2. 업로드 스크립트는 OpenAPI + DF-API-KEY 인증 방식을 사용하며, datawayUrl + clientToken을 사용하지 않습니다.
  3. sourcemap.zip 압축 해제 후의 디렉터리 구조는 오류 스택의 파일 경로와 일치해야 합니다.
  4. 업로드 파일은 .zip 형식이어야 하며, 파일 크기는 500 MB를 초과할 수 없습니다.
  5. version과 env 중 하나만 입력하면 업로드 대상이 정확하지 않을 수 있으므로, 함께 입력하는 것을 권장합니다.
  6. 청크 업로드 시 각 청크의 최대 크기는 10 MB입니다.
  7. 업로드 프로세스가 초기화 후 실패하면 스크립트가 자동으로 현재 청크 업로드 작업을 취소합니다.
  8. Python 버전은 Python 표준 라이브러리만 사용하며, 별도의 pip 종속성 설치가 필요하지 않습니다.

자주 묻는 질문

uploadId is empty

일반적으로 서버에 동일한 이름의 SourceMap이 이미 존재하고 덮어쓰기가 활성화되지 않았음을 의미합니다.

다시 시도할 때 다음 파라미터를 추가하세요.

--need-cover true

Missing required command

Shell 버전에 필요한 종속 명령이 누락되었음을 의미합니다. 해당 도구를 설치한 후 다시 시도하세요.

Merge endpoint ... returned HTTP 404

일반적으로 현재 사이트에서 다른 병합 인터페이스 경로를 사용하고 있음을 의미합니다.

해당 사이트 관리자에게 인터페이스 경로를 확인한 후 다시 지정하세요.

--merge-path <your-path>

업로드는 성공했지만 오류 스택이 해석되지 않습니다.

다음 내용을 우선 확인하세요.

  1. app_id, version, env가 실제 오류 데이터와 일치하는지 확인합니다.
  2. sourcemap.zip 압축 해제 후의 디렉터리 구조가 error_stack의 리소스 경로와 일치하는지 확인합니다.
  3. 현재 애플리케이션이 SourceMap을 업로드해야 하는 대상 애플리케이션이 맞는지 확인합니다.

문서 평가

이 페이지가 도움이 되었나요?