README_ZH.md

jlog(基佬哥)

jlog是一款针对Android开发者的日志工具。

orhanobut的logger，ZhaoKaiQiang的KLog和JakeWharton的timber给了我灵感和参考，感谢他们的开源精神。

再结合一些工作上的经验，就撸出了这个库。

希望你会喜欢它。( ^_^ )

特点

• 兼容android logcat，VERBOSE、DEBUG、INFO、WARN、ERROR和WTF全都有，一个都不能少
• 在JSON模式下，jlog会把json内容格式化，便于理解
• jlog提供了调用者的类、方法和行号信息，甚至可以从控制台直接跳转到源文件
• 简化了logcat，jlog使用调用者的类名作TAG（当然也支持自定义TAG）
• 突破了logcat的4000字长度限制
• jlog可以把日志输出到指定的目录和文件中
• 你可以决定哪些级别的日志写入文件中
• 在日志文件的顶部，jlog提供了很多有用的运行环境相关的信息，比如操作系统信息、设备信息和应用信息
• jlog针对写入文件的日志做了格式化，同时提供了足够的信息方便分析，例如时间、日志等级和调用位置
• 混淆后也能工作正常（获取调用位置）
• 支持设置日志文件的时间格式
• 支持设置日志文件的时区（便于调试其他时区的设备）
• 日志按照时间切片写入到不同的文件中，默认是24小时，文件名诸如2016-01-19.log，你也可以指定前缀和时间切片，比如${userid}_2016-01-19_2021.log
• 支持设置日志的存储空间，超过容量后会按日志的最后修改时间清理，时间越早的越先被清理掉，大约清理出一半配置空间的时停止
• 支持上传日志到七牛
• 支持扩展
• TimingLogger可以记录方法运行的时间

依赖

在根目录的build.gradle里添加仓库。

allprojects {
 repositories {
    jcenter()
    maven { url "https://jitpack.io" }
 }

在模块的build.gradle中添加依赖。

dependencies {
     compile 'com.github.JiongBull:jlog:0.1.0'
}

配置

初始化

建议在你的application的onCreate()方法里初始化jlog的全局配置，设置一次终身受用。

public class RootApp extends Application {

    private static Logger sLogger;

    @Override
    public void onCreate() {
        super.onCreate();
        List<String> logLevels = new ArrayList<>();
        logLevels.add(LogLevel.ERROR);
        logLevels.add(LogLevel.WTF);

        sLogger = Logger.Builder.newBuilder(getApplicationContext(), "jlog")
                /* 下面的属性都是默认值，你可以根据需求决定是否修改它们. */
                .setDebug(true)
                .setWriteToFile(false)
                .setLogDir("jlog")
                .setLogPrefix("")
                .setLogSegment(LogSegment.TWELVE_HOURS)
                .setLogLevelsForFile(logLevels)
                .setZoneOffset(TimeUtils.ZoneOffset.P0800)
                .setTimeFormat("yyyy-MM-dd HH:mm:ss")
                .setPackagedLevel(0)
                .setStorage(null)
                .build();
    }

    public static Logger getLogger() {
        return sLogger;
    }
}

build后所有的属性都保存在Logger对象中。修改它的属性，下次就会生效。

如果你的应用的'targetSdkVersion'是23+，不要忘记在闪屏页或首页申请'android.permission.WRITE_EXTERNAL_STORAG'权限。

setDebug(boolean)

默认是true，日志会输出到控制台中。在发布版本的时候请把这个变量设置为false。

logger.setDebug(false);

或

logger.setDebug(BuildConfig.DEBUG);

writeToFile(boolean)

日志开关，如果是true，日志会输出到文件中，默认是false。

  logger.writeToFile(true);

setLogDir(String)

配置日志保存的目录名称，日志目录是位于内部sd卡中，默认名称是jlog.

可以使用应用的名称作为日志目录名。

logger.setLogDir(getString(R.string.app_name));

子目录当然也支持啦，可以使用一些唯一标识作为子目录的名称，比如用户标识。

logger.setLogDir(getString(R.string.app_name) + File.separator + ${userid});

setLogPrefix(String)

如果不想使用子目录，你或许可以试一试日志文件的前缀功能。

logger.setLogPrefix("JiongBull");

setLogSegment(LogSegment)

日志按照时间切片写入到不同的文件中，默认是24小时，文件名诸如2016-01-19.log，如果设置为LogSegment.ONE_HOUR，文件名就会变成诸如2016-01-19_0203.log那样了，表示文件里记录的是2:00到3:00的日志。

logger.setLogSegment(LogSegment.ONE_HOUR);

setLogLevelsForFile(List)

这个方法决定了哪些级别的日志可以输出到文件中。默认的日志级别是LogLevel.ERROR和LogLevel.WTF。

List<LogLevel> logLevels = new ArrayList<>();
logLevels.add(LogLevel.INFO);
logLevels.add(LogLevel.ERROR);
logger.setLogLevelsForFile(logLevels);

setZoneOffset(ZoneOffset)

我们可以指定文件里日志时间的时区，而不受用户位置的影响，这样会更容易定位问题，默认是ZoneOffset.P0800（+0800），表示“北京时间”。

logger.setZoneOffset(ZoneOffset.P0800);

setTimeFormat(String)

默认的时间格式是yyyy-MM-dd HH:mm:ss，你可以使用这个方法让日志更容易理解。

logger.setTimeFormat("yyyy年MM月dd日 HH时mm分ss秒");

setPackagedLevel(int)

如果需要扩展jlog，请设置封装的层级，否则jlog不能获取调用者的信息.

logger.setPackagedLevel(1);

setStorage(IStorage)

可以继承IStorage接口，通过upload接口把日志上传到远程服务器上，它每隔15分钟会被调用一次。

logger.setStorage(new IStorage() {
    @Override
    public void upload(@NonNull Logger logger) {
        // 把日志上传到远程服务器上.
    }
})

有两种已经预定义的IStorage实现，可以直接使用。

• jlog-storage-qiniu, 可以自动把日志上传到七牛
• jlog-storage-disk, 超过容量后会按日志的最后修改时间清理，时间越早的越先被清理掉，大约清理出一半配置空间的时停止

用法

logger.v(String)

jlog默认会使用调用者的类名作TAG。

logger.v(TAG, String)

你也可以自己指定TAG。

logger.json(json)

jlog会把json内容格式化，便于理解。

关于