swift log
Swift Log 1.6.1
まず最初に: これは、コード、ドキュメント、アイデアなど、積極的に貢献を求めるコミュニティ主導のオープンソース プロジェクトの始まりです。 SwiftLog自体への貢献とは別に、現時点では別の大きなギャップがあります。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 " ) ,そして、アプリケーション/ライブラリターゲットに、 dependenciesに"Logging"を追加します。たとえば次のようになります。
. 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- syslog | syslog バックエンド |
| Adorkable/swift-log- format-and-pipe | 出力形式と結果の宛先をカスタマイズできるバックエンド |
| chrisaljoudi/swift-log- oslog | Apple プラットフォームで使用するための OSLog Unified Logging バックエンド。重要な注意事項:ここで説明されているように、os_log を直接使用することをお勧めします。このバックエンドを使用して swift-log を通じて os_log を使用すると、効率が低下し、メッセージのプライバシーを指定できなくなります。バックエンドは常に%{public}@フォーマット文字列として使用し、すべての文字列補間を文字列に積極的に変換します。これには 2 つの欠点があります。 1. 文字列補間の静的コンポーネントが統合ログ システムによって熱心にコピーされるため、パフォーマンスが低下します。 2. すべてのメッセージが公開されるため、os_log のデフォルトのプライバシー ポリシーが変更され、メッセージのセクションの詳細なプライバシーを指定できなくなります。別の進行中の作業では、os_log 用の Swift API が改善され、swift-log API と緊密に連携するように作られています。参考資料: ログ レベルの統一、コンパイル時の解釈を使用して os_log が文字列補間を受け入れるようにする。 |
| Brainfinance/StackdriverLogging | Google Cloud Platform で Stackdriver ロギング エージェントとともに使用する構造化 JSON ロギング バックエンド |
| DnV1eX/GoogleCloudLogging | REST API v2 経由で Google Cloud でアプリケーション イベントをログに記録するためのクライアント側ライブラリ。 |
| 蒸気/コンソールキット | 現在の端末または定型化された (ANSI) 出力を持つ標準出力へのロガー。すべての Vapor アプリケーションのデフォルトのロガー |
| neallester/swift-log-testing | アサーション (テスト ターゲット内) で使用するログ メッセージへのアクセスを提供します。 |
| wlisac/swift-log-slack | 重要なログ メッセージを Slack に送信するログ バックエンド |
| NSHipster/swift-log-github-actions | ロギング メッセージを GitHub Actions のワークフロー コマンドに変換するロギング バックエンド。 |
| スティーブアップル/swift-log-telegram | Telegram チャットにログ メッセージを送信するログ バックエンド (wlisac/swift-log-slack からインスピレーションを受け、そこからフォークされたもの) |
| jagreenwood/swift-log-datadog | ログ メッセージを Datadog ログ管理サービスに送信するログ バックエンド |
| google/SwiftLogFireCloud | ログをフラット ファイルとして Firebase Cloud Storage にプッシュする時系列ロギング用のロギング バックエンド。 |
| crspybits/swift-log-file | 単純なローカル ファイル ロガー ( Foundation FileManagerを使用) |
| 寿司チョップ/子犬 | 複数のトランスポート (コンソール、ファイル、syslog など) をサポートし、フォーマットとファイル ログ ローテーションの機能を備えたロギング バックエンド |
| ShivaHuang/swift-log-SwiftyBeaver | Xcode コンソール/ファイルに色付きのログを出力したり、暗号化されたログを SwiftyBeaver プラットフォームに送信したりするためのログ バックエンド。 |
| アポディニ/swift-log-elk | ログ データをフォーマット、キャッシュし、elastic/logstash に送信するロギング バックエンド |
| バイナリスクレイピング/swift-log-supabase | ログ エントリを Supabase に送信するログ バックエンド。 |
| キリアンコエ/swift-log-matrix | ログをマトリックス ルームに直接送信するためのログ バックエンド |
| 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 インスタンス、または任意の場所に保存されると考えられることを意味します。
しかし、現実の世界では、ログ システムが正確にどのように動作するべきか、ログ メッセージはどのようにフォーマットされるべきか、どこにどのように永続化されるべきかについて、非常に多くの意見があります。私たちは、1 つのロギング パッケージが使いやすくパフォーマンスを維持しながら、特定のデプロイメントに必要なすべてをサポートするのを待つのは現実的ではないと考えています。だからこそ、私たちは問題を半分に減らすことにしました。
このパッケージはロギング 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 をロガーに添付し、そのロガーで記録されるすべてのログ メッセージにその 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コンシューマが使用できる互換性のあるロギング バックエンドになるには、次の 2 つのことを行う必要があります: 1) SwiftLogによって提供されるプロトコルであるLogHandlerを実装する型 (通常は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構成の 2 つの重要な部分、つまり次の部分を制御します。
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 Server Work Group) によって SSWG のインキュベーション プロセスの「サンドボックス レベル」まで承認されました。
