미니앱 로그 수집¶

미니앱 Logs SDK는 Guance로 비즈니스 로그를 전송하고 콘솔, 런타임 및 네트워크 오류를 자동으로 수집합니다. 로그는 browser_log 소스로 기록되며 로그 탐색기에서 검색할 수 있습니다. MiniApp RUM SDK와 함께 사용하면 앱, 세션, 페이지 및 사용자 정보를 연결할 수 있습니다.

이 문서는 SDK 1.0.6 기준으로 연동 방법과 동작을 설명합니다. 버전 변경 사항은 SDK 업데이트 로그를 참조하세요.

시작하기¶

1. 설치 및 가져오기¶

npm을 통한 설치를 권장하며 datafluxLogs 진입점을 사용합니다:

npm install @cloudcare/dataflux-rum-miniapp-logs

앱 진입점에서 SDK를 가져오고 비즈니스 로그와 요청이 발생하기 전에 초기화를 완료합니다. 네이티브 미니앱 개발 도구를 사용하는 경우 도구 요구사항에 따라 npm 빌드를 수행하세요.

const { datafluxLogs } = require('@cloudcare/dataflux-rum-miniapp-logs')

SDK 파일을 다운로드하여 미니앱 프로젝트에 넣은 후 로컬 경로에서 가져올 수도 있습니다. 아래 경로는 파일의 실제 위치에 맞게 조정해야 합니다:

const { datafluxLogs } = require('./dataflux-rum-miniapp-logs.js')

SDK는 사용 가능한 wx, my, swan, tt 또는 uni 요청 인터페이스를 자동으로 선택하여 각각 WeChat, Alipay, Baidu, Douyin 및 uni 호스트에 대응합니다. 여러 인터페이스가 동시에 존재하는 경우 위 순서대로 선택합니다. uni 프로젝트를 사용하는 경우 미니앱 코드에서 SDK를 가져와 초기화해야 합니다. 디바이스, 네트워크, 스토리지 또는 라이프사이클 인터페이스가 없는 경우 각각 독립적으로 폴백됩니다. 사용 가능한 요청 인터페이스가 없으면 로그를 수집하지 않고 초기화 안내를 출력합니다.

SDK는 미니앱 호스트에서 실행되며 설치 패키지에는 engines.node 제한이 설정되어 있지 않습니다. Node.js는 개발 단계의 빌드, 테스트 및 배포 도구에만 사용되며, 해당 버전은 각 개발 의존성의 요구사항을 충족해야 합니다.

2. 초기화¶

보고 방식을 하나 선택하여 앱 수명주기 내에서 한 번 초기화합니다. 보고 주소는 미니앱에서 접근 가능해야 하며 대상 플랫폼 요구사항에 따라 요청 도메인을 구성해야 합니다.

datafluxLogs.init({
  datakitOrigin: 'https://datakit.example.com',
  applicationId: '<APPLICATION_ID>',
  service: 'miniapp',
  env: 'prod',
  version: '1.0.0'
})

datafluxLogs.init({
  site: '<PUBLIC_DATAWAY_URL>',
  clientToken: '<CLIENT_TOKEN>',
  applicationId: '<APPLICATION_ID>',
  service: 'miniapp',
  env: 'prod',
  version: '1.0.0'
})

init()를 반복 호출해도 구성이 업데이트되지 않습니다. silentMultipleInit: true는 중복 초기화 안내만 끕니다.

3. 로그 전송 및 조회¶

초기화 후 동일 모듈에서 datafluxLogs를 사용합니다. 다른 페이지에서도 앞서 설명한 방식으로 동일한 SDK 모듈을 가져올 수 있습니다.

datafluxLogs.logger.info('应用启动', { entry: 'home' })
datafluxLogs.logger.warn('库存不足', { product_id: 'product-123' })
datafluxLogs.logger.error('支付失败', { order_id: 'order-123' })

