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)를 함께 활성화하는 것이 좋습니다. - 로그 양이 많은 경우 샘플링 비율과 레벨 필터링을 통해 업로드 양을 제어할 수 있습니다.