腾讯云可观测平台 API 说明

本文详细介绍终端性能监控 Pro 日志 SDK 的功能接口，帮助您更加灵活、深度地使用日志 SDK。
Diagnose
Diagnose 是应用的诊断模块，作用是管理诊断数据的配置、收集与上报，以下是接口的详细信息。
TDDiag
TDDiag 接口提供初始化配置、设置用户 ID、接收推送、主动上报日志及刷新配置等功能，用于应用的诊断日志管理与上报。
object TDDiag {
﻿
    /**
     * 初始化
     *
     * @param context
     * @param config
     */
    fun initialize(context: Context, config: TDDiagConfig)
﻿
    /**
     * 初始化
     *
     * @param context
     * @param config
     * @param host 在多个进程初始化时，需要保证只有一个进程设置为true，默认主进程，用于拉取配置和上传日志
     */
    fun initialize(context: Context, config: TDDiagConfig, host: Boolean)
﻿
    /**
     * 设置userId
     */
    fun setUserId(id: String)
﻿
    /**
     * 接收Push
     */
    fun onPush(data: String)
﻿
    /**
     * 主动上报日志
     *
     * @param label 标签，必填，不超过64字节
     * @param fileList 文件路径列表
     * @param summary 摘要，不超过256字节，支持搜索
     * @param extraInfo 附加信息
     * @param listener UI回调
     * @param saveSync 仅同步保存任务，下次启动时上传
     * @see upload
     */
    @Deprecated("Use TDDiag.upload(param) instead")
    @JvmStatic
    fun uploadFiles(
        label: String,
        fileList: List<File>,
        summary: String? = null,
        extraInfo: String? = null,
        listener: UploadListener? = null,
        saveSync: Boolean = false
    )
﻿
    /**
     * 主动上报日志
     *
     * @param label 标签，必填，不超过64字节
     * @param pathList 文件路径列表
     * @param summary 摘要，不超过256字节，支持搜索
     * @param extraInfo 附加信息
     * @param listener UI回调
     * @param saveSync 仅同步保存任务，下次启动时上传
     * @see upload
     */
    @Deprecated("Use TDDiag.upload(param) instead")
    @JvmStatic
    fun uploadPaths(
        label: String,
        pathList: List<String>,
        summary: String? = null,
        extraInfo: String? = null,
        listener: UploadListener? = null,
        saveSync: Boolean = false
    )
﻿
    /**
     * 主动上报日志
     *
     * @param label 标签，必填，不超过64字节
     * @param startTimestamp 开始时间戳（单位：秒），包含此值
     * @param endTimestamp 结束时间戳（单位：秒），不含此值
     * @param extraPathList 文件路径列表
     * @param summary 摘要，不超过256字节，支持搜索
     * @param extraInfo 附加信息
     * @param listener UI回调
     * @param saveSync 仅同步保存任务，下次启动时上传
     * @param sizeLimit （压缩前）文件大小限制，当值小于[限制规则](README.md)时有效，默认不限制
     * @see upload
     */
    @Deprecated("Use TDDiag.upload(param) instead")
    @JvmStatic
    fun uploadLogs(
        label: String,
        startTimestamp: Long,
        endTimestamp: Long,
        extraPathList: List<String>? = null,
        summary: String? = null,
        extraInfo: String? = null,
        listener: UploadListener? = null,
        saveSync: Boolean = false,
        sizeLimit: Long = Long.MAX_VALUE
    )
﻿
    /**
     * 主动上报日志
     */
    @JvmStatic
    fun upload(param: UploadParam)
﻿
    /**
     * 主动刷新配置
     *
     * @param force 强制刷新，不检查拉取间隔
     */
    fun syncConfig(force: Boolean = false): Boolean
}
TDDiagConfig.Builder
TDDiagConfig.Builder 接口用于通过链式方法配置 TDDiag 所需的各项参数（如 appId、appKey、日志适配器、流量配额等），最终构建 TDDiagConfig 实例。
class TDDiagConfig.Builder {
    /**
     * 设置从[TDS-调试诊断平台](https://diagnose.woa.com/)申请的appId
     */
    fun setAppId(appId: String): Builder
﻿
    /**
     * 设置从[TDS-调试诊断平台](https://diagnose.woa.com/)申请的appKey
     */
    fun setAppKey(appKey: String): Builder
﻿
    /**
     * 设置LoggerAdapter，适配打日志模块
     */
    fun setLoggerAdapter(loggerAdapter: LoggerAdapter): Builder
﻿
    /**
     * 注入合规的隐私信息（可选，默认从android.os.Build读取）
     */
    fun setDeviceInfoAdapter(deviceInfoAdapter: DeviceInfoAdapter): Builder
﻿
    /**
     * 自定义app版本（可选，默认从PackageInfo读取）
     */
    fun setAppVersion(appVersion: String): Builder
﻿
    /**
     * 设置标签白名单
     */
    fun setImportantLabels(vararg labels: String): Builder
﻿
    /**
     * 设置每日流量配额（可选，默认不限制）
     *
     * @param total 总流量（单位：字节），要求 >= [metered]
     * @param metered 4G流量（单位：字节），要求 > 0
     */
    fun setTrafficQuota(total: Long, metered: Long): Builder
﻿
    /**
     * 设置自动上报频率限制（可选，默认不限制）
     *
     * @param limit 次数
     * @param period 周期
     * @param timeUnit 周期单位
     */
    fun setUploadCountLimit(limit: Long, period: Long, timeUnit: TimeUnit): Builder
﻿
    /**
     * 设置环境（可选）
     *
     * @param env 默认[TDDiagConfig.ENV_NORMAL]，海外版[TDDiagConfig.ENV_OVERSEAS]
     */
    fun setEnvironment(env: String): Builder
﻿
    /**
     * 生成[TDDiagConfig]
     */
    fun build(): TDDiagConfig
﻿
}
UploadParam
UploadParam 类是主动上传日志的参数配置类，通过构造函数和一系列方法设置标签、日志时间范围、附带文件、附加信息、回调等上传相关参数。
/**
 * 主动上传参数类
 */
