GoogleCloudLogging

适用于 Apple 平台客户端应用程序的事件日志记录，支持离线工作并自动上传到 Google Cloud (GCP)。该软件包依赖于 SwiftLog - 一个官方的 Swift 日志 API，因此可以轻松地集成到项目中并与其他日志后端结合使用。日志事件以 JSON Lines 文件格式本地存储，并在时间间隔、指定事件或显式请求时批量上传到使用 Cloud Logging API v2 上传到 GCP。

是的，它会记录自身！（带有递归保护）🤘

原理

Google 推荐的客户端应用程序日志记录解决方案是 Analytics 框架，它现在是 Firebase SDK 的一部分。以下是他们的框架和此库在日志记录方面的比较：

库	FirebaseAnalytics	GoogleCloudLogging
平台	仅限移动设备。甚至目前不支持 Catalyst。	所有现代 Apple 的操作系统。这对于开发通用 SwiftUI 应用程序至关重要。
源代码	闭源。所有应用程序和用户数据都可供 Google 使用。	开源。几百行纯 Swift 代码，没有隐式数据提交。
依赖	Firebase SDK 的一部分。带来了一堆带有运行时方法调配的 Objective-C/C++ 代码等。	仅依赖 SwiftLog 和 Apple 的嵌入式框架。
分发	CocoaPods/Carthage。由于闭源和依赖关系，目前不支持 SwiftPM。	SwiftPM，这是首选的，因为它与 Swift 构建系统集成。
后端	Google Analytics for Firebase。包括一些预定义的营销工具。	GCP Operations（以前称为 Stackdriver）。灵活的自定义日志视图、指标、通知、导出等。
集成	需要在 Google 中注册您的应用程序。	只需要生成一个访问密钥。
日志记录	专有日志记录功能和隐式使用情况跟踪。	SwiftLog 日志记录 API。单行连接日志记录后端。

入门

添加软件包依赖项

在 Xcode 11 或更高版本中打开您的应用程序项目，转到菜单 File -> Swift Packages -> Add Package Dependency... 并粘贴软件包存储库 URL https://github.com/DnV1eX/GoogleCloudLogging.git。

创建服务帐户

在您的 Web 浏览器中，打开 Google Cloud Console 并创建一个新项目。在 IAM & Admin -> Service Accounts 中创建一个服务帐户，选择 Logging -> Logs Writer 角色。在最后一步中，创建并下载私钥，选择 JSON 格式。您需要将此文件包含在您的应用程序包中。

只需将文件拖到 Xcode 项目中，并在文件检查器中勾选所需的 target。

设置日志记录

导入 SwiftLog 和 GoogleCloudLogging 模块

import Logging
import GoogleCloudLogging

在应用程序启动后注册一次日志记录后端

LoggingSystem.bootstrap(GoogleCloudLogHandler.init)

或者，您可以注册多个后端，例如，为了将日志发送到 GCP 和 Xcode 控制台

LoggingSystem.bootstrap { MultiplexLogHandler([GoogleCloudLogHandler(label: $0), StreamLogHandler.standardOutput(label: $0)]) }

配置 GoogleCloudLogHandler

do {
    try GoogleCloudLogHandler.setup(serviceAccountCredentials: Bundle.main.url(forResource: /* GCP private key file name */, withExtension: "json")!, clientId: UIDevice.current.identifierForVendor)
} catch {
    // Log GoogleCloudLogHandler setup error
}

如果 UIKit 不可用，您可以使用 UUID() 生成随机 clientId 并在应用程序启动之间存储它。

您可以自定义 GoogleCloudLogHandler 的静态变量，这些变量都是线程安全的，并且记录在源代码中。

建议在隐藏或退出应用程序时显式上传日志，调用 GoogleCloudLogHandler.upload()。

如何使用

发出日志

将 SwiftLog 模块导入到所需的文件中

import Logging

创建 logger，它可以是类型、实例或全局常量或变量

static let logger = Logger(label: /* Logged class name */)

您可以自定义最小发出的日志级别并设置 logger 元数据。

以特定日志级别发出日志消息

logger.info(/* Logged info message */)
logger.error(/* Logged error message */, metadata: [LogKey.error: "\(error)"])

最佳实践是定义 typealias LogKey = GoogleCloudLogHandler.MetadataKey 并使用您自定义的键扩展它，而不是使用字符串文字。

GoogleCloudLogHandler.globalMetadata 优先于 Logger 元数据，而 Logger 元数据又优先于日志消息元数据，以防键重叠。

分析日志

在您的 Web 浏览器中，打开 GCP Operations Logging 并选择您的项目。您将看到给定时间范围的日志列表，可以按日志名称（logger 标签）、严重性（日志级别）、文本有效负载（消息）、标签（元数据）等进行过滤。 GoogleCloudLogHandler 生成的日志的资源类型始终为全局。

您可以切换到新的 Logs Viewer Preview，它引入了新功能，例如高级日志查询和直方图。

单击所需日志条目的 clientId 标签值，然后选择“Show matching entries”以便仅查看来自同一应用程序实例的日志。

支持的平台

iOS 11+
iPadOS 13+
macOS 10.13+
tvOS 11+
watchOS 4+