请 star 此 GitHub 仓库以保持最新。

TraceLog

  

简介

TraceLog 是一个高度可配置、灵活、便携且易于使用的调试日志系统，适用于在 Linux、macOS、iOS、watchOS 和 tvOS 运行的 Swift 和 Objective-C 应用程序。

TraceLog 设计哲学

1. 通用：使用 TraceLog，您不必局限于某一类型的日志系统，实际上，您可以选择使用多种日志写入器的组合，将其写入各种端点和系统。
2. 灵活：使用 TraceLog，您可以在运行时或编译时动态地过滤消息。选择适合您特定用例的任何组合的 写入器 和过滤器。为特定的用例编写自己的自定义 写入器 以连接到 TraceLog。
3. 便携：截至写作时，TraceLog 是少数几个设计用于在所有 Swift 支持的平台（Linux、macOS、iOS、tvOS 和 watchOS）上运行，并用于多种语言的日志系统之一（Swift 和 Objective-C）。
4. 轻量级：TraceLog 的占用空间小且高效。它旨在尽可能高效地使用资源，并在需要时进行优化。
5. 易于使用：TraceLog 可以直接使用，无需任何设置或特殊依赖项。这一点设计在内，并且我们已经努力保持这一特点多年。您可以实际上将它链接到应用程序中并为任何平台添加 log 语句，从而获得有用的输出。

功能

• 快速简便地开始使用。
• 完整可配置。
• 消息过滤。
• 日志级别（错误、警告、信息、跟踪1、跟踪2、跟踪3、跟踪4）。
• 支持自定义 标签，以便对消息进行分组和过滤。
• 通过 OS 环境在运行时或内联编译到应用程序中的代码中动态配置级别。
• 可安装的日志写入器（一次安装多个写入器）
• 为任何用例创建自定义日志写入器。
• 预定义的日志写入器，用于将日志写入各种端点。
  • 内置（OutputStreamWriter）
    • Stdout（ConsoleWriter） - 一个简单的标准输出（stdout）写入器，用于将日志记录到控制台或终端。
    • 文件（FileWriter） - 一个文件写入器，将日志输出写入本地磁盘上的文件，并根据需要管理文件的轮换和存档。
  • 外部
    • 苹果统一日志记录（AdaptiveWriter） - 在苹果平台上，AdaptiveWriter将写入统一日志系统（见https://github.com/tonystone/tracelog-adaptive-writer）。
    • Linux systemd日志（AdaptiveWriter） - 在Linux平台上，AdaptiveWriter将记录到systemd日志（见https://github.com/tonystone/tracelog-adaptive-writer）。
• 用于按所需格式格式化日志条目的输出格式化程序。
  • TextFormat - 一个可定制的、可与人机交互的文本格式化程序，可用于任何OutputStreamWriter。
  • JSONFormat - 一个可定制的JSON字符串格式化程序，可用于任何OutputStreamWriter。
• 为任何使用场景创建自定义输出格式化程序。
• 在写入程序不可用时缓冲输出的输出缓冲模式（例如，在iOS上，当受保护的数据不可用）。
• 为写入Writers提供多种并发模式。可以全局设置或为每个安装的Writer设置。
  • direct - 实时日志。
  • sync - 阻塞队列日志。
  • async - 背景线程日志。
• 多语言：支持Swift和Objective-C。
• 可移植性：Linux、macOS、iOS、tvOS、WatchOS。

文档

• 用户指南与参考 - 具有广泛的用户指南和参考文档！100%的API文档，完整示例和许多隐藏的细节。

快速入门指南

TraceLog开箱即用，极其简单。尽管TraceLog高度可配置，但要开始使用，你只需将pod添加到项目中，将TraceLog导入到需要记录日志的文件中，并在需要的位置开始添加日志语句。TraceLog会自动初始化并完成其他所有工作。

将TraceLog添加到项目中

在Podfile中添加TraceLog。

    target 'MyApp'

    pod "TraceLog", '~>5.0'

如果您有混合Swift和Objective-C的代码，必须指定subspect以启用Objective-C，如下所示

    target 'MyApp'

    pod "TraceLog", '~>5.0'
    pod "TraceLog/ObjC", '~>5.0'

导入TraceLog并开始记录

将TraceLog导入您的文件中并开始记录。

    import TraceLog

    struct MyStruct {

        func doSomething() {

            logInfo { "A simple TraceLog Test message" }
        }
    }

日志功能

TraceLog具有以下主要日志功能，用于记录不同级别的信息。这些输出的控制可以通过运行时环境变量或通过在应用启动时通过TraceLog.configure()函数进行程序化控制。

    logError  (tag: String?, message: @escaping () -> String)
    logWarning(tag: String?, message: @escaping () -> String)
    logInfo   (tag: String?, message: @escaping () -> String)
    logTrace  (tag: String?, level: UInt, message: @escaping () -> String)
    logTrace  (level: UInt, @escaping message: () -> String)

注意：为了简单起见，省略了隐藏参数和默认值。

基本配置

虽然不是强制性的，但建议在启动时调用TraceLog.configure()命令以允许TraceLog读取配置信息。

尽量在启动代码中尽早调用configure无参数，最好在调用任何日志语句之前。

    TraceLog.configure()

有关用户指南、完全文档化的API参考和许多其他示例的完整文档集合，请参见https://tonystone.io/tracelog。

运行时开销

Swift实现是为了利用Swift编译器优化，当与优化标识-O和TRACELOG_DISABLED定义一起编译时，将不会有任何开销。

Objective-C实现是为了利用预处理器，当与TRACELOG_DISABLED定义一起编译时，在应用中不会产生任何开销。

对于XCode，你可以在项目目标中设置TRACELOG_DISABLED。对于Swift Package Manager，你可以将swiftc指令传递给swift build，如下例所示。

swift build -Xswiftc -DTRACELOG_DISABLED

最低要求

构建环境

最低运行版本

注意

要在Linux上构建和运行，我们提供了一个预先配置的Vagrant文件，位置在https://github.com/tonystone/vagrant-swift

请参阅README以获取说明。

安装（Swift 包管理器）

TraceLog 现已支持在所有苹果操作系统变体以及 Linux 上通过 Swift 包管理器进行依赖项管理。

有关更多信息，请参阅 Swift 包管理器。

安装（CocoaPods）

TraceLog 通过 CocoaPods 提供。有关使用 CocoaPods 安装的快速入门指南，请参阅 快速入门指南。

有关 CocoaPods 的更多信息，请参阅“使用 CocoaPods”指南。

作者

Tony Stone (https://github.com/tonystone)

许可

TraceLog 根据 Apache 许可证，版本 2.0 发布。