class UploadParam {
    /**
     * @param label 标签，必填，不超过64字节
     */
    constructor(label: String)
﻿
    /**
     * 设置日志范围
     *
     * @param startTimestamp 开始时间戳（单位：秒），包含此值
     * @param endTimestamp 结束时间戳（单位：秒），不含此值
     */
    fun setTimestamp(startTimestamp: Long, endTimestamp: Long): UploadParam
﻿
    /**
     * 设置附带文件（或文件夹）列表
     */
    fun setExtraPaths(pathList: List<String>): UploadParam
﻿
    /**
     * 设置附带文件（或文件夹）列表
     */
    fun setExtraFiles(fileList: List<File>): UploadParam
﻿
    /**
     * 设置附加信息
     *
     * @param summary 摘要，不超过256字节，支持搜索
     * @param extraInfo 附加信息
     */
    fun setExtraInfo(summary: String?, extraInfo: String?): UploadParam
﻿
    /**
     * 设置UI回调
     *
     * @param listener UI回调
     * @param disableAsyncRetry 是否禁用重试，默认false，可设为true后在上层自定义重试方式
     */
    fun setListener(listener: UploadListener?, disableAsyncRetry: Boolean): UploadParam
﻿
    /**
     * 设置仅同步保存任务，下次启动时上传
     */
    fun setSaveSync(saveSync: Boolean = true): UploadParam
﻿
    /**
     * 设置（压缩前）文件大小限制，当值小于[限制规则](README.md)时有效
     */
    fun setSizeLimit(sizeLimit: Long): UploadParam
﻿
    /**
     * 设置是否收集日志cache文件，默认不收集
     */
    fun setIncludeCache(includeCache: Boolean = true): UploadParam
﻿
    /**
     * 附加检索信息，用于平台互通（跨系统检索）
     *
     * @param queryKey 专门用于检索日志的key，不超过128字节
     * @param source 调用方来源，不超过128字节
     */
    fun appendExtQueryInfo(queryKey: String, source: String): UploadParam
}
LoggerAdapter
LoggerAdapter 是日志组件适配接口，提供设置染色级别、获取指定时间范围日志文件、强制写入日志、打印 SDK 自身日志及获取日志加密公钥等功能，用于适配日志相关操作。
/**
 * 日志组件适配接口
 */
