na nossa série “Getting Started with Logging”, já cobrimos logging para muitas linguagens e frameworks: C#, Java, Python, Ruby, Ruby on Rails, Node.js, Symfony, Kotlin, Flask, Angular e Laravel. Hoje, vamos adicionar outro a esta série: PowerShell.

pode ser um estranho para adicionar à lista; PowerShell é uma linguagem de scripting, enquanto os outros podem ser vistos como linguagens de programação de Aplicação completas ou frameworks., No entanto, o PowerShell é tão poderoso que pode criar sistemas complexos e importantes o suficiente para justificar a exploração madeireira.

PowerShell é frequentemente usado para executar tarefas críticas de manutenção em computadores ou servidores. É importante para os administradores saber como esses scripts funcionavam bem ou não.

vamos ver como você pode fazer login com PowerShell de uma forma muito básica, escrevendo sua própria função de registro. Então vamos cobrir porque é que o registo da PowerShell é útil. Também falaremos sobre o que você deve registrar e o que você não deve registrar., Finalmente, vamos olhar para duas opções diferentes que vão tornar suas vidas de registro mais fácil.

Um Simples Script do PowerShell

Vamos começar com isso extremamente simples de script do PowerShell:

Este script básico recebe um número inteiro como entrada. Ele então faz a soma dos dígitos desse número. Se o resultado for maior que um único dígito, ele executa a operação novamente, até que isso resulte em um único dígito.,

Aqui estão alguns exemplos para esclarecer as coisas:

  • 45 -> 4 + 5 = 9
  • 397 -> 3 + 9 + 7 = 19 -> 1 + 9 = 10 -> 1 + 0 = 1
  • 3 -> 3

Colocar esse script em um arquivo de texto e salve-o como recursiveSum.ps1. Em seguida, você pode executá-lo em PowerShell linha de comando executando recursiveSum.ps1 45, por exemplo., A saída será as 9:

Este é um script que é simples o suficiente para funcionar como um exemplo, mas tem o suficiente passos que poderíamos estar interessados em algum registro. Claro, scripts PowerShell da vida real será muito mais complexo, garantindo a necessidade de registro ainda mais.

a maneira mais fácil de Logar em PowerShell

vamos escrever o resultado de cada passo para a consola. Já estamos escrevendo algo para o console usando a declaração de Escrita-saída, para que possamos facilmente usar isso novamente., Alterar o loop While para incluir uma declaração:

Quando você executá-lo agora, você deve ser capaz de ver uma saída como esta:

isso é ótimo! Temos algumas madeireiras. No entanto, estas declarações de log serão sempre visíveis. Em um programa mais complexo, pode fazer sentido não mostrar nada a menos que o USUÁRIO queira ver o registro. Provavelmente também é útil dar ao usuário algum controle sobre a quantidade de detalhes que eles vêem. É aqui que entram os níveis de Registo.,

Níveis de Log no PowerShell

PowerShell tem algumas Escrever-* instruções de mapa tradicionais níveis de log como:

  • Write-Verbose
  • Write-Debug
  • Escreva-a Informação
  • Escrever-Aviso
  • Write-Error

Detalhado

Vamos olhar para Escrever-Verbose primeiro. Podemos mudar nossas mensagens sobre os passos intermediários para usar Write-Verbose., Quando vamos executar o nosso script de agora, não veremos nossos passos intermediários:

Mas, se adicionar o sinalizador-Verbose, nossos registos aparecem mais uma vez:

Debug, Informação e Aviso

Debug, Informação e Aviso níveis de log de trabalho um pouco diferente do que estamos acostumados a partir tradicional frameworks de logging em outros idiomas., Vamos adicionar algumas declarações extra primeiro:

Write-Debug "This is a debug statement"Write-Information "This is an info statement"Write-Warning "This is a warning statement"

