swift log
Swift Log 1.6.1
Comecemos pelo princípio: este é o início de um projeto de código aberto conduzido pela comunidade que busca ativamente contribuições, seja código, documentação ou ideias. Além de contribuir para o próprio SwiftLog , há outra grande lacuna no momento: SwiftLog é um pacote de API que tenta estabelecer uma API comum que o ecossistema possa usar. Para fazer com que o registro realmente funcione para cargas de trabalho do mundo real, precisamos de back-ends de registro compatíveis com SwiftLog que persistam as mensagens de registro em arquivos, as renderizem em cores mais agradáveis no terminal ou as enviem para o Splunk ou ELK.
O que SwiftLog oferece hoje pode ser encontrado na documentação da API.
Se você tiver um aplicativo Swift do lado do servidor, ou talvez um aplicativo/biblioteca de plataforma cruzada (por exemplo, Linux e macOS) e gostaria de registrar, achamos que direcionar este pacote de API de registro é uma ótima ideia. Abaixo você encontrará tudo o que precisa saber para começar.
SwiftLog foi projetado para Swift 5.8 e posterior. Para depender do pacote da API de log, você precisa declarar sua dependência em seu Package.swift :
. package ( url : " https://github.com/apple/swift-log.git " , from : " 1.0.0 " ) , e ao destino do seu aplicativo/biblioteca, adicione "Logging" às suas dependencies , por exemplo, assim:
. 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 fornece registro de console muito básico pronto para uso por meio de StreamLogHandler . É possível mudar a saída padrão para stderr assim:
LoggingSystem . bootstrap ( StreamLogHandler . standardError ) StreamLogHandler é principalmente uma conveniência e não fornece nenhuma personalização substancial. Os mantenedores de bibliotecas que pretendem construir seus próprios back-ends de log para integração e consumo devem implementar o protocolo LogHandler diretamente, conforme descrito na seção "Sobre a implementação de um back-end de log".
Para mais informações, consulte a documentação da API.
Você pode escolher um dos seguintes back-ends para consumir seus logs. Se você estiver interessado em implementar um, consulte a seção "Considerações sobre implementação" abaixo, explicando como fazê-lo. Lista de bibliotecas existentes compatíveis com a API SwiftLog:
| Repositório | Descrição do manipulador |
|---|---|
| Kitura/HeliumLogger | um back-end de registro amplamente utilizado no ecossistema Kitura |
| ianpartridge/swift-log- syslog | um back-end de syslog |
| Adorkable/swift-log- formato-e-pipe | um backend que permite a personalização do formato de saída e do destino resultante |
| chrisaljoudi/swift-log -oslog | um backend OSLog Unified Logging para uso em plataformas Apple. Nota importante: recomendamos usar os_log diretamente conforme descrito aqui. Usar os_log por meio do swift-log usando esse back-end será menos eficiente e também impedirá a especificação da privacidade da mensagem. O back-end sempre usa %{public}@ como string de formato e converte avidamente todas as interpolações de string em strings. Isto tem duas desvantagens: 1. os componentes estáticos da interpolação de string seriam copiados avidamente pelo sistema de registro unificado, o que resultaria em perda de desempenho. 2. Torna todas as mensagens públicas, o que altera a política de privacidade padrão do os_log, e não permite especificar privacidade refinada de seções da mensagem. Em um trabalho separado em andamento, as APIs Swift para os_log estão sendo aprimoradas e alinhadas com as APIs Swift-log. Referências: Unificando níveis de log, fazendo com que os_log aceite interpolações de strings usando interpretação em tempo de compilação. |
| Brainfinance/StackdriverLogging | um back-end de geração de registros JSON estruturado para uso no Google Cloud Platform com o agente do Stackdriver Logging |
| DnV1eX/GoogleCloudLogging | uma biblioteca do lado do cliente para registrar eventos de aplicativos no Google Cloud por meio da API REST v2. |
| vapor/kit de console | um registrador para o terminal atual ou stdout com saída estilizada (ANSI). O registrador padrão para todos os aplicativos Vapor |
| neallester/swift-log-testing | fornece acesso a mensagens de log para uso em asserções (dentro dos alvos de teste) |
| Swift-log-slack | um back-end de registro que envia mensagens de registro críticas para o Slack |
| NSHipster/swift-log-github-actions | um back-end de registro que traduz mensagens de registro em comandos de fluxo de trabalho para GitHub Actions. |
| stevapple/swift-log-telegrama | um back-end de registro que envia mensagens de registro para qualquer bate-papo do Telegram (inspirado e bifurcado em wlisac/swift-log-slack) |
| jagreenwood/swift-log-datadog | um back-end de registro que envia mensagens de registro para o serviço de gerenciamento de log Datadog |
| google/SwiftLogFireCloud | um back-end de registro para registro de série temporal que envia registros como arquivos simples para o Firebase Cloud Storage. |
| crspybits/arquivo de log rápido | um registrador de arquivo local simples (usando Foundation FileManager ) |
| sushichop/cachorrinho | um back-end de registro que suporta vários transportes (console, arquivo, syslog, etc.) e possui o recurso de formatação e rotação de log de arquivo |
| ShivaHuang/swift-log-SwiftyBeaver | um back-end de registro para imprimir registros coloridos no console/arquivo Xcode ou enviar registros criptografados para a plataforma SwiftyBeaver. |
| Apodini/alce-log-rápido | um back-end de registro que formata, armazena em cache e envia dados de registro para elastic/logstash |
| raspagem binária/swift-log-supabase | um back-end de registro que envia entradas de log para Supabase. |
| matriz logarítmica rápida | um back-end de registro para enviar registros diretamente para uma sala Matrix |
| DiscordBM/DiscordLogger | uma implementação de registro do Discord para enviar seus logs para um canal do Discord de maneira bonita e com muitas opções de configuração, incluindo a capacidade de enviar apenas alguns níveis de log importantes, como warning / error / critical . |
| CacauLenhador | uma estrutura de registro rápida e simples, mas poderosa e flexível para macOS, iOS, tvOS e watchOS, que inclui um back-end de registro para registro rápido. |
| Swift-log-ecs | um back-end de registro para registro no formato ECS Log. Compatível com Vapor e permite encadeamento de vários LogHandlers. |
| ShipBook/swift-log -shipbook | um back-end de registro que envia entradas de registro para o Shipbook - o Shipbook oferece o poder de coletar, pesquisar e analisar remotamente seus registros de usuário e exceções na nuvem, por usuário e por sessão. |
| Sua biblioteca? | Entre em contato! |
Que bom que você perguntou. Acreditamos que, para o ecossistema Swift on Server, é crucial ter uma API de registro que possa ser adotada por qualquer pessoa, para que uma infinidade de bibliotecas de diferentes partes possam registrar-se em um destino compartilhado. Mais concretamente, isso significa que acreditamos que todas as mensagens de log de todas as bibliotecas terminam no mesmo arquivo, banco de dados, instância do Elastic Stack/Splunk ou o que você escolher.
No mundo real, entretanto, existem muitas opiniões sobre como exatamente um sistema de log deve se comportar, como uma mensagem de log deve ser formatada e onde/como ela deve ser persistida. Achamos que não é viável esperar que um pacote de log ofereça suporte a tudo o que uma implantação específica precisa e ao mesmo tempo seja fácil de usar e mantenha o desempenho. É por isso que decidimos reduzir o problema pela metade:
Este pacote fornece apenas a própria API de registro e, portanto, SwiftLog é um 'pacote de API de registro'. SwiftLog (usando LoggingSystem.bootstrap ) pode ser configurado para escolher qualquer implementação de back-end de registro compatível. Dessa forma, os pacotes podem adotar a API e o aplicativo pode escolher qualquer implementação de back-end de registro compatível sem exigir nenhuma alteração de nenhuma das bibliotecas.
Apenas para completar: este pacote de API na verdade inclui uma implementação de back-end de log excessivamente simplista e não configurável que simplesmente grava todas as mensagens de log em stdout . O motivo para incluir essa implementação de back-end de registro excessivamente simplista é melhorar a experiência de uso pela primeira vez. Vamos supor que você inicie um projeto e experimente SwiftLog pela primeira vez, é muito melhor ver algo que você registrou aparecer no stdout em um formato simplista, em vez de nada acontecer. Para qualquer aplicativo do mundo real, recomendamos configurar outra implementação de back-end de registro que registre no estilo que você preferir.
Logger s são usados para emitir mensagens de log e, portanto, o tipo mais importante no SwiftLog , portanto seu uso deve ser o mais simples possível. Mais comumente, eles são usados para emitir mensagens de log em um determinado nível de log. Por exemplo:
// logging an informational message
logger . info ( " Hello World! " )
// ouch, something went wrong
logger . error ( " Houston, we have a problem: ( problem ) " )Os seguintes níveis de log são suportados:
tracedebuginfonoticewarningerrorcritical O nível de log de um determinado criador de logs pode ser alterado, mas a alteração afetará apenas o criador de logs específico em que você o alterou. Você poderia dizer que Logger é um tipo de valor relacionado ao nível de log.
Os metadados de registro são metadados que podem ser anexados aos criadores de logs para adicionar informações cruciais ao depurar um problema. Em servidores, o exemplo usual é anexar um UUID de solicitação a um criador de logs que estará presente em todas as mensagens de log registradas com esse criador de logs. Exemplo:
var logger = logger
logger [ metadataKey : " request-uuid " ] = " ( UUID ( ) ) "
logger . info ( " hello world " )irá imprimir
2019-03-13T18:30:02+0000 info: request-uuid=F8633013-3DD8-481C-9256-B296E43443ED hello world
com a implementação de back-end de registro padrão fornecida com SwiftLog . Escusado será dizer que o formato é totalmente definido pelo back-end de registro que você escolher.
LogHandler )Observação: se você não deseja implementar um back-end de registro personalizado, tudo nesta seção provavelmente não é muito relevante, portanto, sinta-se à vontade para pular.
Para se tornar um back-end de registro compatível que todos os consumidores SwiftLog possam usar, você precisa fazer duas coisas: 1) implementar um tipo (geralmente um struct ) que implemente LogHandler , um protocolo fornecido pelo SwiftLog e 2) instruir SwiftLog a usar sua implementação de back-end de registro .
Um LogHandler ou implementação de back-end de registro é qualquer coisa que esteja em conformidade com o seguinte protocolo
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 }
} Instruir SwiftLog para usar seu backend de log como aquele que todo o aplicativo (incluindo todas as bibliotecas) deve usar é muito simples:
LoggingSystem . bootstrap ( MyLogHandler . init ) Os LogHandler controlam a maior parte do sistema de registro:
LogHandler LogHandler s controlam as duas partes cruciais da configuração Logger , a saber:
logger.logLevel )logger[metadataKey:] e logger.metadata ) Para que o sistema funcione, porém, é importante que o LogHandler trate a configuração como tipos de valor . Isso significa que LogHandler s devem ser struct s e uma alteração no nível de log ou nos metadados de registro deve afetar apenas o próprio LogHandler em que foi alterado.
No entanto, em casos especiais, é aceitável que um LogHandler forneça alguma substituição de nível de log global que possa afetar todos LogHandler s criados.
LogHandler s LogHandler s não controlam se uma mensagem deve ser registrada ou não. Logger só invocará a função log de um LogHandler se Logger determinar que uma mensagem de log deve ser emitida de acordo com o nível de log configurado.
Um Logger carrega um label (imutável) e cada mensagem de log carrega um parâmetro source (desde SwiftLog 1.3.0). O rótulo do Logger identifica o criador do Logger . Se você estiver usando o log estruturado preservando metadados em vários módulos, o label do Logger não é uma boa maneira de identificar a origem de uma mensagem de log, pois identifica o criador de um Logger que geralmente é passado entre bibliotecas para preservar metadados e algo parecido.
Se desejar filtrar todas as mensagens de log originadas de um determinado subsistema, filtre por source cujo padrão é o módulo que está emitindo a mensagem de log.
Consulte SECURITY.md para o processo de segurança do SwiftLog.
Esta API de registro foi projetada com os colaboradores da comunidade Swift on Server e aprovada pelo SSWG (Swift Server Work Group) para o 'nível sandbox' do processo de incubação do SSWG.