public interface LoggerAdapter {
    /**
     * 设置染色级别
     */
    void setColorLevel(@LogLevel int level);
﻿
    /**
     * 获取日志文件
     *
     * @param startTimestamp 开始时间戳（单位：秒），包含此值
     * @param endTimestamp 结束时间戳（单位：秒），不含此值
     * @return 日志文件列表
     */
    @Nullable
    List<File> getLogFiles(long startTimestamp, long endTimestamp);
﻿
    /**
     * 获取日志文件
     *
     * @param startTimestamp 开始时间戳（单位：秒），包含此值
     * @param endTimestamp 结束时间戳（单位：秒），不含此值
     * @param includeCache 是否收集cache文件
     * @return 日志文件列表
     */
    @Nullable
    default List<File> getLogFiles(long startTimestamp, long endTimestamp, boolean includeCache) {
        return getLogFiles(startTimestamp, endTimestamp);
    }
﻿
    /**
     * 强制将Log写入文件
     */
    void flushLog();
﻿
    /**
     * 打印sdk自身的日志
     */
    void printDiagnoseLog(@NotNull String tag, @NotNull String msg, @Nullable Throwable tr);
﻿
    /**
     * 获取日志加密公钥（可选，默认null表示未开启加密）
     */
    @Nullable
    default String getPubKey() {
        return null;
    }
﻿
}
DeviceInfoAdapter
DeviceInfoAdapter 是隐私信息适配接口，用于按隐私合规要求提供设备品牌（对应 Build.BRAND）和设备型号（对应 Build.MODEL）信息。
/**
 * 隐私信息适配接口
 */
