미니 프로그램 앱 연동¶

SDK 파일을 도입하여 미니 프로그램 앱의 성능 지표, 오류 로그, 리소스 요청 데이터를 수집하고 Guance 플랫폼에 업로드하여 미니 프로그램 앱의 성능을 시각화하여 분석합니다.

전제 조건 (DataKit 연동)¶

DataKit 설치
RUM 수집기 구성
DataKit을 공개 인터넷에서 접근 가능하도록 구성하고 IP 지리 정보 데이터베이스 설치

연동 시작¶

사용자 액세스 모니터링 > 앱 생성 > 미니 프로그램으로 이동합니다.
앱 이름을 입력합니다.
앱 ID를 입력합니다.
앱 연동 방식을 선택합니다.
공용 DataWay: DataKit 수집기 설치 없이 RUM 데이터를 직접 수신합니다.
로컬 환경 배포: 전제 조건을 충족한 후 RUM 데이터를 수신합니다.

연동 방식¶

DataKit 연동공용 OpenWay

DataKit이 설치되어 공개 인터넷에서 접근 가능하고 IP 지리 정보 데이터베이스가 설치되었는지 확인합니다.
콘솔에서 applicationId, env, version 등의 매개변수를 가져와 앱 연동을 시작합니다.
SDK를 통합할 때 datakitOrigin을 DataKit의 도메인 이름 또는 IP로 설정합니다.

콘솔에서 applicationId, clientToken, site 등의 매개변수를 가져와 앱 연동을 시작합니다.
SDK 통합 시 datakitOrigin을 구성할 필요가 없으며, 데이터는 기본적으로 공용 DataWay로 전송됩니다.

사용 방법¶

미니 프로그램의 app.js 파일에 다음과 같이 코드를 추가합니다.

참고: 추가 위치는 App() 초기화보다 먼저여야 합니다.

NPMCDN

NPM 패키지 추가 방식은 위챗 공식 npm 추가 방식을 참조하세요.

