swift log
Swift Log 1.6.1
Tout d'abord : c'est le début d'un projet open source mené par la communauté et recherchant activement des contributions, qu'il s'agisse de code, de documentation ou d'idées. En plus de contribuer à SwiftLog lui-même, il existe actuellement une autre lacune énorme : SwiftLog est un package API qui tente d'établir une API commune que l'écosystème peut utiliser. Pour que la journalisation fonctionne réellement pour les charges de travail du monde réel, nous avons besoin de backends de journalisation compatibles SwiftLog qui conservent ensuite les messages de journal dans des fichiers, les restituent dans des couleurs plus agréables sur le terminal ou les envoient à Splunk ou ELK.
Ce que SwiftLog propose aujourd'hui peut être trouvé dans la documentation de l'API.
Si vous disposez d'une application Swift côté serveur, ou peut-être d'une application/bibliothèque multiplateforme (par exemple Linux et macOS), et que vous souhaitez vous connecter, nous pensons que cibler ce package d'API de journalisation est une excellente idée. Vous trouverez ci-dessous tout ce que vous devez savoir pour commencer.
SwiftLog est conçu pour Swift 5.8 et versions ultérieures. Pour dépendre du package API de journalisation, vous devez déclarer votre dépendance dans votre Package.swift :
. package ( url : " https://github.com/apple/swift-log.git " , from : " 1.0.0 " ) , et à votre cible application/bibliothèque, ajoutez "Logging" à vos dependencies , par exemple comme ceci :
. 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 par défaut SwiftLog fournit une journalisation de console très basique prête à l'emploi via StreamLogHandler . Il est possible de basculer la sortie par défaut sur stderr comme ceci :
LoggingSystem . bootstrap ( StreamLogHandler . standardError ) StreamLogHandler est avant tout une commodité uniquement et ne fournit aucune personnalisation substantielle. Les responsables de bibliothèque qui souhaitent créer leurs propres backends de journalisation pour l'intégration et la consommation doivent implémenter le protocole LogHandler directement, comme indiqué dans la section « Sur la mise en œuvre d'un backend de journalisation ».
Pour plus d’informations, veuillez consulter la documentation de l’API.
Vous pouvez choisir parmi l'un des backends suivants pour consommer vos journaux. Si vous souhaitez en mettre en œuvre un, consultez la section « Considérations sur la mise en œuvre » ci-dessous expliquant comment procéder. Liste des bibliothèques compatibles avec l'API SwiftLog existantes :
| Dépôt | Description du gestionnaire |
|---|---|
| Kitura/HéliumLogger | un backend de journalisation largement utilisé dans l'écosystème Kitura |
| ianpartridge/swift-log- syslog | un back-end syslog |
| Adorkable/swift-log- format-and-pipe | un backend qui permet de personnaliser le format de sortie et la destination résultante |
| chrisaljoudi/swift-log- oslog | un backend OSLog Unified Logging à utiliser sur les plates-formes Apple. Remarque importante : nous vous recommandons d'utiliser os_log directement comme décrit ici. Utiliser os_log via Swift-log en utilisant ce backend sera moins efficace et empêchera également de spécifier la confidentialité du message. Le backend utilise toujours %{public}@ comme chaîne de format et convertit avec empressement toutes les interpolations de chaînes en chaînes. Cela présente deux inconvénients : 1. les composants statiques de l'interpolation de chaîne seraient copiés avec impatience par le système de journalisation unifié, ce qui entraînerait une perte de performances. 2. Il rend tous les messages publics, ce qui modifie la politique de confidentialité par défaut d'os_log et ne permet pas de spécifier une confidentialité précise des sections du message. Dans le cadre d'un travail distinct en cours, les API Swift pour os_log sont améliorées et conçues pour s'aligner étroitement sur les API Swift-log. Références : Unifier les niveaux de journalisation, Faire en sorte que os_log accepte les interpolations de chaînes à l'aide de l'interprétation au moment de la compilation. |
| Brainfinance/StackdriverLogging | un backend de journalisation JSON structuré à utiliser sur Google Cloud Platform avec l'agent de journalisation Stackdriver |
| DnV1eX/GoogleCloudLogging | une bibliothèque côté client pour enregistrer les événements d'application dans Google Cloud via l'API REST v2. |
| kit vapeur/console | un enregistreur vers le terminal actuel ou la sortie standard avec une sortie stylisée (ANSI). L'enregistreur par défaut pour toutes les applications Vapor |
| neallester/swift-log-test | fournit un accès aux messages de journal à utiliser dans les assertions (dans les cibles de test) |
| wlisac/swift-log-slack | un backend de journalisation qui envoie des messages de journal critiques à Slack |
| NSHipster/swift-log-github-actions | un backend de journalisation qui traduit les messages de journalisation en commandes de workflow pour les actions GitHub. |
| stevapple/swift-log-télégramme | un backend de journalisation qui envoie des messages de journal à n'importe quel chat Telegram (inspiré et dérivé de wlisac/swift-log-slack) |
| jagreenwood/swift-log-datadog | un backend de journalisation qui envoie des messages de journal au service de gestion des journaux Datadog |
| google/SwiftLogFireCloud | un backend de journalisation pour la journalisation de séries chronologiques qui transmet les journaux sous forme de fichiers plats vers Firebase Cloud Storage. |
| crspybits/fichier-log-swift | un simple enregistreur de fichiers local (utilisant Foundation FileManager ) |
| sushichop/Chiot | un backend de journalisation qui prend en charge plusieurs transports (console, fichier, syslog, etc.) et dispose de la fonctionnalité de formatage et de rotation des journaux de fichiers |
| ShivaHuang/swift-log-SwiftyBeaver | un backend de journalisation pour imprimer la journalisation en couleur sur la console/fichier Xcode, ou pour envoyer la journalisation cryptée à la plateforme SwiftyBeaver. |
| Apodini/rapide-log-elk | un backend de journalisation qui formate, met en cache et envoie les données de journal à elastic/logstash |
| grattage binaire/swift-log-supabase | un backend de journalisation qui envoie des entrées de journal à Supabase. |
| kiliankoe/swift-log-matrix | un backend de journalisation pour envoyer des journaux directement à une salle Matrix |
| DiscordBM/DiscordLogger | une implémentation de journalisation Discord pour envoyer vos journaux à un canal Discord de manière élégante et avec de nombreuses options de configuration, y compris la possibilité d'envoyer uniquement quelques niveaux de journal importants tels que warning / error / critical . |
| CacaoBûcheron | un cadre de journalisation rapide, simple, mais puissant et flexible pour macOS, iOS, tvOS et watchOS, qui comprend un backend de journalisation pour Swift-Log. |
| rwbutler/swift-log-ecs | un backend de journalisation pour la journalisation au format ECS Log. Compatible avec Vapor et permet le chaînage de plusieurs LogHandlers. |
| ShipBook/swift-log -shipbook | un backend de journalisation qui envoie des entrées de journal à Shipbook - Shipbook vous donne le pouvoir de collecter, rechercher et analyser à distance vos journaux d'utilisateurs et exceptions dans le cloud, par utilisateur et par session. |
| Votre bibliothèque ? | Entrer en contact! |
Heureux que vous ayez demandé. Nous pensons que pour l'écosystème Swift on Server, il est crucial de disposer d'une API de journalisation qui puisse être adoptée par n'importe qui afin qu'une multitude de bibliothèques de différentes parties puissent toutes se connecter à une destination partagée. Plus concrètement, cela signifie que nous pensons que tous les messages de journal de toutes les bibliothèques se retrouvent dans le même fichier, base de données, instance Elastic Stack/Splunk ou tout ce que vous choisissez.
Cependant, dans le monde réel, il existe de nombreuses opinions sur la manière exacte dont un système de journalisation doit se comporter, sur le format d'un message de journal et sur où et comment il doit être conservé. Nous pensons qu'il n'est pas possible d'attendre qu'un seul package de journalisation prenne en charge tout ce dont un déploiement spécifique a besoin tout en restant suffisamment simple à utiliser et performant. C'est pourquoi nous avons décidé de réduire le problème de moitié :
Ce package fournit uniquement l'API de journalisation elle-même et SwiftLog est donc un « package API de journalisation ». SwiftLog (à l'aide de LoggingSystem.bootstrap ) peut être configuré pour choisir n'importe quelle implémentation de backend de journalisation compatible. De cette façon, les packages peuvent adopter l'API et l' application peut choisir n'importe quelle implémentation de backend de journalisation compatible sans nécessiter de modification de l'une des bibliothèques.
Juste par souci d'exhaustivité : ce package API inclut en fait une implémentation de backend de journalisation trop simpliste et non configurable qui écrit simplement tous les messages de journal sur stdout . La raison d’inclure cette implémentation trop simpliste du backend de journalisation est d’améliorer l’expérience de première utilisation. Supposons que vous démarriez un projet et essayiez SwiftLog pour la première fois, c'est bien mieux de voir quelque chose que vous avez enregistré apparaître sur stdout dans un format simpliste plutôt que rien ne se passe du tout. Pour toute application réelle, nous vous conseillons de configurer une autre implémentation du backend de journalisation qui enregistre dans le style que vous souhaitez.
Les Logger sont utilisés pour émettre des messages de journal et constituent donc le type le plus important dans SwiftLog , leur utilisation doit donc être aussi simple que possible. Le plus souvent, ils sont utilisés pour émettre des messages de journalisation à un certain niveau de journalisation. Par exemple:
// logging an informational message
logger . info ( " Hello World! " )
// ouch, something went wrong
logger . error ( " Houston, we have a problem: ( problem ) " )Les niveaux de journalisation suivants sont pris en charge :
tracedebuginfonoticewarningerrorcritical Le niveau de journalisation d'un enregistreur donné peut être modifié, mais la modification n'affectera que l'enregistreur spécifique sur lequel vous l'avez modifié. On pourrait dire que Logger est un type de valeur concernant le niveau de journalisation.
Les métadonnées de journalisation sont des métadonnées qui peuvent être attachées aux enregistreurs pour ajouter des informations cruciales lors du débogage d'un problème. Sur les serveurs, l'exemple habituel consiste à attacher un UUID de requête à un enregistreur qui sera ensuite présent sur tous les messages de journal enregistrés avec cet enregistreur. Exemple:
var logger = logger
logger [ metadataKey : " request-uuid " ] = " ( UUID ( ) ) "
logger . info ( " hello world " )imprimera
2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED hello world
avec l'implémentation du backend de journalisation par défaut fournie avec SwiftLog . Inutile de dire que le format est entièrement défini par le backend de journalisation que vous choisissez.
LogHandler )Remarque : Si vous ne souhaitez pas implémenter un backend de journalisation personnalisé, tout ce qui se trouve dans cette section n'est probablement pas très pertinent, alors n'hésitez pas à l'ignorer.
Pour devenir un backend de journalisation compatible que tous les consommateurs SwiftLog peuvent utiliser, vous devez faire deux choses : 1) Implémenter un type (généralement un struct ) qui implémente LogHandler , un protocole fourni par SwiftLog et 2) demander à SwiftLog d'utiliser votre implémentation de backend de journalisation. .
Une implémentation LogHandler ou de backend de journalisation est tout ce qui est conforme au protocole suivant
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 }
} Demander à SwiftLog d'utiliser votre backend de journalisation comme celui que l'ensemble de l'application (y compris toutes les bibliothèques) devrait utiliser est très simple :
LoggingSystem . bootstrap ( MyLogHandler . init ) LogHandler contrôlent la plupart des parties du système de journalisation :
LogHandler LogHandler contrôlent les deux éléments cruciaux de la configuration Logger , à savoir :
logger.logLevel )logger[metadataKey:] et logger.metadata ) Toutefois, pour que le système fonctionne, il est important que LogHandler traite la configuration comme des types de valeur . Cela signifie que les LogHandler doivent être struct et qu'une modification du niveau de journalisation ou des métadonnées de journalisation ne doit affecter que le LogHandler sur lequel il a été modifié.
Cependant, dans des cas particuliers, il est acceptable qu'un LogHandler fournisse un remplacement global du niveau de journalisation qui peut affecter tous LogHandler créés.
LogHandler s Les LogHandler ne contrôlent pas si un message doit être enregistré ou non. Logger n'invoquera la fonction log d'un LogHandler que si Logger détermine qu'un message de journal doit être émis compte tenu du niveau de journalisation configuré.
Un Logger porte une label (immuable) et chaque message de journal porte un paramètre source (depuis SwiftLog 1.3.0). L'étiquette du Logger identifie le créateur du Logger . Si vous utilisez la journalisation structurée en préservant les métadonnées sur plusieurs modules, l' label du Logger n'est pas un bon moyen d'identifier l'origine d'un message de journal car elle identifie le créateur d'un Logger qui est souvent transmis entre les bibliothèques pour préserver les métadonnées et le genre.
Si vous souhaitez filtrer tous les messages de journal provenant d'un certain sous-système, filtrez par source qui est par défaut le module qui émet le message de journal.
Veuillez consulter SECURITY.md pour le processus de sécurité de SwiftLog.
Cette API de journalisation a été conçue avec les contributeurs de la communauté Swift on Server et approuvée par le SSWG (Swift Server Work Group) au « niveau sandbox » du processus d'incubation du SSWG.