interface DeviceInfoAdapter {
    /**
     * {@link android.os.Build#BRAND}
     */
    fun getBrand(): String
﻿
    /**
     * {@link android.os.Build#MODEL}
     */
    fun getModel(): String
}
UploadListener
UploadListener 是日志上传过程的回调接口，用于在上传开始、进度更新、上传成功及上传失败（并返回具体失败原因）时触发对应回调，以反馈上传状态。
interface UploadListener {
    /**
     * 开始上传
     */
    fun onStart()
﻿
    /**
     * 进度更新，可能回调0次或多次
     *
     * @param percent 0～100
     */
    fun onProgress(percent: Int)
﻿
    /**
     * 上传成功
     */
    fun onSuccess()
﻿
    /**
     * 上传失败
     *
     * @param reason 失败原因：
     * * -4：本地限制策略，包括：次数限制、流量限制、熔断
     * * -3：向后台同步上传url失败，一般是网络波动
     * * -2：管理端配置的标签抽样限制
     * * -1：重复任务
     * * 1：文件上传网络错误
     * * 2：压缩后的日志文件大小超过阈值
     * * 3：压缩IO错误，一般是存储不足
     * * 4：文件上传时cos后台返回http错误
     * * 5：无本地日志
     */
    fun onFailure(@UploadLogFailReasonType reason: Int)
Logger
Logger 指日志组件，作用是实现日志的规范输出、存储与管理，以下是接口的详细信息。
TDLog
TDLog 类提供日志系统的初始化、子实例创建、不同级别（VERBOSE/DEBUG 等）日志打印，以及日志刷新、关闭和获取默认日志适配器实例等功能，用于日志的管理与输出。
public class TDLog {
﻿
    /**
     * 初始化
     */
    public static void initialize(Context context, TDLogConfig config)
﻿
    /**
     * 创建子实例
     */
    public static ILogInstance getSubInstance(String category, boolean consoleLog, int maxAliveDay, long maxAliveFileSize)
﻿
    /**
     * 获取默认{@link LoggerAdapter}实例
     */
    public static ITDLog getLogImpl()
﻿
    /**
     * 打印{@link LogLevel#VERBOSE}日志
     */
    public static void v(String tag, String message)
﻿
    /**
     * 打印{@link LogLevel#VERBOSE}日志
     */
    public static void v(String tag, String message, Throwable throwable)
﻿
    /**
     * 打印{@link LogLevel#DEBUG}日志
     */
    public static void d(String tag, String message)
﻿
    /**
     * 打印{@link LogLevel#DEBUG}日志
     */
    public static void d(String tag, String message, Throwable throwable)
﻿
    /**
     * 打印{@link LogLevel#INFO}日志
     */
    public static void i(String tag, String message)
﻿
    /**
     * 打印{@link LogLevel#INFO}日志
     */
    public static void i(String tag, String message, Throwable throwable)
﻿
    /**
     * 打印{@link LogLevel#WARN}日志
     */
    public static void w(String tag, String message)
﻿
    /**
     * 打印{@link LogLevel#WARN}日志
     */
    public static void w(String tag, String message, Throwable throwable)
﻿
    /**
     * 打印{@link LogLevel#ERROR}日志
     */
    public static void e(String tag, String message)
﻿
    /**
     * 打印{@link LogLevel#ERROR}日志
     */
    public static void e(String tag, String message, Throwable throwable)
﻿
    /**
     * 打印{@link TDLogInfo}日志
     */
    public static void log(TDLogInfo info)
﻿
    /**
     * 强制把缓冲区日志写入文件
     */
    public static void flushLog()
﻿
    /**
     * 关闭日志实例
     */
    public static void closeLog()
}
TDLogConfig.Build
TDLogConfig.Builder 是日志组件的配置构造器，通过链式方法设置日志级别、是否输出到 Logcat、存储路径、加密公钥、文件大小及保存天数等参数，最终生成 TDLogConfig 实例。
/**
 * 日志组件的配置构造器
 */
public static class TDLogConfig.Build {
﻿
    /**
     * constructor
     */
    public Builder(Context context)
﻿
    /**
     * 设置最低日志级别
     */
    public Builder setLogLevel(@LogLevel int logLevel)
﻿
    /**
     * 设置是否输出到Logcat
     */
    public Builder setConsoleLog(boolean consoleLog)
﻿
    /**
     * 设置日志文件存储路径
     */
    public Builder setLogPath(String logPath)
﻿
    /**
     * 设置日志文件加密的公钥
     */
    public Builder setPubKey(String key)
﻿
    /**
     * 设置单个日志文件大小的最大值
     */
    public Builder setMaxFileSize(long maxFileSize)
﻿
    /**
     * 设置日志文件保存天数
     */
    public Builder setMaxAliveDay(int maxAliveDay)
﻿
    /**
     * 设置日志文件总大小的最大值
     */
    public Builder setMaxAliveFileSize(long maxAliveFileSize)
﻿
    /**
     * 生成{@link TDLogConfig}实例
     */
    public TDLogConfig build()
}
TDLogInfo
TDLogInfo 类是日志信息的载体类，用于封装日志的标签（含一、二、三级）、级别、线程信息、内容、异常对象及时间戳等详细数据。
public class TDLogInfo {
    /**
     * Tag
     */
    public String tag;
    /**
     * 二级Tag
     */
    public String subTag;
    /**
     * 三级Tag
     */
    public String thirdTag;
    /**
     * 日志级别
     */
    @LogLevel
    public int level;
    /**
     * 线程id
     */
    public long tid;
    /**
     * 线程名
     */
    public String tName;
    /**
     * 日志内容
     */
    public String message;
    /**
     * Throwable对象
     */
    public Throwable throwable;
    /**
     * 时间，单位毫秒，默认0表示不指定
     */
    public long timeMillis;
}
ILogInstance
ILogInstance 是日志实例接口，提供打印日志（含普通日志和带自定义信息的日志）、强制写入日志到文件及关闭当前日志实例的功能。
/**
 * 日志实例接口
 */
public interface ILogInstance {
﻿
    /**
     * 打印日志
     */
    void log(String tag, @LogLevel int level, String message, @Nullable Throwable throwable);
﻿
    /**
     * 打印带自定义信息的日志
     */
    void log(TDLogInfo info);
﻿
    /**
     * 强制将Log写入文件
     */
    void flushLog();
﻿
    /**
     * 关闭当前Log实例
     */
    void closeLog();
}
Push 支持（可选）
日志 SDK 会默认在初始化时拉取配置，检查有无日志捞取命令。接入 Push 后可更及时收到日志捞取命令，减少等待时间。
业务需要把自有的 Push 通道与平台对接（平台不提供 Push 能力），当收到捞日志/染色 Push 后，调用以下接口，完成日志捞取/染色。
TDDiag.onPush("{}");
主动检查指令下发（可选）
一般情况下，通过启动时设置 userId 和接入 Push，即可获得很好的捞取指令配置下发实时性。如果 App 希望增加更多检查指令配置下发的时机（例如 App 进入前台时检查），可在对应的时机调用。
TDDiag.syncConfig(false); // false表示不强制刷新
SDK 对主动检查指令配置下发有频率限制，限制策略由后台根据负载情况动态决定。
注意：
不建议在任何没有用户交互的自动触发场景进行强制刷新，避免给后台带来不可控的负载压力。
API 说明

本页目录：

Diagnose

TDDiag

TDDiagConfig.Builder

UploadParam

LoggerAdapter

DeviceInfoAdapter

UploadListener

Logger

TDLog

TDLogConfig.Build

TDLogInfo

ILogInstance

Push 支持（可选）

主动检查指令下发（可选）