로그는 배치 단위로 전송되며 기본적으로 30초마다 전송을 시도합니다. 배치 임계값에 도달하거나 앱이 백그라운드로 전환될 때도 전송이 트리거됩니다. 로그 탐색기에서 소스 browser_log, service, 로그 본문 또는 사용자 정의 필드로 검색할 수 있습니다.

구성¶

초기화 매개변수¶

선택한 보고 방식에 필요한 주소와 토큰 외에 다른 매개변수는 모두 선택 사항입니다. 샘플링은 SDK 초기화 시 결정되며 동일한 실행 인스턴스 내에서 해당 결과가 유지됩니다. 각 로그가 독립적으로 무작위 샘플링되는 것은 아닙니다.

1.0.6부터 미구현 초기화 옵션인 tags, trackInteractions, allowedTracingOrigins, traceId128Bit, traceType이 제거되었습니다. 사용자 정의 필드는 컨텍스트 API를 사용하며, 인터랙션 및 트레이스 수집은 RUM SDK에서 구성합니다.

사용¶

로그 레벨¶

기본 Logger는 datafluxLogs.logger이며 기본 레벨은 debug, 기본 전송 방식은 HTTP입니다. 해당 메서드를 직접 호출할 수 있습니다:

message는 문자열이고 context는 선택적인 필드 객체입니다. log(message, context, status)로 레벨을 명시적으로 지정할 수도 있으며, status를 생략하면 info입니다. warn()의 상태 값은 warning이라는 점에 유의하세요:

datafluxLogs.logger.log('库存不足', { product_id: 'product-123' }, 'warning')

setLevel()로 최소 레벨을 설정하면 해당 레벨보다 낮은 로그는 출력되지 않습니다. 레벨 순서는 debug → info → warning → error → critical입니다:

datafluxLogs.logger.setLevel('warning')

사용자 정의 Logger¶

비즈니스 모듈별로 Logger를 생성하여 레벨, 출력 방식 및 영구 컨텍스트를 각각 설정할 수 있습니다:

const paymentLogger = datafluxLogs.createLogger('payment', {
  level: 'info',
  handler: 'http',
  context: { module: 'payment' }
})

paymentLogger.info('创建订单', { order_id: 'order-123' })

createLogger(name, configuration)는 생성된 Logger를 반환하며 이후 getLogger(name)으로 가져올 수 있습니다. 생성되지 않은 이름은 undefined를 반환합니다. configuration의 level, handler, context는 모두 생략할 수 있으며 기본값은 각각 debug, http, 빈 객체입니다.

setHandler()로 출력 방식을 전환할 수 있습니다:

const paymentLogger = datafluxLogs.getLogger('payment')
if (paymentLogger) {
  paymentLogger.setHandler('console')
}

자동 수집된 오류는 기본 Logger로 출력되므로 datafluxLogs.logger의 레벨이나 출력 방식을 변경하면 자동 오류 로그에도 영향을 줍니다. 명명된 Logger의 설정은 해당 Logger에만 적용됩니다.

사용자 정의 필드¶

사용자 정의 필드는 전역 컨텍스트, Logger 컨텍스트 또는 단일 로그 컨텍스트에 넣을 수 있습니다. HTTP 보고 시 동일한 이름의 사용자 정의 필드는 전역 → Logger → 단일 로그 순서로 덮어씁니다.

전역 컨텍스트는 모든 Logger의 HTTP 로그에 적용됩니다:

datafluxLogs.setLoggerGlobalContext({ tenant: 'example' })
datafluxLogs.addLoggerGlobalContext('region', 'cn')
const globalContext = datafluxLogs.getLoggerGlobalContext()
datafluxLogs.removeLoggerGlobalContext('region')

Logger 컨텍스트는 해당 Logger에만 적용됩니다:

datafluxLogs.logger.setContext({ team: 'payments' })
datafluxLogs.logger.addContext('channel', 'miniapp')
datafluxLogs.logger.removeContext('channel')

