From 660e762857e5a962fac6b697d0e592426e4d72e2 Mon Sep 17 00:00:00 2001 From: s1rius Date: Mon, 14 Aug 2023 22:59:45 +0800 Subject: [PATCH] update docs --- README.md | 407 ++++++++++++++++++++++++++++++++++- README.zh-CN.md | 17 -- docs/book.toml | 3 + docs/po/messages.pot | 90 ++++---- docs/po/zh.po | 145 +++++++------ docs/src/architecture.md | 18 +- docs/src/benchmark.md | 10 +- docs/src/build.md | 10 +- docs/src/introduction.md | 8 +- docs/src/platform/android.md | 8 +- docs/src/platform/flutter.md | 8 +- docs/src/platform/ios.md | 8 +- docs/src/platform/rust.md | 9 +- 13 files changed, 559 insertions(+), 182 deletions(-) delete mode 100644 README.zh-CN.md diff --git a/README.md b/README.md index 73dc436..e8997ca 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,16 @@ # ezlog -[中文介绍](README.zh-CN.md)

+[中文介绍](https://s1rius.github.io/ezlog/zh/index.html)

-[ezlog](https://s1rius.github.io/ezlog) is a high efficiency cross-platform logging library. +## What is ezlog? -it is inspired by [Xlog](https://github.com/Tencent/mars) and [Loagan](https://github.com/Meituan-Dianping/Logan), rewrite in Rust. -## Features +ezlog is a high-performance cross-platform file logging library. + +It can be used in Flutter, Android, iOS, Windows, Linux, MacOS. + +It is inspired by [Xlog](https://github.com/Tencent/mars) and [Logan](https://github.com/Meituan-Dianping/Logan), rewrite in Rust. + +### Features - multi platform: Flutter, Android, iOS, Windows, Linux, MacOS - map file into memory by [mmap](https://man7.org/linux/man-pages/man2/mmap.2.html). - compression support, eg: [zlib](https://en.wikipedia.org/wiki/Zlib). @@ -14,8 +19,396 @@ it is inspired by [Xlog](https://github.com/Tencent/mars) and [Loagan](https://g - trim out of date files. - command line parser support. -## Guide level documentation is found on the [website](https://s1rius.github.io/ezlog). +### License + +See [LICENSE-MIT](../../LICENSE-MIT), [LICENSE-APACHE](../../LICENSE-APACHE) +### Android Usage + +#### Add ezlog to dependencies + +Open top-level `build.gradle`, add `mavenCentral` to repositories. + +```groovy +buildscript { + repositories { + ... + mavenCentral() + ... + } +} + +allprojects { + repositories { + ... + mavenCentral() + ... + } +} +``` + +Open app level `build.gradle`, add `ezlog` + +```groovy +dependencies { + implementation "wtf.s1.ezlog:ezlog:0.2+" +} +``` + +Sync gradle + +#### Setup in application + +```kotlin +override fun onCreate() { + super.onCreate() + + val path = File(filesDir, "ezlog").absolutePath + val config = EZLogConfig.Builder("demo", path) + .compress(EZLog.CompressZlib) + .compressLevel(EZLog.CompressFast) + .cipher(EZLog.Aes128Gcm) + .cipherKey("a secret key!!!!".toByteArray()) + .cipherNonce("unique nonce".toByteArray()) + .enableTrace(BuildConfig.DEBUG) + .build() + EZLog.initWith(config) + + EZLog.v("ezlog", "first blood") + + EZLog.registerCallback(object : Callback { + override fun onLogsFetchSuccess( + logName: String?, + date: String?, + logs: Array? + ) { + Log.i("ezlog", "$logName $date ${logs.contentToString()}") + logs?.let { + logs.getOrNull(0)?.let { log -> + Log.i("ezlog", "check file exists ${File(log).exists()}") + } + } + } + + override fun onLogsFetchFail(logName: String?, date: String?, err: String?) { + Log.i("ezlog", "$logName $date $err") + } + }) +} + +``` +### Flutter Usage + +#### Add ezlog_flutter as a dependency in your pubspec.yaml file. + +```yaml +dependencies: + ezlog_flutter: ^0.2.0 +``` + +#### Example + +```dart +import 'dart:io'; +import 'package:flutter/material.dart'; +import 'dart:async'; +import 'package:ezlog_flutter/ezlog_flutter.dart'; +import 'package:path_provider/path_provider.dart'; + +void main() { + runApp(const MyApp()); +} + +class MyApp extends StatefulWidget { + const MyApp({Key? key}) : super(key: key); + + @override + State createState() => _MyAppState(); +} + +class _MyAppState extends State { + + @override + void initState() { + super.initState(); + initEZLog(); + } + + Future initEZLog() async { + EZLog.init(true); + Directory appDocDir = await getApplicationSupportDirectory(); + String logDir = '${appDocDir.path}/ezlog'; + + var logger = EZLogger.config( + EZLogConfig.plaintext("main", Level.trace.id, logDir, 7)); + + logger.d("init", "success"); + + var logs = await EZLog.requestLogFilesForDate("main", "2022_08_25"); + } +} +``` +### iOS Usage + +#### Add ezlog + +Add dependency to Podfile + +```shell +pod 'EZLog', '~> 0.1' +``` +then + +```shell +pod update +``` +#### Open Xcode, add sample code + +```swift +import EZLog + +init() { + pthread_setname_np("main") + #if DEBUG + ezlogInitWithTrace() + #else + ezlogInit() + #endif + + let dirPath = URL.documents.appendingPathComponent("ezlog").relativePath + + let config = EZLogConfig(level: Level.trace, + dirPath: dirPath, + name: "demo", + keepDays: 7, + maxSize: 150*1024, + compress: CompressKind.ZLIB, + compressLevel: CompressLevel.DEFAULT, + cipher: Cipher.AES128GCM, + cipherKey: [UInt8]("a secret key!!!!".utf8), + cipherNonce: [UInt8]("unique nonce".utf8)) + let logger = EZLogger(config: config) + + ezlogRegisterCallback(success: {name, date, logs in + if !logs.isEmpty { + for log in logs { + print("name:" + name + " date:" + date + " log:" + log); + } + } else { + print("no log found at that time") + } + + }, fail: {name, date, err in + print("name:" + name + " date:" + date + " err:" + err); + }) + + logger.debug("first blood") +} +``` +click run and see console ouput. +### Rust Usage + +#### Add ezlog + +Add this to your Cargo.toml + +```toml +[dependencies] +ezlog = "0.2" +``` + +#### Example + +```rust +use ezlog::EZLogConfigBuilder; +use ezlog::Level; +use log::{error, info, warn}; +use log::{LevelFilter, Log}; + +ezlog::InitBuilder::new().init(); + +let config = EZLogConfigBuilder::new() + .level(Level::Trace) + .dir_path( + dirs::download_dir() + .unwrap() + .into_os_string() + .into_string() + .expect("dir path error"), + ) + .build(); +ezlog::create_log(config); + +info!("hello ezlog"); + +``` + +see more examples in examples dir. +## Architecture + +### Code structure + +``` +├── android +│   ├── app # android demo app +│   └── lib-ezlog # ezlog android library +├── examples # Rust examples +├── ezlog_flutter # Flutter plugin +├── ezlog-cli # Rust command line tool +├── ezlog-core # Rust core library +├── ios +│   ├── EZLog # ezlog iOS library +│   ├── demo # iOS demo app +│   └── framework # ezlog XCFramework +``` + +### Log file format + +#### Header + +| Bytes Offset | Meaning | +|--------|------------------------------------------| +| 0-1 | 'ez' | +| 2 | Version number | +| 3 | Flag bits | +| 4-7 | Offset of recorder position in bytes | +| 8-15 | Unix timestamp (big-endian) | +| 16 | Compression type | +| 17 | Encryption type | +| 18-21 | Encryption key hash | + +#### Per log record + +| Byte Offset | Field Name| Description | +|----------|-----------|-----------------| +| 0| Start Byte| Always 0x3b indicating the start| +| 1-varint|Record Length| A variable-length integer that specifies the length| +| varint+1-varint+n | Record Content | The actual log record content | +| varint+n+1| End Byte| Always 0x21 indicating the start | + +### Compression + +We use zlib as the compression algorithm. + +### Encryption + +#### We use AES-GCM-SIV as the encryption algorithm. + +AES-GCM-SIV, as a symmetric encryption algorithm, is more efficient compared to asymmetric encryption. As an AEAD, When compared to AES-CFB, it is more secure, and when compared to AES-GCM, AES-GCM-SIV is nonce-misuse-resistant. + +### Make nonce not repeat + +First of all, we need an init nonce, which is generated randomly when the logger is created. Then, we get the timestamp of the log file creation. When we write a log record, we know the current index of the log file, and we can calculate the nonce of the current log record by the following formula: + +``` +nonce = init_nonce ^ timestamp.extend(index) + +``` +## Benchmark + +### Android Benchmark + +#### measure log method + +| Library | Time (ns) | Allocations | +|---------|-----------|-------------| +| logcat | 2,427 | 7 | +| logan | 4,726 | 14 | +| ezlog | 8,404 | 7 | +| xlog | 12,459 | 7 | + +#### startup time + +startup baseline +``` +min 206.4, median 218.5, max 251.9 +``` + +startup with ezlog time: +``` +min 206.8, median 216.6, max 276.6 +``` +## Build + +- install and config rust + +```shell +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +source $HOME/.cargo/env +``` + +- use rust nightly + +```shell +rustup default nightly-2022-08-10 +``` + +we use [build-std](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std) feature, so add nightly src component + +```shell +rustup component add rust-src --toolchain nightly-x86_64-apple-darwin +``` + +clone repository and open in command line tool. then run + +```shell +cargo check +``` + +wait crates download... + +```shell +cargo build -p ezlog +``` + +### for Flutter build + +```dart +flutter packages get + +flutter packages upgrade +``` + +### For android build + +- add android targets + +```shell +rustup target add aarch64-linux-android armv7-linux-androideabi i686-linux-android x86_64-linux-android +``` + +we use `cargo-ndk` to build dylib + +```shell +cargo install cargo-ndk +``` + +cd android + +```shell +sh b_android.sh +``` + +then open current workspace in AndroidStudio + +### For iOS build + +- add iOS targets + +```shell +rustup target add aarch64-apple-ios aarch64-apple-ios-sim x86_64-apple-ios +``` + + +install `cbindgen` + +```shell +cargo install --force cbindgen +``` + +cd ios dir -## License +```shell +sh b_ios.sh +``` -See [LICENSE-MIT](LICENSE-MIT), [LICENSE-APACHE](LICENSE-APACHE), \ No newline at end of file +open the `ios/EZlog.xcworkspace` in Xcode diff --git a/README.zh-CN.md b/README.zh-CN.md deleted file mode 100644 index e31f09f..0000000 --- a/README.zh-CN.md +++ /dev/null @@ -1,17 +0,0 @@ -# ezlog是一个高效的跨平台的日志库 -[ezlog](https://s1rius.github.io/ezlog/zh/index.html)灵感来自[Xlog](https://github.com/Tencent/mars)和[Loagan](https://github.com/Meituan-Dianping/Logan)，用Rust重写。 - -## 特性 -- 多平台支持 Flutter, iOS, Android, Windows, Linux, MacOS -- 使用[mmap](https://man7.org/linux/man-pages/man2/mmap.2.html)做日志映射 -- 支持压缩，如[zilb](https://en.wikipedia.org/wiki/Zlib) -- 支持加密，如[AEAD](https://en.wikipedia.org/wiki/Authenticated_encryption) -- 日志回捞 -- 日志清理 -- 命令行解析工具 - -## [使用指南](https://s1rius.github.io/ezlog/zh/index.html). - -## 协议 - -详见 [LICENSE-MIT](LICENSE-MIT), [LICENSE-APACHE](LICENSE-APACHE), \ No newline at end of file diff --git a/docs/book.toml b/docs/book.toml index f1da740..1946b0f 100644 --- a/docs/book.toml +++ b/docs/book.toml @@ -5,6 +5,9 @@ multilingual = false src = "src" title = "ezlog documentation" +# [preprocessor.serie] +# command = "cat ./src/introduction.md ./src/platform/*.md ./src/architecture.md ./src/benchmark.md ./src/build.md >> ./../README.md;" + [preprocessor.gettext] after = ["links"] diff --git a/docs/po/messages.pot b/docs/po/messages.pot index 05ac99c..4f2a561 100644 --- a/docs/po/messages.pot +++ b/docs/po/messages.pot @@ -53,28 +53,32 @@ msgid "# ezlog" msgstr "" #: src/introduction.md:3 -msgid "## What is ezlog?" +msgid "[中文介绍](https://s1rius.github.io/ezlog/zh/index.html)

" msgstr "" #: src/introduction.md:5 -msgid "ezlog is a high-performance cross-platform file logging library." +msgid "## What is ezlog?" msgstr "" #: src/introduction.md:7 -msgid "It can be used in Flutter, Android, iOS, Windows, Linux, MacOS." +msgid "ezlog is a high-performance cross-platform file logging library." msgstr "" #: src/introduction.md:9 +msgid "It can be used in Flutter, Android, iOS, Windows, Linux, MacOS." +msgstr "" + +#: src/introduction.md:11 msgid "" "It is inspired by [Xlog](https://github.com/Tencent/mars) and " "[Logan](https://github.com/Meituan-Dianping/Logan), rewrite in Rust." msgstr "" -#: src/introduction.md:11 -msgid "## Features" +#: src/introduction.md:13 +msgid "### Features" msgstr "" -#: src/introduction.md:12 +#: src/introduction.md:14 msgid "" "- multi platform: Flutter, Android, iOS, Windows, Linux, MacOS\n" "- map file into memory by " @@ -87,22 +91,21 @@ msgid "" "- command line parser support." msgstr "" -#: src/introduction.md:20 -msgid "## License" +#: src/introduction.md:22 +msgid "### License" msgstr "" -#: src/introduction.md:22 +#: src/introduction.md:24 msgid "" -"See [LICENSE-MIT](../../LICENSE-MIT), " -"[LICENSE-APACHE](../../LICENSE-APACHE), " +"See [LICENSE-MIT](../../LICENSE-MIT), [LICENSE-APACHE](../../LICENSE-APACHE)" msgstr "" #: src/platform/flutter.md:1 -msgid "# Flutter ezlog" +msgid "### Flutter Usage" msgstr "" #: src/platform/flutter.md:3 -msgid "### Add ezlog_flutter as a dependency in your pubspec.yaml file." +msgid "#### Add ezlog_flutter as a dependency in your pubspec.yaml file." msgstr "" #: src/platform/flutter.md:5 @@ -114,8 +117,8 @@ msgid "" msgstr "" #: src/platform/flutter.md:10 -#: src/platform/rust.md:13 -msgid "### Example" +#: src/platform/rust.md:12 +msgid "#### Example" msgstr "" #: src/platform/flutter.md:12 @@ -164,11 +167,11 @@ msgid "" msgstr "" #: src/platform/android.md:1 -msgid "# Android ezlog" +msgid "### Android Usage" msgstr "" #: src/platform/android.md:3 -msgid "### Add ezlog to dependencies" +msgid "#### Add ezlog to dependencies" msgstr "" #: src/platform/android.md:5 @@ -204,7 +207,7 @@ msgstr "" msgid "" "```groovy\n" "dependencies {\n" -" implementation \"wtf.s1.ezlog:ezlog:0.1.7\"\n" +" implementation \"wtf.s1.ezlog:ezlog:0.2+\"\n" "}\n" "```" msgstr "" @@ -214,7 +217,7 @@ msgid "Sync gradle" msgstr "" #: src/platform/android.md:35 -msgid "### Setup in application" +msgid "#### Setup in application" msgstr "" #: src/platform/android.md:37 @@ -262,11 +265,12 @@ msgid "" msgstr "" #: src/platform/ios.md:1 -msgid "# iOS ezlog" +msgid "### iOS Usage" msgstr "" #: src/platform/ios.md:3 -msgid "### Add ezlog" +#: src/platform/rust.md:3 +msgid "#### Add ezlog" msgstr "" #: src/platform/ios.md:5 @@ -292,7 +296,7 @@ msgid "" msgstr "" #: src/platform/ios.md:15 -msgid "### Open Xcode, add sample code" +msgid "#### Open Xcode, add sample code" msgstr "" #: src/platform/ios.md:17 @@ -349,11 +353,7 @@ msgid "click run and see console ouput." msgstr "" #: src/platform/rust.md:1 -msgid "# Rust ezlog" -msgstr "" - -#: src/platform/rust.md:3 -msgid "### Usage" +msgid "### Rust Usage" msgstr "" #: src/platform/rust.md:5 @@ -368,7 +368,7 @@ msgid "" "```" msgstr "" -#: src/platform/rust.md:15 +#: src/platform/rust.md:14 msgid "" "```rust\n" "use ezlog::EZLogConfigBuilder;\n" @@ -395,20 +395,20 @@ msgid "" "```" msgstr "" -#: src/platform/rust.md:39 +#: src/platform/rust.md:38 msgid "see more examples in examples dir." msgstr "" #: src/benchmark.md:1 -msgid "# Benchmark" +msgid "## Benchmark" msgstr "" #: src/benchmark.md:3 -msgid "## Android Benchmark" +msgid "### Android Benchmark" msgstr "" #: src/benchmark.md:5 -msgid "### measure log method" +msgid "#### measure log method" msgstr "" #: src/benchmark.md:7 @@ -422,7 +422,7 @@ msgid "" msgstr "" #: src/benchmark.md:14 -msgid "### startup time" +msgid "#### startup time" msgstr "" #: src/benchmark.md:16 @@ -448,11 +448,11 @@ msgid "" msgstr "" #: src/architecture.md:1 -msgid "# Architecture" +msgid "## Architecture" msgstr "" #: src/architecture.md:3 -msgid "## Code structure" +msgid "### Code structure" msgstr "" #: src/architecture.md:5 @@ -473,11 +473,11 @@ msgid "" msgstr "" #: src/architecture.md:19 -msgid "## Log file format" +msgid "### Log file format" msgstr "" #: src/architecture.md:21 -msgid "### Header " +msgid "#### Header " msgstr "" #: src/architecture.md:23 @@ -495,7 +495,7 @@ msgid "" msgstr "" #: src/architecture.md:34 -msgid "### Per log record" +msgid "#### Per log record" msgstr "" #: src/architecture.md:36 @@ -510,7 +510,7 @@ msgid "" msgstr "" #: src/architecture.md:43 -msgid "## Compression" +msgid "### Compression" msgstr "" #: src/architecture.md:45 @@ -518,11 +518,11 @@ msgid "We use zlib as the compression algorithm." msgstr "" #: src/architecture.md:47 -msgid "## Encryption" +msgid "### Encryption" msgstr "" #: src/architecture.md:49 -msgid "### We use AES-GCM-SIV as the encryption algorithm." +msgid "#### We use AES-GCM-SIV as the encryption algorithm." msgstr "" #: src/architecture.md:51 @@ -553,7 +553,7 @@ msgid "" msgstr "" #: src/build.md:1 -msgid "# Build" +msgid "## Build" msgstr "" #: src/build.md:3 @@ -616,7 +616,7 @@ msgid "" msgstr "" #: src/build.md:34 -msgid "## for Flutter build" +msgid "### for Flutter build" msgstr "" #: src/build.md:36 @@ -629,7 +629,7 @@ msgid "" msgstr "" #: src/build.md:42 -msgid "## For android build" +msgid "### For android build" msgstr "" #: src/build.md:44 @@ -671,7 +671,7 @@ msgid "then open current workspace in AndroidStudio" msgstr "" #: src/build.md:64 -msgid "## For iOS build" +msgid "### For iOS build" msgstr "" #: src/build.md:66 diff --git a/docs/po/zh.po b/docs/po/zh.po index 784bd65..e5acfaf 100644 --- a/docs/po/zh.po +++ b/docs/po/zh.po @@ -52,18 +52,22 @@ msgid "# ezlog" msgstr "" #: src/introduction.md:3 +msgid "[中文介绍](https://s1rius.github.io/ezlog/zh/index.html)

" +msgstr "" + +#: src/introduction.md:5 msgid "## What is ezlog?" msgstr "## 介绍" -#: src/introduction.md:5 +#: src/introduction.md:7 msgid "ezlog is a high-performance cross-platform file logging library." msgstr "ezlog是一个高性能的跨平台文件日志库。" -#: src/introduction.md:7 +#: src/introduction.md:9 msgid "It can be used in Flutter, Android, iOS, Windows, Linux, MacOS." msgstr "可以用在Flutter，android，iOS，Windows，Linux，MacOS。" -#: src/introduction.md:9 +#: src/introduction.md:11 msgid "" "It is inspired by [Xlog](https://github.com/Tencent/mars) and [Logan]" "(https://github.com/Meituan-Dianping/Logan), rewrite in Rust." @@ -71,11 +75,11 @@ msgstr "" "本项目参考了[Xlog](https://github.com/Tencent/mars)和[Logan](https://github." "com/Meituan-Dianping/Logan), 使用[Rust](https://www.rust-lang.org/)重写。" -#: src/introduction.md:11 -msgid "## Features" -msgstr "## 特性" +#: src/introduction.md:13 +msgid "### Features" +msgstr "### 特性" -#: src/introduction.md:12 +#: src/introduction.md:14 msgid "" "- multi platform: Flutter, Android, iOS, Windows, Linux, MacOS\n" "- map file into memory by [mmap](https://man7.org/linux/man-pages/man2/" @@ -96,23 +100,22 @@ msgstr "" "- 日志清理\n" "- 命令行解析工具\n" -#: src/introduction.md:20 -msgid "## License" +#: src/introduction.md:22 +msgid "### License" msgstr "" -#: src/introduction.md:22 +#: src/introduction.md:24 msgid "" -"See [LICENSE-MIT](../../LICENSE-MIT), [LICENSE-APACHE](../../LICENSE-" -"APACHE), " +"See [LICENSE-MIT](../../LICENSE-MIT), [LICENSE-APACHE](../../LICENSE-APACHE)" msgstr "" #: src/platform/flutter.md:1 -msgid "# Flutter ezlog" -msgstr "" +msgid "### Flutter Usage" +msgstr "### Flutter 用例" #: src/platform/flutter.md:3 -msgid "### Add ezlog_flutter as a dependency in your pubspec.yaml file." -msgstr "### 在pubspec.yaml中添加ezlog_flutter依赖" +msgid "#### Add ezlog_flutter as a dependency in your pubspec.yaml file." +msgstr "#### 在pubspec.yaml中添加ezlog_flutter依赖" #: src/platform/flutter.md:5 msgid "" @@ -122,9 +125,9 @@ msgid "" "```" msgstr "" -#: src/platform/flutter.md:10 src/platform/rust.md:13 -msgid "### Example" -msgstr "### 示例" +#: src/platform/flutter.md:10 src/platform/rust.md:12 +msgid "#### Example" +msgstr "#### 示例" #: src/platform/flutter.md:12 msgid "" @@ -172,12 +175,12 @@ msgid "" msgstr "" #: src/platform/android.md:1 -msgid "# Android ezlog" -msgstr "" +msgid "### Android Usage" +msgstr "### Android用例" #: src/platform/android.md:3 -msgid "### Add ezlog to dependencies" -msgstr "### 添加ezlog依赖" +msgid "#### Add ezlog to dependencies" +msgstr "#### 添加ezlog依赖" #: src/platform/android.md:5 msgid "Open top-level `build.gradle`, add `mavenCentral` to repositories." @@ -212,7 +215,7 @@ msgstr "在App层级的`build.gradle`添加ezlog依赖" msgid "" "```groovy\n" "dependencies {\n" -" implementation \"wtf.s1.ezlog:ezlog:0.1.7\"\n" +" implementation \"wtf.s1.ezlog:ezlog:0.2+\"\n" "}\n" "```" msgstr "" @@ -222,8 +225,8 @@ msgid "Sync gradle" msgstr "同步gradle" #: src/platform/android.md:35 -msgid "### Setup in application" -msgstr "### 在应用中初始化" +msgid "#### Setup in application" +msgstr "#### 在应用中初始化" #: src/platform/android.md:37 msgid "" @@ -270,12 +273,12 @@ msgid "" msgstr "" #: src/platform/ios.md:1 -msgid "# iOS ezlog" -msgstr "" +msgid "### iOS Usage" +msgstr "### iOS用例" -#: src/platform/ios.md:3 -msgid "### Add ezlog" -msgstr "### 添加ezlog依赖" +#: src/platform/ios.md:3 src/platform/rust.md:3 +msgid "#### Add ezlog" +msgstr "#### 添加ezlog依赖" #: src/platform/ios.md:5 msgid "Add dependency to Podfile" @@ -300,8 +303,8 @@ msgid "" msgstr "" #: src/platform/ios.md:15 -msgid "### Open Xcode, add sample code" -msgstr "### 打开Xcode，添加示例代码" +msgid "#### Open Xcode, add sample code" +msgstr "#### 打开Xcode，添加示例代码" #: src/platform/ios.md:17 msgid "" @@ -357,12 +360,8 @@ msgid "click run and see console ouput." msgstr "点击运行，查看控制台输出" #: src/platform/rust.md:1 -msgid "# Rust ezlog" -msgstr "# Rust ezlog" - -#: src/platform/rust.md:3 -msgid "### Usage" -msgstr "### 使用" +msgid "### Rust Usage" +msgstr "### Rust用例" #: src/platform/rust.md:5 msgid "Add this to your Cargo.toml" @@ -376,7 +375,7 @@ msgid "" "```" msgstr "" -#: src/platform/rust.md:15 +#: src/platform/rust.md:14 msgid "" "```rust\n" "use ezlog::EZLogConfigBuilder;\n" @@ -403,21 +402,21 @@ msgid "" "```" msgstr "" -#: src/platform/rust.md:39 +#: src/platform/rust.md:38 msgid "see more examples in examples dir." msgstr "在examples文件夹中查看更多示例" #: src/benchmark.md:1 -msgid "# Benchmark" -msgstr "# 性能" +msgid "## Benchmark" +msgstr "## 性能" #: src/benchmark.md:3 -msgid "## Android Benchmark" -msgstr "## Android平台性能测试" +msgid "### Android Benchmark" +msgstr "### Android平台性能测试" #: src/benchmark.md:5 -msgid "### measure log method" -msgstr "### 单条日志格式" +msgid "#### measure log method" +msgstr "#### 单条日志格式" #: src/benchmark.md:7 msgid "" @@ -436,8 +435,8 @@ msgstr "" "| xlog | 12,459 | 7 |" #: src/benchmark.md:14 -msgid "### startup time" -msgstr "### 启动时间" +msgid "#### startup time" +msgstr "#### 启动时间" #: src/benchmark.md:16 msgid "startup baseline" @@ -468,12 +467,12 @@ msgstr "" "```" #: src/architecture.md:1 -msgid "# Architecture" -msgstr "# 架构设计" +msgid "## Architecture" +msgstr "## 架构设计" #: src/architecture.md:3 -msgid "## Code structure" -msgstr "## 代码结构" +msgid "### Code structure" +msgstr "### 代码结构" #: src/architecture.md:5 msgid "" @@ -493,12 +492,12 @@ msgid "" msgstr "" #: src/architecture.md:19 -msgid "## Log file format" -msgstr "## 日志文件格式" +msgid "### Log file format" +msgstr "### 日志文件格式" #: src/architecture.md:21 -msgid "### Header " -msgstr "### 文件头" +msgid "#### Header " +msgstr "#### 文件头" #: src/architecture.md:23 msgid "" @@ -525,8 +524,8 @@ msgstr "" "| 18-21 | 密钥哈希 |" #: src/architecture.md:34 -msgid "### Per log record" -msgstr "### 单条日志格式" +msgid "#### Per log record" +msgstr "#### 单条日志格式" #: src/architecture.md:36 msgid "" @@ -546,20 +545,20 @@ msgstr "" "| 可变下标+日志长度+1 | 结束标记 | 0x21|\n" #: src/architecture.md:43 -msgid "## Compression" -msgstr "## 压缩算法" +msgid "### Compression" +msgstr "### 压缩算法" #: src/architecture.md:45 msgid "We use zlib as the compression algorithm." msgstr "我们使用zlib作为默认压缩算法" #: src/architecture.md:47 -msgid "## Encryption" -msgstr "## 加密算法" +msgid "### Encryption" +msgstr "### 加密算法" #: src/architecture.md:49 -msgid "### We use AES-GCM-SIV as the encryption algorithm." -msgstr "### 我们使用AES-GCM-SIV作为默认加密算法" +msgid "#### We use AES-GCM-SIV as the encryption algorithm." +msgstr "#### 我们使用AES-GCM-SIV作为默认加密算法" #: src/architecture.md:51 msgid "" @@ -595,8 +594,8 @@ msgid "" msgstr "" #: src/build.md:1 -msgid "# Build" -msgstr "# 本地构建" +msgid "## Build" +msgstr "## 本地构建" #: src/build.md:3 msgid "- install and config rust" @@ -659,8 +658,8 @@ msgid "" msgstr "" #: src/build.md:34 -msgid "## for Flutter build" -msgstr "## Flutter 构建" +msgid "### for Flutter build" +msgstr "### Flutter 构建" #: src/build.md:36 msgid "" @@ -672,8 +671,8 @@ msgid "" msgstr "" #: src/build.md:42 -msgid "## For android build" -msgstr "## Android 构建" +msgid "### For android build" +msgstr "### Android 构建" #: src/build.md:44 msgid "- add android targets" @@ -714,8 +713,8 @@ msgid "then open current workspace in AndroidStudio" msgstr "然后在 AndroidStudio 中打开当前工作区" #: src/build.md:64 -msgid "## For iOS build" -msgstr "## iOS 构建" +msgid "### For iOS build" +msgstr "### iOS 构建" #: src/build.md:66 msgid "- add iOS targets" diff --git a/docs/src/architecture.md b/docs/src/architecture.md index 60b27a2..d01d69d 100644 --- a/docs/src/architecture.md +++ b/docs/src/architecture.md @@ -1,6 +1,6 @@ -# Architecture +## Architecture -## Code structure +### Code structure ``` ├── android @@ -16,9 +16,9 @@ │   └── framework # ezlog XCFramework ``` -## Log file format +### Log file format -### Header +#### Header | Bytes Offset | Meaning | |--------|------------------------------------------| @@ -31,7 +31,7 @@ | 17 | Encryption type | | 18-21 | Encryption key hash | -### Per log record +#### Per log record | Byte Offset | Field Name| Description | |----------|-----------|-----------------| @@ -40,13 +40,13 @@ | varint+1-varint+n | Record Content | The actual log record content | | varint+n+1| End Byte| Always 0x21 indicating the start | -## Compression +### Compression We use zlib as the compression algorithm. -## Encryption +### Encryption -### We use AES-GCM-SIV as the encryption algorithm. +#### We use AES-GCM-SIV as the encryption algorithm. AES-GCM-SIV, as a symmetric encryption algorithm, is more efficient compared to asymmetric encryption. As an AEAD, When compared to AES-CFB, it is more secure, and when compared to AES-GCM, AES-GCM-SIV is nonce-misuse-resistant. @@ -58,5 +58,3 @@ First of all, we need an init nonce, which is generated randomly when the logger nonce = init_nonce ^ timestamp.extend(index) ``` - - diff --git a/docs/src/benchmark.md b/docs/src/benchmark.md index 2c1660f..daecd5f 100644 --- a/docs/src/benchmark.md +++ b/docs/src/benchmark.md @@ -1,8 +1,8 @@ -# Benchmark +## Benchmark -## Android Benchmark +### Android Benchmark -### measure log method +#### measure log method | Library | Time (ns) | Allocations | |---------|-----------|-------------| @@ -11,7 +11,7 @@ | ezlog | 8,404 | 7 | | xlog | 12,459 | 7 | -### startup time +#### startup time startup baseline ``` @@ -21,4 +21,4 @@ min 206.4, median 218.5, max 251.9 startup with ezlog time: ``` min 206.8, median 216.6, max 276.6 -``` \ No newline at end of file +``` diff --git a/docs/src/build.md b/docs/src/build.md index cc2aed9..7dd72b0 100644 --- a/docs/src/build.md +++ b/docs/src/build.md @@ -1,4 +1,4 @@ -# Build +## Build - install and config rust @@ -31,7 +31,7 @@ wait crates download... cargo build -p ezlog ``` -## for Flutter build +### for Flutter build ```dart flutter packages get @@ -39,7 +39,7 @@ flutter packages get flutter packages upgrade ``` -## For android build +### For android build - add android targets @@ -61,7 +61,7 @@ sh b_android.sh then open current workspace in AndroidStudio -## For iOS build +### For iOS build - add iOS targets @@ -82,4 +82,4 @@ cd ios dir sh b_ios.sh ``` -open the `ios/EZlog.xcworkspace` in Xcode \ No newline at end of file +open the `ios/EZlog.xcworkspace` in Xcode diff --git a/docs/src/introduction.md b/docs/src/introduction.md index c567d44..9cd3508 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1,5 +1,7 @@ # ezlog +[中文介绍](https://s1rius.github.io/ezlog/zh/index.html)

+ ## What is ezlog? ezlog is a high-performance cross-platform file logging library. @@ -8,7 +10,7 @@ It can be used in Flutter, Android, iOS, Windows, Linux, MacOS. It is inspired by [Xlog](https://github.com/Tencent/mars) and [Logan](https://github.com/Meituan-Dianping/Logan), rewrite in Rust. -## Features +### Features - multi platform: Flutter, Android, iOS, Windows, Linux, MacOS - map file into memory by [mmap](https://man7.org/linux/man-pages/man2/mmap.2.html). - compression support, eg: [zlib](https://en.wikipedia.org/wiki/Zlib). @@ -17,6 +19,6 @@ It is inspired by [Xlog](https://github.com/Tencent/mars) and [Logan](https://gi - trim out of date files. - command line parser support. -## License +### License -See [LICENSE-MIT](../../LICENSE-MIT), [LICENSE-APACHE](../../LICENSE-APACHE), \ No newline at end of file +See [LICENSE-MIT](../../LICENSE-MIT), [LICENSE-APACHE](../../LICENSE-APACHE) diff --git a/docs/src/platform/android.md b/docs/src/platform/android.md index fe4a550..ca34e65 100644 --- a/docs/src/platform/android.md +++ b/docs/src/platform/android.md @@ -1,6 +1,6 @@ -# Android ezlog +### Android Usage -### Add ezlog to dependencies +#### Add ezlog to dependencies Open top-level `build.gradle`, add `mavenCentral` to repositories. @@ -32,7 +32,7 @@ dependencies { Sync gradle -### Setup in application +#### Setup in application ```kotlin override fun onCreate() { @@ -71,4 +71,4 @@ override fun onCreate() { }) } -``` \ No newline at end of file +``` diff --git a/docs/src/platform/flutter.md b/docs/src/platform/flutter.md index 1fb645f..debce8f 100644 --- a/docs/src/platform/flutter.md +++ b/docs/src/platform/flutter.md @@ -1,13 +1,13 @@ -# Flutter ezlog +### Flutter Usage -### Add ezlog_flutter as a dependency in your pubspec.yaml file. +#### Add ezlog_flutter as a dependency in your pubspec.yaml file. ```yaml dependencies: ezlog_flutter: ^0.2.0 ``` -### Example +#### Example ```dart import 'dart:io'; @@ -48,4 +48,4 @@ class _MyAppState extends State { var logs = await EZLog.requestLogFilesForDate("main", "2022_08_25"); } } -``` \ No newline at end of file +``` diff --git a/docs/src/platform/ios.md b/docs/src/platform/ios.md index 61ff72e..87761bb 100644 --- a/docs/src/platform/ios.md +++ b/docs/src/platform/ios.md @@ -1,6 +1,6 @@ -# iOS ezlog +### iOS Usage -### Add ezlog +#### Add ezlog Add dependency to Podfile @@ -12,7 +12,7 @@ then ```shell pod update ``` -### Open Xcode, add sample code +#### Open Xcode, add sample code ```swift import EZLog @@ -55,4 +55,4 @@ init() { logger.debug("first blood") } ``` -click run and see console ouput. \ No newline at end of file +click run and see console ouput. diff --git a/docs/src/platform/rust.md b/docs/src/platform/rust.md index eb0256f..5d63988 100644 --- a/docs/src/platform/rust.md +++ b/docs/src/platform/rust.md @@ -1,6 +1,6 @@ -# Rust ezlog +### Rust Usage -### Usage +#### Add ezlog Add this to your Cargo.toml @@ -9,8 +9,7 @@ Add this to your Cargo.toml ezlog = "0.2" ``` - -### Example +#### Example ```rust use ezlog::EZLogConfigBuilder; @@ -36,4 +35,4 @@ info!("hello ezlog"); ``` -see more examples in examples dir. \ No newline at end of file +see more examples in examples dir.