a depuração de escrita só será visível quando adicionar a opção-depuração. Ele também vai parar o seu script de correr e pedir a confirmação para continuar. Isto é útil para executar através de seus scripts passo a passo.

Mas você tem algum controle sobre se deve ou não mostrar avisos e mensagens de informações. Os comandos de Write-Warning e Write-Information podem ser controlados usando as bandeiras WarningAction e InformationAction.,se bandeiras, somente as mensagens de aviso são exibidas:

Se queremos mostrar as mensagens de informações, nós podemos fazer isso adicionando -InformationAction Continuar bandeira:

E se queremos ocultar os avisos, podemos usar o -WarningAction SilentlyContinue opção:

Erro

Finalmente, vejamos como Gravação de Erro do works., Podemos adicionar como uma instrução para o nosso script:

Write-Error "Something went wrong"

Quando esta instrução é executada, o PowerShell irá parar a execução do nosso script e o erro de gravação para o console, juntamente com alguns detalhes que podem ser úteis:

o Que É o registro em Log do Aplicativo?

vamos agora dar um passo de distância de nosso script PowerShell e olhar para o que o registro de aplicação é exatamente., O primeiro post da nossa série definiu – o bem:

registo de aplicações envolve a gravação de informações sobre o comportamento de execução da sua aplicação para um meio mais persistente.

já estamos fazendo a primeira parte: em outras palavras, capturando informações sobre o comportamento de execução da nossa aplicação. Estamos a mostrar os resultados intermédios do nosso processo. Mas não vamos fazer a segunda parte. Não estamos a gravar esta informação para um meio persistente. Quando fechamos a sessão PowerShell, perdemos esta informação. Vamos fazer isso primeiro.,

registar num ficheiro

adicionaremos esta função de Registo ao nosso ficheiro de script:

Function Log { param( $msg ) Add-Content log.txt $msg}

simplesmente pega numa String e adiciona-a a um log.ficheiro txt.,

em Seguida, nós podemos mudar a nossa declaração de log para que não mais usa a Escrita detalhada, mas esta função de Log em vez de:

Log "Intermediate result: $($sum)"

Agora podemos executar nosso script e ele irá criar um arquivo contendo o nosso intermediário passos:

Mas, se vamos executar o nosso script várias vezes, ele vai ser apenas uma longa lista de instruções. Não temos como saber quando as linhas foram registadas. Em um cenário mais complexo, contendo vários scripts, nós também não temos nenhuma maneira de saber onde a linha de log originou-i.e.,, de que arquivo ps1. Há mais informações que podemos estar a registar.

novamente, vamos dar um passo atrás e olhar para o que estamos tentando alcançar com o registro.por que fazemos login?

PowerShell é frequentemente usado para automatizar e programar certas tarefas que de outra forma seriam tediosas e propensas a erros. A automação realmente começa a fornecer valor quando é aplicada a tarefas mais complexas. Mas estes scripts complexos também podem ter mais chance de quebrar: os serviços podem não responder, configurações de máquinas podem ter mudado, etc.,

sem registo, é difícil saber se os programas correram bem ou se algo correu mal. Se alguma coisa correr mal, o registo vai ajudar-nos a descobrir onde e porquê. O registro de aplicativos também pode ajudá-lo a reunir insights sobre quais partes de seus scripts estão sendo usadas mais ou onde os ganhos de desempenho ainda podem ser feitos.

o Que não Deve Você fazer?

quando escrever as suas declarações de registo, certifique-se de que deixa de fora dados sensíveis ou pessoais., Os exemplos incluem:

  • senhas e tokens de acesso
  • números do cartão de crédito ou números de contas bancárias
  • números de segurança social
  • endereços de e-mail
  • endereços de rua
  • chaves de criptografia
  • números de segurança social

A OWASP enganar folha de registo tem uma seção sobre os dados para excluir o que é interessante para ler. Embora se destine a aplicações de pleno direito, também pode ser útil para scripts PowerShell. Posso imaginar o cenário onde os scripts PowerShell lidam com endereços de E-mail ou certas chaves de API.,

