dans notre série « démarrer avec la journalisation”, nous avons déjà couvert la journalisation pour de nombreux langages et frameworks: C#, Java, Python, Ruby, Ruby on Rails, Node.js, Symfony, Kotlin, Flacon, Angulaire, et Laravel. Aujourd’hui, nous allons ajouter un autre à cette série: PowerShell.

Il peut être étrange d’ajouter à la liste; PowerShell est un langage de script, tandis que les autres peuvent être considérés comme des langages de programmation ou des frameworks complets., Pourtant, PowerShell est si puissant qu’il peut créer des systèmes complexes et suffisamment importants pour justifier la journalisation.

PowerShell est souvent utilisé pour effectuer des tâches de maintenance critiques sur des ordinateurs ou des serveurs. Il est important pour les administrateurs de savoir si ces scripts ont bien fonctionné ou non.

nous verrons comment vous pouvez vous connecter avec PowerShell de manière très basique en écrivant votre propre fonction de journalisation. Ensuite, nous expliquerons pourquoi la journalisation à partir de PowerShell est utile. Nous parlerons également de ce que vous devez enregistrer et de ce que vous ne devez pas enregistrer., Enfin, nous examinerons deux options différentes qui faciliteront votre vie de journalisation.

Un Simple Script PowerShell

commençons avec le très simple, ce script PowerShell:

Ce script de base qui prend un entier en entrée. Il fait alors la somme des chiffres de ce nombre. Si le résultat est plus long qu’un seul chiffre, il effectue à nouveau l’opération, jusqu’à ce qu’il en résulte un seul chiffre.,

Voici quelques exemples pour clarifier les choses:

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

Placez ce script dans un fichier texte et l’enregistrer en tant que recursiveSum.ps1. Ensuite, vous pouvez l’exécuter en ligne de commande PowerShell en exécutant recursiveSum.ps1 45, par exemple., La sortie sera de 9:

C’est un script qui est assez simple à fonctionner comme un exemple, mais a suffisamment de mesures que nous pourrions être intéressés à l’abattage. Bien sûr, les scripts PowerShell réels seront beaucoup plus complexes, ce qui justifiera encore plus le besoin de se connecter.

le moyen le plus simple de se connecter à PowerShell

écrivons le résultat de chaque étape dans la console. Nous écrivons déjà quelque chose sur la console en utilisant L’instruction Write-Output, donc nous pouvons facilement l’utiliser à nouveau., Modifier la boucle While pour inclure un tel énoncé:

Lorsque vous l’exécutez maintenant, vous devriez être en mesure de voir une sortie comme ceci:

C’est super! Nous avons certains enregistrement en cours. Cependant, ces instructions de journal seront toujours visibles. Dans un programme plus complexe, il peut être logique de ne rien montrer à moins que l’utilisateur ne veuille voir la journalisation. Il est probablement également utile de donner à l’utilisateur un certain contrôle sur la quantité de détails qu’il voit. C’est là que les niveaux de journal entrent en jeu.,

historique des Niveaux dans PowerShell

PowerShell a certains Écrivent-* déclarations que la carte de bûches traditionnelles des niveaux tels que:

  • Write-Verbose
  • Write-Debug
  • l’Écriture de l’Information
  • Écriture d’Alerte
  • Write-Error

Commentaire

regardons Écriture Prolixe en premier. Nous pouvons modifier nos messages sur les étapes intermédiaires pour utiliser Write-Verbose., Lorsque nous exécutons notre script maintenant, nous ne verrons pas nos étapes intermédiaires:

Mais si nous ajoutons l’indicateur-Verbose, nos journaux apparaissent à nouveau:

debug, information, and warning

les niveaux de debug, information, and warning log fonctionnent un peu différent de ce à quoi nous sommes habitués des frameworks de journalisation traditionnels dans d’autres langues., Ajoutons d’abord quelques instructions supplémentaires:

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

Le Write-Debug ne sera visible que lorsque vous ajoutez l’indicateur-Debug. Il empêchera également votre script de s’exécuter et demandera une confirmation pour continuer. Ceci est utile pour parcourir vos scripts étape par étape.

