文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>腾讯云可观测平台>终端性能监控 Pro>接入指南>日志 SDK 接入指引（iOS）>API 说明

API 说明

最近更新时间：2025-12-12 10:52:41

我的收藏

本页目录：

本文详细介绍终端性能监控 Pro 日志 SDK 的功能接口，帮助您更加灵活、深度地使用日志 SDK。

SDK 日志打印模块说明

SDK 内置的打印日志能力基于微信 Mars-xlog 方案，对外提供能力在 TDLoggingIMPProtocol(TDOS_Diagnose/Classes/LogReport/TDLoggingIMPProtocol.h) 中定义，主要包含如下本地日志打印、日志染色、日志文件获取等功能，使用方法如下。
// 头文件
#import <TDOS_Diagnose/TDOSLoggerProxy.h>

// 初始化方式：
@interface TDOSLogger : NSObject <TDLoggingIMPProtocol>

/// 根据配置初始化日志SDK
/// @param config 配置
- (instancetype)initWithConfig:(TDOSLoggerConfig *)config;

@end

// 其中，TDOSLoggerConfig配置包含如下可选设置项：

/// 日志目录
@property (nonatomic, readonly) NSString *logPath;
/// 默认日志级别，默认RAFTLogLevel_Error
@property (nonatomic, readonly) RAFTLogLevel defaultLogLevel;
/// 加密Key
@property (nonatomic, readonly) NSString *publicKey;
/// 控制台是否输出，默认关闭
@property (nonatomic, assign) BOOL enableConsoleLog;
/// 日志文件名前缀（可选设置）
@property (nonatomic, copy) NSString *logFilePrefix;

关于能力的说明请参见如下内容。

基础能力

包含打印日志、设置日志级别、强制日志落地等。其中日志级别遵循 RAFT 日志定义—— RAFTLogDef(Log/RAFTLogDef.h) ，提供7个级别。
RAFTLogLevelVerbose = 0,
RAFTLogLevelDebug = 1,
RAFTLogLevelInfo = 2,
RAFTLogLevelWarn = 3,
RAFTLogLevelError = 4,
RAFTLogLevelFatal = 5,
RAFTLogLevelNone = 6,
在此基础上，TDOS_DiagnoseSDK 提供了5个宏定义，以便业务快速接入。这些宏定义在 TDOSLoggerProxy 中，如下所示：
#define TDLogDebug(tag, format, ...)
#define TDLogInfo(tag, format, ...)
#define TDLogWarn(tag, format, ...)
#define TDLogError(tag, format, ...)
#define TDLogFatal(tag, format, ...)
原始具体接口如下所示：
/// 打印日志接口（不带格式化字符串）
- (void)log:(RAFTLogLevel)level
        tag:(NSString *)tag
       file:(const char *)file
       func:(const char *)func
       line:(int)line
        msg:(NSString *)msg;

/// 打印日志接口（带格式化字符串）
- (void)log:(RAFTLogLevel)level
        tag:(NSString *)tag
       file:(const char *)file
       func:(const char *)func
       line:(int)line
     format:(NSString *)format, ... __attribute__((format(__NSString__, 6, 7))) NS_REQUIRES_NIL_TERMINATION;

/// 获取当前是否处于染色状态
- (BOOL)isColorState;

/// 重置染色级别
- (void)resetColorLevel;

/// 设置Log打印级别
/// @param level 日志级别
- (void)setLogLevel:(RAFTLogLevel)level;

/// 设置打印log的特殊级别, 以及特殊级别的过期时间
/// @param level 日志级别
/// @param endtime 结束时间
- (void)setLogLevel:(RAFTLogLevel)level endTimestamp:(time_t)endtime;

/// 强制写入日志到文件
/// @param isSync 是否同步写入
- (void)flushLog:(BOOL)isSync;

更多日志设置能力

包含设置本地日志最大保留时间（默认10天）、设置本地保留的最大日志总量、设置控制台日志输出、设置日志落地时机等。
/// 设置日志最大存留时间
/// @param time 单位s，默认10（10*24*60*60）天
- (void)setMaxLogAliveTime:(long)time;

/// 设置总的日志文件大小，超出即清理（底层限制最小50M）
/// @param maxSize 总文件大小，默认为0不限制
- (void)setMaxTotalLogFileSize:(int64_t)maxSize;

/// 设置控制台log输出
/// @param enabled 是否开启
- (void)setConsoleLogEnabled:(BOOL)enabled;

日志信息获取

获取指定时间范围内的小时级日志文件列表（含大小限制功能）、日志文件夹路径及日志加密公钥。
/// 获取日志列表（按小时打印）
/// @param startTime 开始时间戳
/// @param endTime 结束时间戳
- (nullable NSArray<NSString *> *)getPeroidLogFilesWithStartTime:(NSTimeInterval)startTime
                                                         endTime:(NSTimeInterval)endTime;
                                                         
/// 获取日志列表，支持限定最大日志量
/// （超过大小优先丢弃旧文件）
///
/// @param startTime 开始时间戳
/// @param endTime 结束时间戳
/// @param sizeLimit 最大日志包
- (nullable NSArray<NSString *> *)getPeroidLogFilesWithStartTime:(NSTimeInterval)startTime
                                                         endTime:(NSTimeInterval)endTime
                                                       sizeLimit:(unsigned long long)sizeLimit;

/// 获取日志文件夹路径。
- (NSString *)getLogFolderPath;

/// 获取日志加密公钥
- (nullable NSString *)getLogEncryptPublicKey;

主动触发拉取捞日志命令（Push，可选）

业务可以结合自身 App 的 Push 通道，触发主动拉取捞日志命令。通过业务自身的 Push 能力，可更及时收到日志捞取命令，减少等待时间。
注意：
业务自身 Push 下发能力需要与平台进行对接，或在新建查询后，主动触发一次对应指令。
客户端在收到 Push 命令后，需主动调用 TDOS_Diagnose SDK 的如下接口，实现及时请求捞日志配置。
/// 主动拉取捞日志命令
///
/// 调用场景：如收到Push消息时
- (void)requestLogConfigFromServer;

// 调用示例：
#import <TDOS_Diagnose/TDOS_Diagnose.h>
[TDLogSDK.sharedInstance requestLogConfigFromServer];

中国站
目录