setLoggerGlobalContext()와 setContext()는 해당 컨텍스트 전체를 교체합니다. add...Context()는 필드를 추가하거나 교체하고, remove...Context()는 필드를 삭제합니다. 전역 컨텍스트를 가져오면 독립적인 스냅샷이 반환되며, 반환된 객체를 수정해도 SDK 내부에 저장된 데이터는 변경되지 않습니다.

단일 로그 컨텍스트는 해당 호출에만 적용됩니다:

datafluxLogs.logger.info('支付完成', {
  order_id: 'order-123',
  amount: 0,
  paid: true,
  customer: { id: 'customer-123' },
  items: ['product-123']
})

필드는 스칼라, 객체 및 배열을 지원합니다. 0, false 같은 유효한 값은 유지됩니다. 객체와 배열은 보고 시 JSON 문자열로 직렬화되고, BigInt는 정확한 10진수 문자열로 전송됩니다. 일반 비즈니스 필드는 컨텍스트 루트에 직접 넣을 수 있으며 tags: { ... } 형식도 호환됩니다. 여기서의 tags도 최종적으로 사용자 정의 로그 필드로 전송됩니다.

컨텍스트는 독립적인 스냅샷을 사용합니다. toJSON(key)가 있는 객체는 원본 인스턴스에서 실제 필드 이름으로 직렬화된 후 결과가 저장되므로 프라이빗 필드를 포함한 마스킹기를 지원합니다. 일반 필드의 마스킹기가 실패하면 오류 플레이스홀더 값을 사용하며 마스킹되지 않은 원본 객체로 폴백하지 않습니다.

HTTP 로그의 루트 컨텍스트와 중첩 tags는 딕셔너리 결과만 허용합니다. 유효하지 않은 결과는 무시되고 유효한 영구 필드는 유지됩니다. 영구 컨텍스트를 설정할 때 루트 마스킹기가 실패하거나 딕셔너리가 아닌 값을 반환하면 빈 딕셔너리로 초기화됩니다. 단일 로그는 영구 컨텍스트를 수정하지 않습니다.

비즈니스 필드는 message, status, service 등 표준 필드와 같은 이름을 피해야 합니다. 동일한 이름의 비즈니스 데이터는 business 객체에 넣을 수 있습니다. message와 status는 로그 호출 매개변수에 의해 결정되며, type은 SDK 내부 로그 유형으로 고정되어 컨텍스트로 교체할 수 없습니다.

수동 오류 기록¶

logger.error()는 본문과 컨텍스트를 받습니다. Error의 스택을 기록해야 하는 경우 error.stack에 명시적으로 넣으세요:

const error = new Error('支付接口超时')
datafluxLogs.logger.error(error.message, {
  order_id: 'order-123',
  error: { stack: error.stack }
})

수동 오류는 기본적으로 error_source=logger로 보고됩니다. 단일 로그에 명시적으로 전달된 error.source는 기본 소스를 덮어쓸 수 있으며, 자동 오류는 실제 소스를 유지합니다.

자동 오류 수집¶

기본적으로 활성화되어 있으며 forwardErrorsToLogs: false로 끌 수 있습니다. 수집 기능은 호스트가 제공하는 API에 따라 달라집니다:

네트워크 오류 자동 수집을 위해서는 비즈니스 호출이 success, fail 또는 complete 콜백을 제공하고 안전하게 복사할 수 있는 일반 매개변수 객체를 사용해야 합니다. 동결된 객체, 빈 프로토타입 딕셔너리, 열거 불가능한 데이터 속성, Symbol 메타데이터 및 반응형 Proxy의 유효한 값은 모두 유지할 수 있습니다. 원래 콜백 매개변수, 반환값, 예외 및 네이티브 task/Promise는 변경되지 않습니다.

다음과 같은 경우 요청 완료 로그가 자동으로 생성되지 않습니다:

• 호출에 콜백이 제공되지 않은 경우. SDK는 콜백을 주입하지 않으며 비즈니스 Promise를 읽거나 구독하지 않아 기존 반환 패턴과 처리되지 않은 거부 이벤트를 유지합니다.
• 매개변수에 접근자 또는 특수 프로토타입이 포함된 경우. SDK는 원래 매개변수를 호스트에 전달하여 기존 읽기 동작을 유지합니다.
• 요청이 Logs 자체 또는 제외된 RUM 업로드 주소에 속하는 경우.

HTTP 4xx는 상태 코드만으로 오류 로그가 생성되지 않습니다. 비즈니스에서 이미 처리한 실패는 logger.error()로 수동 기록할 수 있으며, 처리되지 않은 거부는 호스트 런타임 훅으로 계속 수집할 수 있습니다. 성공한 요청과 제외된 업로드 요청의 응답 본문은 읽지 않습니다.

RUM 연동¶

Logs는 단독으로 사용할 수 있습니다. 사용자 액세스 컨텍스트를 연동해야 하는 경우 MiniApp RUM 연동 문서에 따라 RUM SDK를 초기화하세요. RUM 컨텍스트를 사용할 수 있으면 로그에 해당 앱, 세션, 페이지, 작업 및 사용자 정보가 포함되며, 사용할 수 없어도 독립 로그를 보고할 수 있습니다.

SDK는 로그 발생 시점의 RUM 컨텍스트를 가져옵니다. 지연 오류의 과거 정보가 없거나 만료된 경우 해당 필드를 생략하며 현재 페이지로 대체하지 않습니다. RUM 연동이 없는 경우 일반 즉시 로그에 현재 페이지 라우트를 포함할 수 있지만, RUM 페이지 ID가 임의로 생성되지는 않습니다.

Logs는 자체 업로드 주소와 동일한 수집 주소의 /v1/write/rum을 자동으로 제외합니다. RUM과 Logs가 서로 다른 도메인, 포트 또는 프록시 경로를 사용하는 경우 선택적 rumIntakeUrls를 설정하여 업로드 실패 시 서로를 수집하지 않도록 방지할 수 있습니다:

datafluxLogs.init({
  datakitOrigin: 'https://logs.example.com',
  rumIntakeUrls: ['https://rum.example.com/v1/write/rum']
})

위 구성은 최초 init()에 포함해야 하며 중복 초기화하지 마세요. 목록은 전체 HTTP(S) URL만 허용하며 초기화 시 스냅샷이 저장되고 유효하지 않은 항목은 무시됩니다. 비교 시 프로토콜, 호스트 이름의 대소문자 및 기본 포트를 통일하고 query/fragment를 무시하며 전체 경로와 대소문자를 유지합니다. 동일 도메인의 다른 비즈니스 경로는 제외되지 않습니다.

보고 필드¶

logger.log() 등 로그를 기록하는 메서드는 void를 반환하며 로그 객체를 반환하지 않습니다. SDK는 데이터를 browser_log 소스에 기록합니다. 아래는 고정된 중첩 JSON 반환 구조가 아니라 로그 탐색기에서 자주 사용되는 필드입니다.

platform은 미니앱 호스트를 나타내며 운영체제는 os 등 별도 필드를 사용합니다. device_uuid는 SDK가 생성하여 로컬 스토리지에 저장하는 익명 설치 식별자로, 호스트 AppID나 하드웨어 ID가 아닙니다. 스토리지를 지우면 다시 생성되며, 스토리지를 사용할 수 없는 경우 현재 실행 중에만 유지됩니다.

보고 시점 및 제한¶

이러한 동작은 SDK의 내장 전송 동작이며 공개 초기화 옵션이 아닙니다. 큰 객체나 응답 본문은 단일 로그의 크기를 늘리므로 문제 해결에 필요한 비즈니스 필드만 기록하는 것이 좋습니다.

자주 묻는 질문¶

SDK 업데이트 로그¶

1.0.6(2026-09-09)¶