Mais vous avez un certain contrôle quant à savoir si ou de ne pas afficher les alertes et les messages d’information. Les commandes Write-Warning et Write-Information peuvent être contrôlées à l’aide des indicateurs-WarningAction et-InformationAction.,se les drapeaux, seuls les messages d’avertissement sont affichés:

Si nous voulons afficher les messages d’information, nous pouvons le faire en ajoutant -InformationAction Continuer drapeau:

Et si nous voulons cacher les mises en garde, nous pouvons utiliser l’-WarningAction SilentlyContinue option:

Erreur

Enfin, voyons comment l’Écriture d’Erreur œuvres., Nous pouvons ajouter une déclaration à notre script:

Write-Error "Something went wrong"

Lorsque cette instruction est exécutée, PowerShell arrêter l’exécution de notre script et écrire l’erreur dans la console, avec quelques détails qui pourraient être utiles:

qu’Est-Ce que Journalisation de l’Application?

éloignons-nous maintenant de notre script PowerShell et regardons ce qu’est exactement la journalisation des applications., Le premier article de notre série l’a bien défini:

la journalisation des applications implique l’enregistrement d’informations sur le comportement d’exécution de votre application sur un support plus persistant.

Nous faisons déjà la première partie: en d’autres termes, capturer des informations sur le comportement d’exécution de notre application. Nous montrons les résultats intermédiaires de notre processus. Mais nous ne faisons pas la deuxième partie. Nous n’enregistrons pas ces informations sur un support persistant. Lorsque nous fermons notre session PowerShell, nous avons perdu cette information. Nous allons le faire en premier.,

la Journalisation dans un Fichier

Nous allons ajouter cette fonction Journal de bord de notre fichier de script:

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

Il faut simplement dans une Chaîne, puis l’ajoute à un journal.fichier txt.,

Ensuite, nous pouvons changer notre journal de déclaration pour qu’elle n’utilise plus Écrire Bavard mais cette fonction de Journal à la place:

Log "Intermediate result: $($sum)"

Maintenant, nous pouvons lancer notre script et il va créer un fichier contenant les étapes intermédiaires:

Mais si nous exécuter notre script plusieurs fois, il va juste être une longue liste de déclarations. Nous n’avons aucun moyen de savoir quand les lignes ont été enregistrées. Dans un scénario plus complexe, contenant plusieurs scripts, nous n’avons également aucun moyen de savoir d’où provient la ligne de journal—c’est-à-dire,, à partir de laquelle le fichier ps1. Il y a plus d’informations que nous pourrions enregistrer.

encore une fois, prenons un peu de recul et regardons ce que nous essayons de réaliser avec la journalisation.

pourquoi enregistrons-nous?

PowerShell est souvent utilisé pour automatiser et script certaines tâches qui seraient autrement fastidieuses et sujettes aux erreurs. L’automatisation commence vraiment à apporter de la valeur lorsqu’elle est appliquée à des tâches plus complexes. Mais ces scripts complexes peuvent également avoir plus de chance de se casser: les services peuvent ne pas répondre, les configurations de la machine peuvent avoir changé, etc.,

Sans journalisation, il est difficile de savoir si les scripts ont bien fonctionné ou si quelque chose a mal tourné. Si quelque chose a mal tourné, la journalisation nous aidera à savoir où et pourquoi cela s’est produit. La journalisation des applications peut également vous aider à déterminer quels morceaux de vos scripts sont les plus utilisés ou où les gains de performances peuvent encore être réalisés.

Ce qui ne devrait pas Vous Connecter?

lorsque vous écrivez vos relevés de journalisation, assurez-vous de laisser de côté les données sensibles ou personnelles., Les exemples incluent:

  • mots de passe et jetons d’accès
  • numéros de carte de crédit ou numéros de compte bancaire
  • numéros de sécurité sociale
  • adresses e-mail
  • adresses de rue
  • clés de chiffrement
  • numéros de sécurité sociale

la feuille de triche OWASP sur la journalisation a une section Bien qu’il soit destiné à des applications à part entière, il pourrait également être utile pour les scripts PowerShell. Je peux imaginer des scénarios où les scripts PowerShell gèrent les adresses e-mail ou certaines clés API.,

