使用

• 使用
  • 初始化
  • 日志策略配置
    • 开启染色日志
    • 设置染色日志的存放路径
    • 设置日志文件名的前缀
    • 设置染色日志的文件大小最大值
    • 设置日志最大的保留时间
    • 设置日志文件加密的 public key
  • 日志能力 API
    • 打印日志
    • flush 接口
    • 染色日志手动开关接口
    • 日志上传手动调用接口
    • 手动日志上传结果回调
    • destroy 接口

染色日志组件主要接口为两类：ColorLogger 及 ColorLogConfig。

• ColorLogger 是日志操作统一入口。
• ColorLogConfig 是染色日志统一配置。

初始化

TMF基础库提供了染色日志的默认最佳实践，正常初始化基础库即可使用染色日志功能，如果需要对日志配置做调整，可参考如下代码

private void initBase(Context context) {
    ColorLogConfig colorConfig = ColorLogConfig.builder(context)
            .setColorLogEnabled(true)//打开染色日志开关
            .setLogNamePrefix("ColorLog")//设置日志文件名的前缀
            .setLogMaxSize(20 << 20)//设置日志文件大小的最大值，单位byte
            .setLogMaxKeepDays(10)//设置文件最长保存时间，单位天
            .setColorLogKey("")//日志加密用的public key，参数设置为空字符即不加密
            .build();

     TMFBaseConfig config = new TMFBaseConfig.Builder()  
            //...
            .colorLogConfig(colorConfig) 
            .build();  

     TMFBase.init(CommonApp.get().getApplication(), config);
}

日志策略配置

ColorLogConfig 该类用于配置染色日志文件相关的配置，可通过控制台下发配置单进行动态配置修改。控制台路径：数据同步 > 日志开关。云端下发配置单生效后，本地默认配置即失效，云端下发的配置单过期后，恢复本地默认配置。具体接口说明如下:

开启染色日志

/**
 * 是否开启染色日志
 * @param enable 默认false，即关闭
 * @return
 */
public Builder setColorLogEnabled(boolean enable)

设置染色日志的存放路径

/**
 * 设置染色日志的存放路径（绝对路径）
 * 默认路径：Environment.getExternalStorageDirectory().getAbsolutePath() + File.separator + "color_log"
 * @param path
 * @return
 */
public Builder setLogDir(String path)

设置日志文件名的前缀

/**
 * 设置日志文件名的前缀
 * 默认文件前缀为ColorLog，生成的文件名示例：ColorLog_20190102.xlog
 * @param logNamePrefix
 * @return
 */
public Builder setLogNamePrefix(String logNamePrefix)

设置染色日志的文件大小最大值

/**
 * 设置染色日志的最大警戒值，当天日志超阈值时将停止日志打印
 * @param size 单位：Byte，默认20M
 * @return
 */
public Builder setLogMaxSize(long size)

设置日志最大的保留时间

/**
 * 设置日志最大的保留天数
 * @param logMaxKeepDays 单位：天，默认：10天
 * @return
 */
public Builder setLogMaxKeepDays(int logMaxKeepDays)

设置日志文件加密的 public key

/**
 * 设置日志文件加密的public key
 * @param logKey 默认为空，即不加密
 * @return
 */
public Builder setColorLogKey(String logKey)

关于染色日志文件的加解密，详见如下链接：Xlog 加密使用指引。

日志能力 API

ColorLogger 该类为日志打印、手动上传、手动开关等统一入口，具体接口说明如下:

打印日志

提供四种常用日志等级，DEBUG、INFO、WARNING、ERROR，对应如下接口：

public static void d(String tag, String message)
public static void i(String tag, String message)
public static void w(String tag, String message)
public static void e(String tag, String message)

入参

Sample

ColorLogger.d("TAG", "ColorLogger LEVEL_DEBUG Demo");
ColorLogger.i("TAG", "ColorLogger LEVEL_INFO Demo");
ColorLogger.w("TAG", "ColorLogger LEVEL_WARNING Demo");
ColorLogger.e("TAG", "ColorLogger LEVEL_ERROR Demo");

flush 接口

调用本接口则主动将内存中的缓存日志写入日志文件中。

/**
 * 调用该接口会把内存中的日志写入到文件
 * @param sync  true 为同步flush，flush结束后才会返回。false为异步flush不等待flush结束就返回。
 */
 public static void flush(boolean sync)

入参

染色日志手动开关接口

组件提供手动开关接口，用于已初始化染色日志配置后，在应用运行过程中，需手动更改日志开关状态的场景，开关接口应根据实际场景搭配使用。使用说明：默认配置为关闭时，调用本打开接口打开日志，则应调用关闭接口及时关闭，恢复默认状态；默认配置为开启时，无需使用本开启接口再次打开，需手动关闭时，可调用关闭接口将直接关闭日志。

注意：本接口使用时仍然受日志文件阈值限制，即若原来当天日志已超阈值，则使用本接口打开日志也无法继续向日志文件中写入日志。

/**
 * 打开日志（init之后才可调用）
 */
public static boolean openLog()

/**
 * 关闭日志（init之后才可调用），与openLog对应
 */
public static boolean closeLog()

Sample

if (ColorLogger.openLog()) {
   for (int i = 0; i < 5000; i++) {
       ColorLogger.d("TAG", "ColorLogger LEVEL_DEBUG Demo.");
   }
   ColorLogger.closeLog();
}

日志上传手动调用接口

/**
 * 染色日志上传手动调用接口
 * @param uploadDate 需要上传日志的日期，日期为8位数标识，如20190101
 * @param callback 日志上传结果回调，不关心结果可置空
 */
public static void upload(String uploadDate, IColorLogUploadCallback callback)

入参

手动日志上传结果回调

public interface IColorLogUploadCallback {

    public static final int ERR_NONE = 0;
    public static final int ERR_EMPTY_UPLOAD_DATE = -1001;//传入的需要上传日志的日期为空
    public static final int ERR_MATCH_NO_FILE = -1002;//不存在与传入的需要上传日志的日期对应的日志文件
    public static final int ERR_UPLOAD_FAILED = -1003;//上传失败，网络原因或其它内部原因

    /**
     * 上传结果回调
     * @param errorCode 错误码
     */
    public void onUploadResult(int errorCode);
}

Sample

ColorLogger.upload("20191111", new IColorLogUploadCallback() {
    @Override
    public void onUploadResult(int errorCode) {
            Log.i("TAG","onUploadResult errorCode=" + errorCode);
    }
});

destroy 接口

注意：在程序退出时请主动调用本接口，本接口会在日志关闭前将缓存日志写入文件。

/**
 * 关闭日志，在程序退出时调用，与init对应
 */
public static void destroy()