swift log
Swift Log 1.6.1
首先，這是一個社群驅動的開源專案的開始，該專案積極尋求貢獻，無論是程式碼、文件還是想法。除了對SwiftLog本身做出貢獻之外，目前還有另一個巨大的差距： SwiftLog是一個API 包，它試圖建立一個生態系統可以使用的通用 API。為了使日誌記錄真正適用於現實世界的工作負載，我們需要與SwiftLog相容的日誌記錄後端，然後將日誌訊息保留在檔案中，在終端上以更好的顏色呈現它們，或者將它們發送到Splunk或ELK。
SwiftLog今天提供的內容可以在 API 文件中找到。
如果您有一個伺服器端 Swift 應用程序，或者可能是一個跨平台（例如 Linux 和 macOS）應用程式/庫，並且您想要記錄日誌，我們認為針對此日誌記錄 API 套件是一個好主意。您將在下面找到入門所需的所有資訊。
SwiftLog是為 Swift 5.8 及更高版本設計的。若要依賴日誌記錄 API 包，您需要在Package.swift中聲明您的依賴項：
. package ( url : " https://github.com/apple/swift-log.git " , from : " 1.0.0 " ) ,並在您的應用程式/庫目標中，將"Logging"添加到您的dependencies中，例如如下所示：
. target ( name : " BestExampleApp " , dependencies : [
. product ( name : " Logging " , package : " swift-log " )
] , // 1) let's import the logging API package
import Logging
// 2) we need to create a logger, the label works similarly to a DispatchQueue label
let logger = Logger ( label : " com.example.BestExampleApp.main " )
// 3) we're now ready to use it
logger . info ( " Hello World! " ) 2019-03-13T15:46:38+0000 info: Hello World!
Logger行為SwiftLog透過StreamLogHandler提供非常基本的開箱即用的控制台日誌。可以將預設輸出切換到stderr如下所示：
LoggingSystem . bootstrap ( StreamLogHandler . standardError ) StreamLogHandler主要只是為了方便，不提供任何實質的客製化。旨在建立自己的日誌記錄後端以進行整合和使用的庫維護者應該直接實作LogHandler協議，如「日誌記錄後端的實作」部分所述。
如需了解更多信息，請查看 API 文件。
您可以選擇以下後端之一來使用您的日誌。如果您有興趣實施，請參閱下面的「實施注意事項」部分，以解釋如何實施。現有 SwiftLog API 相容庫列表：
| 儲存庫 | 處理程序描述 |
|---|---|
| Kitura/氦記錄器 | Kitura 生態系中廣泛使用的記錄後端 |
| ianpartridge/swift-log-系統日誌 | 系統日誌後端 |
| Adorkable/swift-log-格式與管道 | 允許自訂輸出格式和結果目的地的後端 |
| chrisaljoudi/swift-log- oslog | 用於 Apple 平台的 OSLog 統一日誌記錄後端。重要提示：我們建議直接使用 os_log，如此處所述。使用此終端透過 swift-log 使用 os_log 效率會較低，並且還會阻止指定訊息的隱私。後端始終使用%{public}@作為格式字串，並急切地將所有字串插值轉換為字串。這有兩個缺點： 1.字串插值的靜態元件會被統一日誌系統急切地複製，這將導致效能損失。 2.它使所有訊息公開，這改變了os_log的預設隱私策略，並且不允許指定訊息部分的細粒度隱私。在一項正在進行的單獨工作中，正在改進 os_log 的 Swift API，使其與 swift-log API 緊密結合。參考文獻：統一日誌記錄級別，使 os_log 使用編譯時解釋接受字串插值。 |
| Brainfinance/StackdriverLogging | 結構化 JSON 日誌記錄後端，可透過 Stackdriver 日誌代理程式在 Google Cloud Platform 上使用 |
| DnV1eX/GoogleCloudLogging | 一個客戶端庫，用於透過 REST API v2 記錄 Google Cloud 中的應用程式事件。 |
| 蒸氣/控制台套件 | 當前終端或標準輸出的記錄器，具有風格化 (ANSI) 輸出。所有 Vapor 應用程式的預設記錄器 |
| 尼爾斯特/swift-log-測試 | 提供對日誌訊息的存取權以在斷言中使用（在測試目標內） |
| wlisac/swift-log-slack | 向 Slack 發送關鍵日誌訊息的日誌記錄後端 |
| NSHipster/swift-log-github-actions | 將日誌記錄訊息轉換為 GitHub Actions 的工作流程命令的日誌記錄後端。 |
| stevapple/swift-log-電報 | 將日誌訊息傳送到任何 Telegram 聊天的日誌記錄後端（受 wlisac/swift-log-slack 啟發並派生） |
| jagreenwood/swift-log-datadog | 將日誌訊息傳送到 Datadog 日誌管理服務的日誌記錄後端 |
| Google/SwiftLogFireCloud | 用於時間序列日誌記錄的日誌記錄後端，它將日誌作為平面檔案推送到 Firebase Cloud Storage。 |
| crspybits/swift-日誌文件 | 一個簡單的本機檔案記錄器（使用Foundation FileManager ） |
| 壽司排/小狗 | 支援多種傳輸（控制台、文件、系統日誌等）並具有格式化和文件日誌輪換功能的日誌記錄後端 |
| ShivaHuang/swift-log-SwiftyBeaver | 日誌記錄後端，用於將彩色日誌記錄列印到 Xcode 控制台/文件，或將加密日誌記錄傳送至 SwiftyBeaver 平台。 |
| Apodini/斯威夫特-日誌-麋鹿 | 日誌記錄後端，用於格式化、快取日誌資料並將其發送到 elastic/logstash |
| 二進位抓取/swift-log-supabase | 將日誌條目傳送到 Supabase 的日誌記錄後端。 |
| kiliankoe/swift-log-矩陣 | 用於將日誌直接傳送到 Matrix room 的日誌記錄後端 |
| DiscordBM/DiscordLogger | 一個 Discord 日誌記錄實現，以美觀的方式將日誌發送到 Discord 通道，並具有許多配置選項，包括僅發送一些重要日誌等級的能力，例如warning / error / critical 。 |
| 可可伐木工 | 一個適用於 macOS、iOS、tvOS 和 watchOS 的快速、簡單、強大且靈活的日誌記錄框架，其中包括 swift-log 的日誌記錄後端。 |
| rwbutler/swift-log-ecs | 用於以 ECS 日誌格式進行日誌記錄的日誌記錄後端。與 Vapor 相容並允許連結多個 LogHandler。 |
| ShipBook/swift-log -shipbook | 將日誌條目傳送到 Shipbook 的日誌記錄後端 - Shipbook 可讓您基於每個使用者和會話遠端收集、搜尋和分析雲端中的使用者日誌和異常情況。 |
| 你的圖書館？ | 聯絡我們！ |
很高興你問了。我們相信，對於 Swift on Server 生態系統來說，擁有任何人都可以採用的日誌 API 至關重要，這樣來自不同方的眾多程式庫都可以登入共享目的地。更具體地說，這意味著我們相信來自所有庫的所有日誌訊息最終都會儲存在同一個檔案、資料庫、Elastic Stack/Splunk 實例或您可能選擇的任何內容中。
然而，在現實世界中，對於日誌系統應該如何運作、日誌訊息應該採用什麼樣的格式以及應該在哪裡/如何持久保存有很多意見。我們認為等待一個日誌記錄包來支援特定部署所需的一切，同時仍然足夠容易使用並保持效能是不可行的。這就是為什麼我們決定將問題減半：
該套件僅提供日誌記錄 API 本身，因此SwiftLog是一個「日誌記錄 API 套件」。 SwiftLog （使用LoggingSystem.bootstrap ）可以設定為選擇任何相容的日誌記錄後端實作。這樣，套件就可以採用 API，並且應用程式可以選擇任何相容的日誌記錄後端實現，而不需要對任何程式庫進行任何更改。
只是為了完整性：這個 API 套件實際上包含一個過於簡單且不可配置的日誌後端實現，它只是將所有日誌訊息寫入stdout 。包含這種過於簡單的日誌記錄後端實作的原因是為了改善首次使用體驗。假設您啟動專案並第一次嘗試SwiftLog ，看到您記錄的內容以簡單的格式出現在stdout上比什麼也沒發生要好得多。對於任何實際應用程序，我們建議配置另一個日誌記錄後端實現，以您喜歡的方式進行日誌記錄。
Logger用於發出日誌訊息，因此是SwiftLog中最重要的類型，因此它們的使用應該盡可能簡單。最常見的是，它們用於發出特定日誌等級的日誌訊息。例如：
// logging an informational message
logger . info ( " Hello World! " )
// ouch, something went wrong
logger . error ( " Houston, we have a problem: ( problem ) " )支援以下日誌等級：
tracedebuginfonoticewarningerrorcritical可以更改給定記錄器的日誌級別，但更改只會影響您更改它的特定記錄器。你可以說Logger是一個關於日誌等級的值類型。
記錄元資料是可以附加到記錄器以添加偵錯問題時至關重要的資訊的元資料。在伺服器中，通常的範例是將請求 UUID 附加到記錄器，然後該記錄器將出現在使用該記錄器記錄的所有日誌訊息中。例子：
var logger = logger
logger [ metadataKey : " request-uuid " ] = " ( UUID ( ) ) "
logger . info ( " hello world " )將列印
2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED hello world
使用SwiftLog附帶的預設日誌記錄後端實作。不用說，格式完全由您選擇的日誌記錄後端定義。
LogHandler ）的實現注意：如果您不想實現自訂日誌記錄後端，本節中的所有內容可能不太相關，因此請隨意跳過。
要成為所有SwiftLog消費者都可以使用的相容日誌記錄後端，您需要做兩件事：1) 實作一個實作LogHandler （ SwiftLog提供的協定）的類型（通常是struct ），2) 指示SwiftLog使用您的日誌記錄後端實作。
LogHandler或日誌記錄後端實作是符合下列協定的任何內容
public protocol LogHandler {
func log ( level : Logger . Level , message : Logger . Message , metadata : Logger . Metadata ? , source : String , file : String , function : String , line : UInt )
subscript ( metadataKey _ : String ) -> Logger . Metadata . Value ? { get set }
var metadata : Logger . Metadata { get set }
var logLevel : Logger . Level { get set }
}指示SwiftLog使用您的日誌記錄後端作為整個應用程式（包括所有庫）應該使用的後端非常簡單：
LoggingSystem . bootstrap ( MyLogHandler . init )LogHandler控制日誌系統的大部分部分：
LogHandler的控制下LogHandler控制Logger配置的兩個關鍵部分，即：
logger.logLevel屬性）logger[metadataKey:]和logger.metadata ）然而，為了使系統正常運作， LogHandler將配置視為值類型非常重要。這意味著LogHandler應該是struct ，並且日誌等級或日誌記錄元資料的變更應該只會影響它所更改的LogHandler 。
但是，在特殊情況下， LogHandler提供一些可能影響創建的所有LogHandler全域日誌層級覆蓋是可以接受的。
LogHandler的控制LogHandler不控制是否應記錄訊息。只有當Logger確定應在給定配置的日誌等級的情況下發出日誌訊息時， Logger才會呼叫LogHandler的log函數。
Logger帶有（不可變的） label ，每個日誌訊息都帶有source參數（自 SwiftLog 1.3.0 起）。 Logger的標籤標識了Logger的創建者。如果您透過跨多個模組保留元資料來使用結構化日誌記錄，則Logger的label不是識別日誌訊息來源的好方法，因為它標識了Logger的建立者，該建立者通常在庫之間傳遞以保留元數據和之類的。
如果您想要過濾源自某個子系統的所有日誌訊息，請按source進行過濾，預設為發出日誌訊息的模組。
SwiftLog 的安全流程請參閱 SECURITY.md。
此日誌記錄 API 是與 Swift on Server 社群的貢獻者共同設計的，並經 SSWG（Swift 伺服器工作小組）批准進入 SSWG 孵化過程的「沙箱等級」。