registar tal informação pessoalmente identificável (ou PII) é perigoso. Não só você precisa do consentimento explícito do usuário na maioria dos países, mas se os dados forem vazados, você ou sua empresa podem ser responsabilizados. Se não for realmente necessário, é melhor deixar esses dados de fora.

o que deve registar?

o nosso artigo sobre começar com o registo em Ruby faz um grande ponto:

deve pensar num registo como um evento—algo que é do interesse do seu aplicativo que aconteceu em algum momento.,

isto significa que, no mínimo, precisamos de uma data e uma descrição do evento. A descrição pode também incluir dados relevantes. Isto nem sempre é fácil de determinar antecipadamente. Pense sobre o que você precisa para resolver um script que não foi executado com sucesso. E se você mais tarde encontrar uma situação em que você teria exigido mais informações para corrigir um problema, adicioná-lo ao registro para a próxima vez.,

menos óbvio, mas muito útil, é incluir um nível de log:

  • no nível mais baixo, as declarações de depuração podem ser úteis para acompanhar o fluxo executado do seu programa PowerShell.
  • um nível acima são mensagens informativas sobre o lado funcional do seu script: o que foi executado, por que, e com que dados?
  • Então há também o nível de avisos: coisas que não são normais e potencialmente prejudiciais, mas que não impedem o script de continuar.
  • finalmente, as mensagens de Nível de erro Estão lá para registar os erros que fizeram o estoiro do programa.,

pode optar por registar todos estes níveis ou apenas um nível específico e subir (por exemplo, avisos e erros). Então, quando você precisar de mais informações, você pode configurar seu script para também registrar mais detalhes sobre a próxima execução.

a nossa função de registo simples não incluía níveis de Registo. Nem acrescentou uma data. Poderíamos adicionar esta funcionalidade, é claro, mas felizmente outros já criaram scripts de registro decente.

indique o programa de Registo

existe um programa simples mas útil no Technet chamado Write-Log., Se o baixarmos, podemos mudar o nosso script para ficar assim:

incluímos o ficheiro função-Write-Log.ps1, removemos a nossa função de Log e substituímos a chamada por uma chamada para Write-Log. Podemos passar uma mensagem, um nível e um caminho. O nível pode ser Informação, aviso ou erro. Note que este script não tem um nível de depuração, o que é lamentável. Você pode, no entanto, modificá-lo facilmente para incluí-lo, uma vez que o script é lançado sob a licença MIT permitindo a modificação.,

Quando usamos este script, o nosso log será parecido com este:

2019-08-20 09:18:29 INFO: Intermediate result: 512019-08-20 09:18:29 INFO: Intermediate result: 6

Agora temos linhas de log que incluem uma data, o nível de log e a nossa mensagem. É muito melhor do que tínhamos antes. Isto pode ser suficiente para suas necessidades, mas vamos dar um passo adiante e olhar para outra opção: o quadro PSFramework.

introduza a estrutura de Registo

o PSFramework é uma estrutura PowerShell que inclui vários utilitários úteis. Só vamos ver a parte da madeira.,

para começar com o PSFramework, terá primeiro de o instalar, executando o Install-Module PSFramework em PowerShell. (Você pode ter que executar seu console PowerShell como administrador). Em seguida, você pode escrever para os arquivos de log chamando o script Write-PSFMessage. No nosso caso, seria assim:

Write-PSFMessage -Level Output -Message "Intermediate result: $($sum)"

Notice how we’re not using an Info level. Em vez disso, estamos a usar a saída. Isto é porque o PSFramework usa níveis de log que correspondem mais bem com os diferentes fluxos de saída que o PowerShell tem por padrão: Verbose, Host, Output, Warning, Error, etc.,

o ficheiro de registo também será ligeiramente diferente do que estamos habituados a:

os cabeçalhos das colunas estão em falta, mas isso pode ser facilmente remediado definindo primeiro o fornecedor de registos:

este ficheiro de registo irá incluir uma data no nome do ficheiro, e irá agora incluir uma linha de cabeçalho. Isto é porque o fornecedor de log por omissão do PSFramework não irá adicionar uma linha de cabeçalho, mas o fornecedor de logfile irá., O ficheiro de registo será agora parecido com este:

isto agora inclui uma série de informações úteis, como o nome do ficheiro do nosso programa, a linha onde o registo ocorreu e o nome de utilizador do utilizador que está a correr o programa. Outra grande vantagem do registro pelo PSFramework é que ele loga assíncronamente. O registo não irá atrasar os seus scripts. Finalmente, ele também vai limpar automaticamente seus registros. Por padrão, ele irá remover arquivos de log após sete dias ou quando eles excedem 100 megabytes.,

Uma Comparação

A Função de Gravação do Registo de script corresponde a mais com que muitos programadores de aplicações que estão habituados. Ele inclui os níveis de log padrão (exceto para depuração) e escreve um arquivo de log como muitos frameworks de logg fazem: um timestamp, o nível de log, e a mensagem.

no entanto, falha alguma funcionalidade extra que pode ser crucial para si: limpeza de log; registo assíncrono; e informação técnica extra como o programa, número de linha e Utilizador de execução.,

o registo PSFramework fornece estas funcionalidades, embora exija que instale a estrutura inteira. Isto não deve ser um problema real, mas é algo a ter em mente. O PSFramework também usa diferentes níveis de registro do que estamos acostumados. No entanto, eles coincidem estreitamente com os fluxos de saída PowerShell. Isto pode parecer mais natural para usuários experientes PowerShell.o que se segue?

demos uma olhada em uma maneira simples de logar em PowerShell. Nós também melhoramos em nossa própria solução usando um script melhor (Function-Write-Log.ps1) e usando o logging incluído no PSFramework.,

uma coisa que me impressionou foi que o registro em PowerShell ainda é bastante básico. Não é que as opções que vimos sejam más ou carentes. Mas eu não encontrei um único script de registro ou módulo que inclui vários níveis de log, registro assíncrono, log clean up, e, mais importante, múltiplos destinos de log.

E se quisermos enviar erros para um endereço de E-mail? Ou se quisermos fazer login a uma base de dados? Tanto quanto eu posso ver, PSFramework oferece a maioria das opções aqui, mas e-mail ou banco de dados não estão incluídos. Pode ser possível escrever o seu próprio e registrá-lo em PSFramework, no entanto.,

isto pode ser porque o mundo de PowerShell é diferente do mundo de desenvolvimento de aplicações. Scripts PowerShell podem ser muito mais personalizados, feitos para um cenário específico, e compostos de vários scripts separados.

no entanto o registro continua importante, especialmente com scripts que correm regularmente e têm um certo nível de complexidade. PowerShell é uma linguagem poderosa para automatizar uma infinidade de Tarefas. Quando algo corre mal com tal tarefa, você quer saber o que correu mal, o que o precedeu, e como corrigi-lo. Os registos dão-lhe esta informação.,

Como um próximo passo, você pode querer olhar para agregar e gerir os seus registos. Scalyr é uma grande ferramenta para isso. Ter olhar para a API Scalyr para as diferentes opções de enviar log eventos para Scalyr. Isso pode ser facilmente chamado a partir de PowerShell e vai melhorar a sua capacidade de monitorar e resolver problemas de scripts PowerShell.

Este post foi escrito por Peter Morlion., Peter é um programador apaixonado que ajuda pessoas e empresas a melhorar a qualidade de seu código, especialmente em codebases legadas. Ele acredita firmemente que as melhores práticas da indústria são inestimáveis ao trabalhar para este objetivo, e suas especialidades incluem TDD, DI e princípios sólidos.