Log 설정¶
이 문서는 HarmonyOS Log 초기화 설정을 설명합니다.
샘플링 필드 마이그레이션(
ft_sdk >= 0.1.18):setLogSamplingRate는 0~100의 부동 소수점 백분율을 사용합니다. 기존setSamplingRate는 0~1 단위를 유지하며, 마이그레이션 시 값에 100을 곱합니다. 새 필드는 명시적으로 설정한 경우에만 기존 필드보다 우선하며, 유효하지 않은 값은 예외를 발생시키고 이전의 유효한 값을 변경하지 않습니다. 이 버전 미만에서는 계속 기존 메서드를 사용합니다. 폐기는 제거를 의미하지 않으며, 기존 메서드는 원래 단위와 동작을 유지합니다.
초기화 설정¶
import { FTSDK, FTLoggerConfig, Status } from '@guancecloud/ft_sdk/Index';
const logConfig = new FTLoggerConfig()
.setLogSamplingRate(100)
.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);
| 메서드 이름 | 유형 | 필수 | 의미 |
|---|---|---|---|
setLogSamplingRate |
number |
아니요 | 로그 수집률을 설정합니다. 값 범위는 [0,100]이며, 0은 수집하지 않음, 100은 전체 수집을 의미합니다. 기본값은 100이고 소수를 지원합니다. ft_sdk 0.1.18 이상에서 지원됩니다. |
setSamplingRate |
number |
아니요 | 더 이상 사용되지 않는 호환 API이며, 값 범위는 [0,1], 기본값은 1입니다. setLogSamplingRate를 대신 사용하세요. |
setEnableCustomLog |
boolean |
아니요 | 사용자 지정 로그를 활성화할지 여부이며, 기본값은 false입니다. |
setPrintCustomLogToConsole |
boolean |
아니요 | FTLogger.logBackground(...) 사용자 지정 로그를 HiLog에도 출력할지 여부이며, 기본값은 false입니다. setEnableCustomLog(true)와 SDK setDebug(true)를 활성화해야 하며, 출력은 setSdkLogLevel(...)의 제어를 받습니다. 자세한 내용은 사용자 지정 로그를 HiLog로 출력을 참조하세요. |
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)도 함께 활성화하는 것이 좋습니다. - 로그량이 많은 경우 샘플링 비율과 레벨 필터링을 통해 전송량을 제어할 수 있습니다.