기능 및 호환성¶

• WeChat, Alipay, Baidu, Douyin 및 uni 호스트의 자동 감지와 디바이스, 네트워크, 스토리지, 라이프사이클 인터페이스의 호환 처리가 개선되었습니다. 선택적 인터페이스를 사용할 수 없으면 안전하게 폴백됩니다.
• Logs를 단독으로 사용할 때 applicationId로 앱 ID를 보고할 수 있습니다. RUM 연동 시 로그 발생 시점의 컨텍스트를 가져와 지연 오류가 현재 페이지나 세션에 연결되는 것을 방지합니다.
• 선택적 rumIntakeUrls가 추가되어 별도 수집 주소의 RUM 업로드를 제외할 수 있습니다. 동일한 수집 주소의 Logs/RUM 업로드는 자동으로 제외되어 업로드 실패 후 서로를 수집하지 않습니다.
• 공개 TypeScript 선언과 배포 패키지의 타입 진입점이 보완되었습니다. engines.node 설치 제한이 제거되어 SDK 런타임은 Node.js에 의존하지 않습니다. 저장소 빌드, 테스트 및 배포 도구는 여전히 각 개발 의존성의 Node.js 요구사항을 충족해야 합니다.

문제 수정¶

• 요청 및 다운로드 인터셉트가 원래 매개변수, 비즈니스 콜백, 반환된 task/Promise 및 처리되지 않은 거부 이벤트에 미치는 영향이 수정되었습니다. 반응형 매개변수의 유효한 값을 유지하며 수집 예외가 더 이상 비즈니스 호출에 영향을 주지 않습니다. 성공한 요청과 제외된 업로드 요청의 응답 본문은 더 이상 읽지 않습니다.
• 컨텍스트 변조, 위험한 속성 병합 및 마스킹 결과의 잘못된 재사용이 수정되었습니다. 원본 객체에서 실제 필드 이름으로 toJSON(key)를 실행하고 독립적인 스냅샷을 저장하여 프라이빗 필드 마스킹기, 객체, 배열 및 BigInt를 지원합니다.
• 루트 컨텍스트 및 중첩 tags가 딕셔너리가 아닌 값을 반환하거나 마스킹에 실패할 때 숫자 필드가 생성되고 기존 필드가 손실되는 문제가 수정되었습니다. 유효하지 않은 컨텍스트는 마스킹되지 않은 원래 값으로 폴백되지 않으며, 단일 로그는 영구 컨텍스트를 수정하지 않습니다.
• 런타임 오류 및 처리되지 않은 거부의 여러 줄 본문, 원본 스택 및 네트워크 진단 필드 손실이 수정되었습니다. 수동 오류 로그의 기본 소스가 logger로 올바르게 보고되며 자동 오류는 실제 소스를 유지합니다.
• 보고 필드 이스케이프, Unicode 바이트 계산, 0/false 등 유효한 값 손실 및 배치 재진입 문제가 수정되었습니다. 앱이 백그라운드로 전환될 때 로그가 즉시 플러시됩니다. platform이 호스트를 올바르게 나타내며 device_uuid는 로컬에 영구 저장된 익명 설치 식별자를 사용합니다.

업그레이드 안내¶

• 미구현 초기화 옵션인 tags, trackInteractions, allowedTracingOrigins, traceId128Bit, traceType이 제거되었습니다. 사용자 정의 필드는 컨텍스트 API를 사용하며 인터랙션 및 트레이스 수집은 RUM SDK에서 구성합니다.
• 콜백 없는 호출과 접근자 또는 특수 프로토타입이 포함된 요청 매개변수는 호스트의 기존 동작을 유지하며 요청 완료 로그가 자동으로 생성되지 않습니다. 비즈니스에서 이미 처리한 실패는 logger.error()로 수동 기록할 수 있으며, 처리되지 않은 거부는 호스트 런타임 훅으로 계속 수집할 수 있습니다.