L’enregistrement de ces informations personnellement identifiables (ou PII) est dangereux. Non seulement vous avez besoin du consentement explicite de l’utilisateur dans la plupart des pays, mais si les données sont divulguées, vous ou votre entreprise pourriez être tenu responsable. Si ce n’est pas vraiment nécessaire, il vaut mieux laisser ces données de côté.

Que devez-vous enregistrer?

notre article sur les débuts avec Ruby logging fait un grand point:

Vous devriez penser à une entrée de journal comme un événement—quelque chose qui intéresse votre application qui s’est produit à un moment donné.,

Cela signifie qu’au minimum, nous avons besoin d’un horodatage et une description de l’événement. La description pourrait également inclure des données. Ce n’est pas toujours facile à déterminer à l’avance. Pensez à ce dont vous auriez besoin pour résoudre un script qui n’a pas réussi à s’exécuter. Et si vous rencontrez plus tard une situation où vous auriez eu besoin de plus d’informations pour résoudre un problème, ajoutez-le à la journalisation pour la prochaine fois.,

moins évident, mais très utile, est d’inclure un niveau de log:

  • au niveau le plus bas, les instructions Debug peuvent être utiles pour suivre le flux exécuté de votre script PowerShell.
  • d’Un niveau sont des messages d’Information sur le côté fonctionnel de votre script: ce qui fut exécuté, pourquoi et avec quelles données?
  • ensuite, il y a aussi le niveau d’Avertissements: des choses qui ne sont pas normales et potentiellement dommageables mais qui n’empêchent pas le script de continuer.
  • enfin, les messages de Niveau Erreur sont là pour enregistrer les erreurs qui ont fait planter le script.,

Vous pouvez choisir de consigner tous ces niveaux ou seulement un niveau spécifique et supérieur (par exemple, les avertissements et les erreurs). Ensuite, lorsque vous avez besoin de plus d’informations, vous pouvez configurer votre script pour enregistrer également plus de détails sur la prochaine exécution.

notre propre fonction de journalisation simple n’incluait pas les niveaux de journalisation. Il n’a pas non plus ajouté d’horodatage. Nous pourrions bien sûr ajouter cette fonctionnalité, mais heureusement, d’autres ont déjà créé des scripts de journalisation décents.

entrez le Script de journalisation

Il existe un script simple mais utile sur Technet appelé Write-Log., Si nous le téléchargeons, nous pouvons changer notre script pour ressembler à ceci:

Nous avons inclus le fichier Function-Write-Log.ps1, supprimé notre fonction Log et remplacé l’appel par un appel à Write-Log. Nous pouvons transmettre un message, un niveau et un chemin d’accès. Le niveau peut être Info, Warn ou Error. Notez que ce script n’a pas de niveau de débogage, ce qui est regrettable. Vous pouvez cependant facilement le modifier pour l’inclure, car le script est publié sous la licence MIT permettant la modification.,

lorsque nous utilisons ce script, notre journal ressemblera à ceci: 

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

Nous avons maintenant des lignes de journal claires qui incluent un horodatage, le niveau de journal et notre message. C’est beaucoup mieux que ce que nous avions précédemment. Cela peut être suffisant pour vos besoins, mais allons plus loin et regardons une autre option: le PSFramework.

entrez dans le cadre de journalisation

Le PSFramework est un cadre PowerShell qui comprend plusieurs utilitaires utiles. Nous allons seulement regarder la partie logging.,

pour commencer avec PSFramework, vous devrez d’abord l’installer en exécutant Install-Module PSFramework dans PowerShell. (Vous devrez peut-être exécuter votre console PowerShell en tant qu’administrateur). Ensuite, vous pouvez écrire dans les fichiers journaux en appelant le script Write-PSFMessage. Dans notre cas, cela ressemblerait à ceci:

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

remarquez comment nous n’utilisons pas un niveau D’information. Au lieu de cela, nous utilisons Output. En effet, PSFramework utilise des niveaux de journal qui correspondent plus bien aux différents flux de sortie que PowerShell a par défaut: Verbose, Host, Output, Warning, Error, etc.,

le fichier journal sera également légèrement différent de ce à quoi nous sommes habitués:

les en-têtes de colonne sont manquants, mais cela peut facilement être corrigé en définissant le fournisseur de journalisation en premier:

Ce fichier journal inclura un horodatage dans le nom de fichier, et inclura maintenant une ligne d’en-tête. En effet, le fournisseur de journaux par défaut de PSFramework n’ajoutera pas de ligne d’en-tête, mais le fournisseur de fichiers journaux le fera., Le fichier journal doit maintenant ressembler à ceci:

Ceci inclut maintenant un grand nombre d’informations utiles comme le nom de notre script, la ligne où l’enregistrement s’est produite et le nom de l’utilisateur qui exécute le script. Un autre grand avantage de la journalisation par PSFramework est qu’elle se connecte de manière asynchrone. La journalisation ne ralentira pas vos scripts. Enfin, il nettoiera également automatiquement vos journaux. Par défaut, il supprimera les fichiers journaux après sept jours ou lorsqu’ils dépassent 100 mégaoctets.,

Une Comparaison

La Fonction de l’Écriture du Journal de script correspond plus à ce que beaucoup de programmeurs d’application sont utilisés pour. Il inclut les niveaux de journal standard (sauf pour Debug) et écrit un fichier journal comme le font de nombreux frameworks de journalisation: un horodatage, le niveau de journal et le message.

cependant, il manque certaines fonctionnalités supplémentaires qui pourraient être cruciales pour vous: Nettoyage des journaux; journalisation asynchrone; et des informations techniques supplémentaires comme le script, le numéro de ligne et l’utilisateur d’exécution.,

la journalisation PSFramework fournit ces fonctionnalités, bien qu’elle vous oblige à installer l’ensemble du framework. Cela ne devrait pas être un vrai problème, mais c’est quelque chose à garder à l’esprit. Le PSFramework utilise également des niveaux de journalisation différents de ceux auxquels nous sommes habitués. Cependant, ils correspondent étroitement aux flux de sortie PowerShell. Cela peut sembler plus naturel pour les utilisateurs expérimentés de PowerShell.

Quelle est la prochaine étape?

Nous avons examiné un moyen simple de se connecter à PowerShell. Nous avons également amélioré notre propre solution en utilisant un meilleur script (Function-Write-Log. ps1) et en utilisant la journalisation incluse dans PSFramework.,

une chose qui m’a frappé, c’est que la connexion à PowerShell est encore assez basique. Ce n’est pas que les options que nous avons examinées sont mauvaises ou manquantes. Mais je n’ai pas trouvé un seul script ou module de journalisation qui inclut plusieurs niveaux de journal, une journalisation asynchrone, un nettoyage de journal et, plus important encore, plusieurs destinations de journal.

Que Faire si nous voulons envoyer des erreurs à une adresse e-mail? Et si nous voulons nous connecter à une base de données? Pour autant que je puisse voir, PSFramework offre le plus d’options ici, mais le courrier électronique ou la base de données ne sont pas inclus. Il pourrait être possible d’écrire le vôtre et de l’enregistrer dans PSFramework, cependant.,

cela pourrait être dû au fait que le monde de PowerShell est différent du monde du développement d’applications. Les scripts PowerShell peuvent être beaucoup plus personnalisés, destinés à un scénario spécifique et composés de plusieurs scripts distincts.

pourtant, la journalisation reste importante, en particulier avec les scripts qui s’exécutent régulièrement et ont un certain niveau de complexité. PowerShell est un langage puissant pour automatiser une multitude de tâches. Quand quelque chose ne va pas avec une telle tâche, vous voulez savoir ce qui a mal tourné, ce qui l’a précédé et comment le réparer. Les journaux vous donnent ces informations.,

dans une prochaine étape, vous voudrez peut-être regarder à l’agrégation et de la gestion de vos journaux. Scalyr est un excellent outil pour cela. Consultez L’API Scalyr pour connaître les différentes options d’envoi d’événements de journal à Scalyr. Cela peut facilement être appelé à partir de PowerShell et améliorera votre capacité de surveillance et de dépannage de vos scripts PowerShell.

Ce billet a été écrit par Peter Morlion., Peter est un programmeur passionné qui aide les gens et les entreprises à améliorer la qualité de leur code, en particulier dans les bases de code héritées. Il croit fermement que les meilleures pratiques de l’industrie sont inestimables pour atteindre cet objectif, et ses spécialités comprennent TDD, DI et principes solides.