const { datafluxRum } = require('@cloudcare/rum-miniapp')
// Rum 초기화
datafluxRum.init({
  datakitOrigin: '<DATAKIT ORIGIN>',// 필수, Datakit 도메인 주소, 위챗 미니 프로그램 관리 백엔드에 도메인 화이트리스트를 추가해야 합니다.
  site: "http://172.16.212.186:9529", // 공용 DataWay에 해당하는 사이트의 도메인
  clientToken: "a993f53a8ea04bc6b9350e5e670a3a3b", // 공용 DataWay 업로드에 필요한 클라이언트 토큰, Guance 콘솔에서 앱 생성 시 생성됩니다.
  applicationId: '<앱 ID>', // 필수, dataflux 플랫폼에서 생성된 앱 ID
  env: 'testing', // 선택, 미니 프로그램의 환경
  version: '1.0.0', // 선택, 미니 프로그램 버전
  service: 'miniapp', // 현재 앱의 서비스 이름
  trackInteractions: true,
  traceType: 'ddtrace', // 선택, 기본값은 ddtrace, 현재 ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6가지 유형 지원
  allowedTracingUrls: ['https://api.example.com/v1/', /https:\/\/.*\.my-api-domain\.com\/v2\//], // 전체 요청 URL로 매칭
  allowTraceHeaderWithoutSession: true, // Session이 샘플링되지 않았어도 Trace Header를 주입하며, 이로 인해 RUM 데이터가 업로드되지 않습니다.
})

파일 다운로드 후 로컬 방식으로 추가

const { datafluxRum } = require('./lib/dataflux-rum-miniapp.js')
// Rum 초기화
datafluxRum.init({
  datakitOrigin: '<DATAKIT ORIGIN>',// 필수, Datakit 도메인 주소, 위챗 미니 프로그램 관리 백엔드에 도메인 화이트리스트를 추가해야 합니다.
  site: "http://172.16.212.186:9529", // 공용 DataWay에 해당하는 사이트의 도메인
  clientToken: "a993f53a8ea04bc6b9350e5e670a3a3b", // 공용 DataWay 업로드에 필요한 클라이언트 토큰, Guance 콘솔에서 앱 생성 시 생성됩니다.
  applicationId: '<앱 ID>', // 필수, dataflux 플랫폼에서 생성된 앱 ID
  env: 'testing', // 선택, 미니 프로그램의 환경
  version: '1.0.0', // 선택, 미니 프로그램 버전
  service: 'miniapp', // 현재 앱의 서비스 이름
  trackInteractions: true,
  traceType: 'ddtrace', // 선택, 기본값은 ddtrace, 현재 ddtrace, zipkin, skywalking_v3, jaeger, zipkin_single_header, w3c_traceparent 6가지 유형 지원
  allowedTracingUrls: ['https://api.example.com/v1/', /https:\/\/.*\.my-api-domain\.com\/v2\//], // 전체 요청 URL로 매칭
  allowTraceHeaderWithoutSession: true, // Session이 샘플링되지 않았어도 Trace Header를 주입하며, 이로 인해 RUM 데이터가 업로드되지 않습니다.
})

구성¶

초기화 매개변수¶

매개변수	유형	필수 여부	기본값	설명
`applicationId`	String	예		Guance에서 생성된 앱 ID입니다.
`datakitOrigin`	String	예		DataKit 데이터 업로드 Origin입니다. ❗️ 미니 프로그램 관리 백엔드에 request 화이트리스트를 추가해야 합니다.
`site`	String	예 (`공용 DataWay` 업로드 방식 필수)		공용 DataWay에 해당하는 사이트의 도메인입니다. 참고: `프로토콜(// 포함), 도메인(또는 IP 주소)[및 포트 번호]` 예: https://www.dataway.com, http://100.20.34.3:8088
`clientToken`	String	예 (`공용 DataWay` 필수)		공용 DataWay 업로드에 필요한 클라이언트 토큰으로, Guance 콘솔에서 앱 생성 시 생성됩니다.
`env`	String	아니요		미니 프로그램 앱의 현재 환경입니다. 예: prod: 프로덕션 환경; gray: 카나리 환경; pre: 사전 프로덕션 환경; common: 일상 환경; local: 로컬 환경.
`version`	String	아니요		미니 프로그램 앱의 버전 번호입니다.
`service`	String	아니요		현재 앱의 서비스 이름이며, 기본값은 `miniapp`입니다. 사용자 정의 구성을 지원합니다.
`sampleRate`	Number	아니요	`100`	지표 데이터 수집 백분율입니다. `100`은 전체 수집, `0`은 수집 안 함을 의미합니다.
`sessionSampleRate`	Number	아니요	`100`	`sampleRate`의 호환 별칭입니다. 둘 다 설정된 경우 `sampleRate`가 우선 적용됩니다.
`remoteConfiguration`	Boolean	아니요	`false`	원격 구성 활성화 여부입니다. SDK는 먼저 로컬 구성으로 시작한 다음, 지원되는 구성 항목을 비동기적으로 가져와 적용합니다.
`remoteConfigration`	Boolean	아니요	`false`	`remoteConfiguration`의 기존 철자 호환 항목입니다. 새 프로젝트에서는 사용하지 않는 것이 좋습니다.
`remoteConfigurationFetchTimeout`	Number	아니요	`3000`	원격 구성 요청 제한 시간(밀리초)입니다. 요청 실패 또는 시간 초과 시 로컬 구성을 계속 사용합니다.
`trackInteractions`	Boolean	아니요	`false`	사용자 행동 수집 활성화 여부입니다.
`trackResourceQueryString`	Boolean	아니요	`false`	요청 URL의 쿼리 문자열 수집 여부입니다. 쿼리 문자열에는 토큰 또는 사용자 ID가 포함될 수 있으므로, 보안이 확인된 경우에만 활성화하세요.
`trackRequestErrorResponseBody`	Boolean	아니요	`false`	실패한 요청의 응답 본문을 오류 스택에 기록할지 여부입니다. 응답 본문에는 민감한 데이터가 포함될 수 있습니다.
`requestErrorResponseLengthLimit`	Number	아니요	`32768`	실패한 요청 응답 본문이 오류 스택에 기록될 수 있는 최대 문자 수입니다. `trackRequestErrorResponseBody`가 활성화된 경우에만 적용됩니다.
`trackLaunchOptions`	Boolean	아니요	`false`	미니 프로그램 시작 매개변수 중 `query` 및 `referrerInfo` 수집 여부입니다.
`beforeSend`	Function	아니요		데이터가 전송 큐에 들어가기 전의 콜백으로, 이벤트를 수정할 수 있습니다. `false`를 반환하면 View가 아닌 이벤트를 폐기할 수 있습니다. 콜백 예외는 비즈니스 로직이나 SDK를 중단시키지 않습니다.
`userId` / `user_id`	String	아니요		초기화 시 로그인 사용자 ID를 설정합니다. 초기화 후 `setUser({ id })`를 호출하여 설정할 수도 있습니다.
`traceType`	Enum	아니요	`ddtrace`	분산 추적 도구 유형을 구성합니다. 구성하지 않으면 기본값은 `ddtrace`입니다. 현재 `ddtrace`, `zipkin`, `skywalking_v3`, `jaeger`, `zipkin_single_header`, `w3c_traceparent` 6가지 데이터 유형을 지원합니다. ❗️ 1. `opentelemetry`는 `zipkin_single_header`, `w3c_traceparent`, `zipkin`, `jaeger` 4가지 유형을 지원합니다. 2. 해당 유형의 traceType을 구성하려면 해당 API 서비스에 대해 서로 다른 `Access-Control-Allow-Headers`를 설정해야 합니다. 자세한 내용은 APM과 RUM 연동 방법을 참조하세요.
`traceId128Bit`	Boolean	아니요	`false`	128비트 `traceID` 생성 여부입니다. `traceType`에 해당하며, 현재 `zipkin`, `jaeger`를 지원합니다.
`allowedTracingUrls`	Array	아니요	`[]`	Trace Header 주입이 허용되는 전체 요청 URL 일치 목록입니다. 문자열은 URL 접두사로 일치합니다. 정규식과 함수는 전체 URL을 받습니다. 객체는 `{ match, traceType }`을 사용하여 단일 규칙에 대한 전파 유형을 지정합니다. 버전 2.2.19 이상이 필요합니다.
`allowedTracingOrigins`	Array	아니요		더 이상 사용되지 않는 호환 구성입니다. 요청 Origin만 정확히 일치시킵니다. 새 프로젝트에서는 `allowedTracingUrls`를 사용하세요. 둘 다 설정된 경우 `allowedTracingUrls`가 우선 적용됩니다.
`allowTraceHeaderWithoutSession`	Boolean	아니요	`false`	현재 Session이 샘플링에 포함되지 않은 경우, `allowedTracingUrls`와 일치하는 요청에 여전히 Trace Header를 주입할지 여부입니다. 활성화해도 해당 Session의 RUM 데이터가 강제로 샘플링되거나 업로드되지는 않습니다.
`isIntakeUrl`	Function	아니요	`function(url) {return false}`	사용자 정의 메서드로, 요청 리소스 URL을 기반으로 해당 리소스 데이터를 수집해야 하는지 여부를 판단합니다. 기본값은 모두 수집입니다. 반환값: `false`는 수집함을, `true`는 수집하지 않음을 의미합니다. ❗️ 1. 이 매개변수 메서드의 반환 결과는 반드시 Boolean 유형이어야 합니다. 그렇지 않으면 유효하지 않은 매개변수로 간주됩니다. 2. 버전 2.1.10 이상이 필요합니다.

Trace Header URL 일치¶

allowedTracingUrls는 전체 요청 URL을 사용하여 일치시킵니다. 문자열은 접두사 일치를 사용하고, RegExp와 Function은 전체 URL을 받습니다. 특정 규칙에 대해 다른 전파 유형을 지정해야 하는 경우 match와 traceType을 모두 포함하는 객체를 사용합니다.

allowedTracingUrls: [
  'https://api.example.com/v1/',
  /https:\/\/.*\.my-api-domain\.com\/v2\//,
  function (url) {
    return url.indexOf('https://internal.example.com/') === 0
  },
  { match: 'https://otel.example.com/', traceType: 'w3c_traceparent' },
]

allowedTracingOrigins는 이전 구성과의 호환성을 위해서만 사용됩니다. 문자열과 정규식 모두 요청 Origin을 기준으로 일치시킵니다. 두 매개변수가 모두 구성된 경우 SDK는 allowedTracingUrls만 사용합니다.

샘플링되지 않은 Session의 Trace Header¶

allowTraceHeaderWithoutSession의 기본값은 false입니다. true로 설정하면 현재 Session이 RUM 샘플링에 포함되지 않은 경우에도 SDK는 allowedTracingUrls와 일치하는 요청에 Trace Header를 주입합니다. 이 구성은 강제로 샘플링하거나 새 Session을 생성하지 않으며, 샘플링되지 않은 Session의 View, Action, Resource, Error 등의 RUM 데이터를 업로드하지 않습니다.

참고 사항¶

datakitOrigin에 해당하는 DataKit 도메인은 미니 프로그램 관리 백엔드에 request 화이트리스트를 추가해야 합니다.
현재 위챗 미니 프로그램의 리소스 요청 API wx.request, wx.downloadFile이 반환하는 데이터에서 profile 필드는 iOS 시스템에서 반환을 지원하지 않으므로, 수집된 리소스 정보 중 타이밍 관련 데이터가 완전히 수집되지 않을 수 있습니다. 현재 이에 대한 해결 방법은 없습니다. request, downloadFile, API 지원 현황.
trackInteractions 사용자 행동 수집을 활성화하면 위챗 미니 프로그램의 제한으로 인해 컨트롤의 콘텐츠 및 구조 데이터를 수집할 수 없습니다. 따라서 미니 프로그램 SDK에서는 선언형 프로그래밍 방식을 채택하여 wxml 파일에 data-name 속성을 설정하여 인터랙션 요소에 이름을 추가함으로써 이후 통계에서 작업 기록을 쉽게 식별할 수 있습니다. 예를 들면 다음과 같습니다.

<button bindtap="bindSetData" data-name="setData">
  setData
</button>