콘텐츠로 이동

Log 설정

이 문서는 HarmonyOS Log 초기화 설정을 다룹니다.

초기화 설정

import { FTSDK, FTLoggerConfig, Status } from '@guancecloud/ft_sdk/Index';

const logConfig = new FTLoggerConfig()
  .setSamplingRate(1.0)
  .setEnableCustomLog(true)
  .setEnableConsoleLog(true, '[business]')
  .setLogLevelFilters([
    Status.ERROR,
    Status.WARN,
    Status.INFO,
    Status.DEBUG
  ])
  .setEnableLinkRumData(true)
  .addGlobalContext('log_source', 'business')
  .setLogCacheLimitCount(10000);

FTSDK.installLogConfig(logConfig);
메서드 타입 필수 설명
setSamplingRate number 아니요 로그 샘플링 비율, 범위 [0.0, 1.0], 기본값 1.0
setEnableCustomLog boolean 아니요 사용자 정의 로그 활성화 여부, 기본값 false
setEnableConsoleLog enable: boolean, prefix?: string 아니요 콘솔 로그 업로드 여부, 이 설정은 Hvigor Plugin이 필요하며 기본값은 false입니다. console.log, debug, info, warn, error, trace 및 @ohos.hilog 또는 @kit.PerformanceAnalysisKit에서 가져온 hilog.debug, info, warn, error, fatal을 지원합니다. 로그 레벨 대응 관계는 log, info -> info, debug, trace -> debug, warn -> warn, error -> error, fatal -> fatal입니다. prefix에는 일반 메시지 접두사 또는 {로 시작하는 DataKit 수집 규칙을 전달할 수 있습니다. 자세한 내용은 콘솔 로그 필터링을 참조하세요. 이 기능을 사용하려면 ft-sdk 0.1.17 이상 버전과 @cloudcare/hvigor-ohos-plugin 0.1.1 이상 버전이 필요합니다.
setEnableLinkRumData boolean 아니요 RUM 데이터 연결 여부, 기본값 false
setLogLevelFilters Array<Status | string | { name: string }> 아니요 로그 레벨 필터링, 선택 값: ERROR, WARN, INFO, DEBUG
addGlobalContext Dictionary 아니요 Log 전역 속성 추가, key,value 지원. 추가 규칙은 여기를 참조하세요.
addGlobalContext key: string, value: object 아니요 Log 전역 속성 추가, 추가 규칙은 여기를 참조하세요.
setLogCacheLimitCount number 아니요 로그 데이터 캐시 수량 제한, 기본값 5000, 최소값 1000
setLogCacheDiscardStrategy LogCacheDiscard 아니요 로그가 제한 상한에 도달한 후의 로그 폐기 규칙을 설정합니다. 기본값은 LogCacheDiscard.DISCARD이며, DISCARD는 새로 추가되는 데이터를 폐기하고 DISCARD_OLDEST는 오래된 데이터를 폐기합니다.

콘솔 로그 필터링

setEnableConsoleLog(true, prefix)의 두 번째 인자는 자동으로 수집되는 console.* 및 hilog.* 로그를 필터링하는 데 사용됩니다.

  • 일반 문자열을 전달하면 기존 호환 동작을 유지하며, 메시지가 해당 문자열로 시작하는 로그만 수집합니다. 전달하지 않으면 필터링하지 않습니다.
  • 첫 번째 공백이 아닌 문자가 {인 문자열을 전달하면 DataKit 규칙 구문에 따라 허용 규칙으로 처리합니다. 규칙에 일치하는 로그는 SDK 큐에 들어가고, 일치하지 않는 로그는 큐에 들어가기 전에 폐기됩니다. 여러 규칙 블록은 '또는(OR)' 관계입니다.

규칙에서는 message, log_source(console 또는 hilog)를 사용할 수 있으며, hilog에서는 tag와 domain도 사용할 수 있습니다. 로그 레벨은 여전히 setLogLevelFilters(...)가 별도로 제어합니다.

const logConfig = new FTLoggerConfig().setEnableConsoleLog(true,
  "{ log_source = 'hilog' and tag = 'Network' and message match ['^HTTP'] }");

Logger 로그 출력

FTLogger로 사용자 정의 로그를 업로드하려면 먼저 setEnableCustomLog(true)를 활성화해야 합니다. 단일 로그 콘텐츠의 최대 크기는 30 KB이며, 초과된 부분은 잘립니다.

사용 방법

/**
 * 단일 사용자 정의 로그를 업로드합니다.
 *
 * @param content 로그 내용입니다.
 * @param status 로그 레벨, `Status` 또는 레벨 문자열을 전달할 수 있습니다.
 * @param property 추가 속성(선택 사항)입니다.
 * @param isSilence 음소거 처리 여부(선택 사항)입니다.
 */
FTLogger.logBackground(
  content: string,
  status: Status | string,
  property?: Map<string, object>,
  isSilence?: boolean
): void

코드 예시

import { FTLogger, Status } from '@guancecloud/ft_sdk/Index';

// 단일 로그를 업로드합니다.
FTLogger.logBackground('登录成功', Status.INFO);

// 추가 속성을 전달합니다.
const property = new Map<string, object>();
property.set('user_id', new String('user-001'));
FTLogger.logBackground('支付完成', Status.INFO, property);

로그 레벨

메서드 이름 의미
Status.TRACE 추적
Status.DEBUG 디버그
Status.INFO 정보
Status.WARN 경고
Status.ERROR 오류
Status.FATAL 치명적 오류

사용 권장 사항

  • setLogLevelFilters(...)는 FTLogger 비즈니스 Log의 업로드 레벨을 제어하며, SDK 내부 진단 로그의 setSdkLogLevel(...)과 서로 독립적입니다.
  • setEnableConsoleLog(...)와 setEnableCustomLog(...)는 서로 독립적입니다. 전자는 console.* 및 hilog.* 로그를 자동 수집하는 데 사용되며 Hvigor Plugin을 설치하고 구성해야 합니다. 후자는 FTLogger로 사용자 정의 로그를 수동 업로드하는 데 사용되며 플러그인을 설치할 필요가 없습니다.
  • 디버깅 단계에서는 setEnableCustomLog(true), setDebug(true) 및 SDK 디버그 로그를 함께 사용하여 수집 파이프라인을 검증할 수 있습니다.
  • 로그를 사용자 행동, 페이지 및 리소스 데이터와 연계하여 분석하려면 setEnableLinkRumData(true)를 함께 활성화하는 것이 좋습니다.
  • 로그 양이 많은 경우 샘플링 비율과 레벨 필터링을 통해 업로드 양을 제어할 수 있습니다.

문서 평가

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