swift log
Swift Log 1.6.1
Hal pertama yang pertama: Ini adalah awal dari proyek sumber terbuka berbasis komunitas yang secara aktif mencari kontribusi, baik itu kode, dokumentasi, atau ide. Selain berkontribusi pada SwiftLog itu sendiri, ada kesenjangan besar lainnya saat ini: SwiftLog adalah paket API yang mencoba membuat API umum yang dapat digunakan oleh ekosistem. Agar logging benar-benar berfungsi untuk beban kerja dunia nyata, kita memerlukan backend logging yang kompatibel dengan SwiftLog yang kemudian menyimpan pesan log dalam file, merendernya dalam warna yang lebih bagus di terminal, atau mengirimkannya ke Splunk atau ELK.
Apa yang disediakan SwiftLog saat ini dapat ditemukan di dokumen API.
Jika Anda memiliki aplikasi Swift sisi server, atau mungkin aplikasi/pustaka lintas platform (misalnya Linux & MacOS), dan Anda ingin mencatat, menurut kami menargetkan paket API logging ini adalah ide yang bagus. Di bawah ini Anda akan menemukan semua yang perlu Anda ketahui untuk memulai.
SwiftLog dirancang untuk Swift 5.8 dan yang lebih baru. Untuk bergantung pada paket API logging, Anda perlu mendeklarasikan ketergantungan Anda pada Package.swift :
. package ( url : " https://github.com/apple/swift-log.git " , from : " 1.0.0 " ) , dan ke target aplikasi/perpustakaan Anda, tambahkan "Logging" ke dependencies Anda, misalnya seperti ini:
. 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 Default SwiftLog menyediakan log out konsol yang sangat mendasar secara langsung melalui StreamLogHandler . Dimungkinkan untuk mengganti output default ke stderr seperti:
LoggingSystem . bootstrap ( StreamLogHandler . standardError ) StreamLogHandler pada dasarnya hanya untuk kenyamanan dan tidak memberikan penyesuaian substansial apa pun. Pengelola perpustakaan yang ingin membangun backend logging mereka sendiri untuk integrasi dan konsumsi harus mengimplementasikan protokol LogHandler secara langsung seperti yang dijelaskan di bagian "Tentang penerapan backend logging".
Untuk informasi lebih lanjut, silakan periksa dokumentasi API.
Anda dapat memilih salah satu backend berikut untuk menggunakan log Anda. Jika Anda tertarik untuk menerapkannya, lihat bagian "Pertimbangan penerapan" di bawah yang menjelaskan cara melakukannya. Daftar pustaka yang kompatibel dengan SwiftLog API:
| Gudang | Deskripsi Pengendali |
|---|---|
| Kitura/HeliumLogger | backend logging yang banyak digunakan di ekosistem Kitura |
| ianpartridge/swift-log- syslog | backend syslog |
| Adorkable/swift-log- format-dan-pipa | backend yang memungkinkan penyesuaian format keluaran dan tujuan yang dihasilkan |
| chrisaljoudi/swift-log- oslog | backend OSLog Unified Logging untuk digunakan pada platform Apple. Catatan Penting: kami merekomendasikan penggunaan os_log secara langsung seperti yang dijelaskan di sini. Menggunakan os_log melalui swift-log menggunakan backend ini akan kurang efisien dan juga akan menghalangi penentuan privasi pesan. Backend selalu menggunakan %{public}@ sebagai format string dan dengan penuh semangat mengubah semua interpolasi string menjadi string. Hal ini mempunyai dua kelemahan: 1. komponen statis dari interpolasi string akan dengan mudah disalin oleh sistem logging terpadu, yang akan mengakibatkan hilangnya kinerja. 2. Ini membuat semua pesan menjadi publik, yang mengubah kebijakan privasi default os_log, dan tidak mengizinkan penentuan privasi terperinci pada bagian-bagian pesan. Dalam pekerjaan terpisah yang sedang berjalan, API Swift untuk os_log sedang ditingkatkan dan dibuat agar selaras dengan API swift-log. Referensi: Menyatukan Tingkat Logging, Membuat os_log menerima interpolasi string menggunakan interpretasi waktu kompilasi. |
| Pembiayaan Otak/StackdriverLogging | backend logging JSON terstruktur untuk digunakan di Google Cloud Platform dengan agen logging Stackdriver |
| DnV1eX/GoogleCloudLogging | perpustakaan sisi klien untuk mencatat peristiwa aplikasi di Google Cloud melalui REST API v2. |
| kit uap/konsol | logger ke terminal saat ini atau stdout dengan keluaran bergaya (ANSI). Logger default untuk semua aplikasi Vapor |
| neallester/swift-log-testing | menyediakan akses ke pesan log untuk digunakan dalam pernyataan (dalam target pengujian) |
| wlisac/swift-log-slack | backend logging yang mengirimkan pesan log penting ke Slack |
| Tindakan NSHipster/swift-log-github | backend logging yang menerjemahkan pesan logging menjadi perintah alur kerja untuk GitHub Actions. |
| stevapple/swift-log-telegram | backend logging yang mengirimkan pesan log ke obrolan Telegram mana pun (Terinspirasi oleh dan bercabang dari wlisac/swift-log-slack) |
| jagreenwood/swift-log-datadog | backend logging yang mengirimkan pesan log ke layanan manajemen log Datadog |
| google/SwiftLogFireCloud | backend logging untuk logging deret waktu yang mendorong log sebagai file datar ke Firebase Cloud Storage. |
| crspybits/swift-log-file | pencatat file lokal sederhana (menggunakan Foundation FileManager ) |
| sushichop/Anak Anjing | backend logging yang mendukung banyak transportasi (konsol, file, syslog, dll.) dan memiliki fitur dengan pemformatan dan rotasi log file |
| ShivaHuang/swift-log-SwiftyBeaver | backend logging untuk mencetak logging berwarna ke konsol/file Xcode, atau mengirim logging terenkripsi ke platform SwiftyBeaver. |
| Apodini/swift-log-elk | backend logging yang memformat, menyimpan cache, dan mengirimkan data log ke elastis/logstash |
| pengikisan biner/swift-log-supabase | backend logging yang mengirimkan entri log ke Supabase. |
| kiliankoe/swift-log-matrix | backend logging untuk mengirim log langsung ke ruang Matrix |
| PerselisihanBM/DiscordLogger | implementasi logging Discord untuk mengirim log Anda ke saluran Discord dengan cara yang bagus dan dengan banyak opsi konfigurasi termasuk kemampuan untuk mengirim hanya beberapa level log penting seperti warning / error / critical . |
| KakaoLumberjack | kerangka logging yang cepat & sederhana, namun kuat & fleksibel untuk macOS, iOS, tvOS, dan watchOS, yang mencakup backend logging untuk swift-log. |
| rwbutler/swift-log-ecs | backend logging untuk login dalam format Log ECS. Kompatibel dengan Vapor dan memungkinkan rangkaian beberapa LogHandlers. |
| Buku Kapal/swift-log- buku kapal | backend logging yang mengirimkan entri log ke Shipbook - Shipbook memberi Anda kemampuan untuk mengumpulkan, mencari, dan menganalisis log pengguna dan pengecualian Anda dari jarak jauh di cloud, berdasarkan per pengguna & sesi. |
| Perpustakaan Anda? | Hubungi kami! |
Senang Anda bertanya. Kami percaya bahwa untuk ekosistem Swift di Server, sangat penting untuk memiliki API logging yang dapat diadopsi oleh siapa saja sehingga banyak perpustakaan dari berbagai pihak dapat login ke tujuan bersama. Lebih konkretnya, ini berarti kami yakin semua pesan log dari semua perpustakaan berakhir di file, database, instance Elastic Stack/Splunk, atau apa pun yang Anda pilih.
Namun di dunia nyata, ada banyak pendapat mengenai bagaimana seharusnya sistem logging berperilaku, seperti apa format pesan log, dan di mana/bagaimana pesan tersebut harus disimpan. Menurut kami, tidak mungkin menunggu satu paket logging mendukung segala sesuatu yang dibutuhkan penerapan tertentu, namun tetap cukup mudah digunakan dan tetap berkinerja baik. Itu sebabnya kami memutuskan untuk membagi masalahnya menjadi dua:
Paket ini hanya menyediakan API logging itu sendiri dan oleh karena itu SwiftLog adalah 'paket API logging'. SwiftLog (menggunakan LoggingSystem.bootstrap ) dapat dikonfigurasi untuk memilih implementasi backend logging yang kompatibel. Dengan cara ini paket dapat mengadopsi API dan aplikasi dapat memilih implementasi backend logging yang kompatibel tanpa memerlukan perubahan apa pun dari perpustakaan mana pun.
Demi kelengkapan: Paket API ini sebenarnya menyertakan implementasi backend logging yang terlalu sederhana dan tidak dapat dikonfigurasi yang hanya menulis semua pesan log ke stdout . Alasan untuk menyertakan implementasi backend logging yang terlalu sederhana ini adalah untuk meningkatkan pengalaman penggunaan pertama kali. Misalkan Anda memulai sebuah proyek dan mencoba SwiftLog untuk pertama kalinya, jauh lebih baik melihat sesuatu yang Anda login muncul di stdout dalam format sederhana daripada tidak terjadi apa-apa sama sekali. Untuk aplikasi dunia nyata apa pun, kami menyarankan untuk mengonfigurasi implementasi backend logging lain yang mencatat gaya yang Anda suka.
Logger digunakan untuk mengeluarkan pesan log dan oleh karena itu merupakan tipe yang paling penting dalam SwiftLog , jadi penggunaannya harus sesederhana mungkin. Umumnya, mereka digunakan untuk mengeluarkan pesan log pada tingkat log tertentu. Misalnya:
// logging an informational message
logger . info ( " Hello World! " )
// ouch, something went wrong
logger . error ( " Houston, we have a problem: ( problem ) " )Level log berikut ini didukung:
tracedebuginfonoticewarningerrorcritical Level log dari logger tertentu dapat diubah, namun perubahan tersebut hanya akan memengaruhi logger tertentu yang Anda gunakan untuk mengubahnya. Bisa dibilang Logger adalah tipe nilai mengenai level log.
Metadata logging adalah metadata yang dapat dilampirkan ke logger untuk menambahkan informasi yang penting saat men-debug suatu masalah. Di server, contoh umum adalah melampirkan permintaan UUID ke logger yang kemudian akan ada di semua pesan log yang dicatat dengan logger tersebut. Contoh:
var logger = logger
logger [ metadataKey : " request-uuid " ] = " ( UUID ( ) ) "
logger . info ( " hello world " )akan mencetak
2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED hello world
dengan implementasi backend logging default yang dikirimkan bersama SwiftLog . Tentu saja, formatnya sepenuhnya ditentukan oleh backend logging yang Anda pilih.
LogHandler )Catatan: Jika Anda tidak ingin menerapkan backend logging khusus, semua yang ada di bagian ini mungkin tidak terlalu relevan, jadi silakan lewati.
Untuk menjadi backend logging yang kompatibel dan dapat digunakan oleh semua konsumen SwiftLog , Anda perlu melakukan dua hal: 1) Menerapkan tipe (biasanya struct ) yang mengimplementasikan LogHandler , sebuah protokol yang disediakan oleh SwiftLog dan 2) menginstruksikan SwiftLog untuk menggunakan implementasi backend logging Anda .
Implementasi LogHandler atau logging backend adalah segala sesuatu yang sesuai dengan protokol berikut
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 }
} Menginstruksikan SwiftLog untuk menggunakan backend logging Anda sebagai backend yang harus digunakan oleh seluruh aplikasi (termasuk semua perpustakaan) sangatlah sederhana:
LoggingSystem . bootstrap ( MyLogHandler . init ) LogHandler mengontrol sebagian besar sistem logging:
LogHandler LogHandler mengontrol dua bagian penting dari konfigurasi Logger , yaitu:
logger.logLevel )logger[metadataKey:] dan logger.metadata ) Namun, agar sistem dapat berfungsi, LogHandler harus memperlakukan konfigurasi sebagai tipe nilai . Ini berarti bahwa LogHandler s harus struct s dan perubahan dalam level log atau metadata logging hanya akan mempengaruhi LogHandler tempat ia diubah.
Namun, dalam kasus khusus, LogHandler dapat memberikan beberapa penggantian tingkat log global yang dapat memengaruhi semua LogHandler yang dibuat.
LogHandler s LogHandler tidak mengontrol apakah suatu pesan harus dicatat atau tidak. Logger hanya akan memanggil fungsi log dari LogHandler jika Logger menentukan bahwa pesan log harus dikeluarkan berdasarkan tingkat log yang dikonfigurasi.
Logger membawa label (yang tidak dapat diubah) dan setiap pesan log membawa parameter source (sejak SwiftLog 1.3.0). Label Logger mengidentifikasi pencipta Logger . Jika Anda menggunakan logging terstruktur dengan mempertahankan metadata di beberapa modul, label Logger bukanlah cara yang baik untuk mengidentifikasi dari mana pesan log berasal karena label tersebut mengidentifikasi pembuat Logger yang sering diedarkan antar perpustakaan untuk menjaga metadata dan sejenisnya.
Jika Anda ingin memfilter semua pesan log yang berasal dari subsistem tertentu, filter berdasarkan source yang defaultnya adalah modul yang mengeluarkan pesan log.
Silakan lihat SECURITY.md untuk proses keamanan SwiftLog.
API logging ini dirancang bersama kontributor komunitas Swift on Server dan disetujui oleh SSWG (Swift Server Work Group) hingga 'tingkat kotak pasir' dari proses inkubasi SSWG.
