[PYTHON] Création d'une commande de recherche personnalisée Splunk - la première étape -

Utilisez le SDK Splunk pour créer une commande de recherche personnalisée.

On dit qu'il y a un document, mais il est difficile à comprendre, je vais donc résumer la destination de référence et la procédure. Dans un premier temps, créez une commande de recherche personnalisée generatehello [^ 2] qui renvoie" hello, world "[^ 1].

[^ 1]: En lettres basses, en l'honneur de Kernighan & Ritchie. [^ 2]: Il s'agit d'une commande dite native qui utilise le framework du Splunk SDK au lieu d'appeler le script en utilisant run. Pour savoir comment créer un script en utilisant la commande run comme commande de recherche personnalisée, "Comment créer une commande de recherche personnalisée (Splunk) --Qiita" sera utile. Je vais.

: point_up_tone3: C'est un peu vieux, mais le contenu est toujours valide Blog officiel de Splunk "[Création de commandes de recherche personnalisées en Python partie I - Une simple commande de génération](https://www.splunk.com/en_us/blog/tips] -et-astuces / construction-commandes-de-recherche-personnalisées-en-partie-python-ia-commande-de-génération-simple.html) Elle est basée sur "[^ 3]. Cependant, cet article adopte une approche ascendante.

[^ 3]: Dans le blog d'avril 2014, il est dit "Partie I", mais il semble que le blog "Partie II" ait été supprimé ou non publié.

objectif

Affiche "hello, world" dans l'instruction SPL | generatehello count = 3 et le nombre d'événements spécifié dans l'argument count (3 événements dans cet exemple).

Splunk カスタムサーチコマンド (custom search command) 作成 ― はじめの一歩 ― ゴール

Pour l'instant, créons une simple commande de recherche personnalisée qui ne prend aucun argument.

Avant de commencer

Guide de développement"Develop apps | Documentation | Splunk Developer Program"Cependant, il est souvent déroutant de lire ceci, donc je vais organiser les termes.

le terme explication facile
App(s) Pièce d'affichage(UI)、Add-sur, toute l'application, y compris les commandes de recherche personnalisées
Application en une seule, mais applications(UPS)Est souvent appelé au pluriel.
$SPLUNKHOME/etc/apps/Il est organisé en unités de répertoires ci-dessous.
Add-on(s) Pièce d'affichage(UI)Une partie ou la totalité de l'application sans
Custom Search Command Votre propre programme appelé comme commande SPL. Généralement configuré dans le cadre de l'application.

Dans cet article, il est décrit comme «SPLUNKHOME = / opt / splunk» [^ 5].

[^ 5]: En passant, il semble que certains fichiers soient codés en dur comme SPLANKHOME = / opt / splunk_home. La destination de distribution est / opt / splunk, vous pouvez donc trébucher un peu.

Environnement de développement et environnement d'exécution

Préparation

Téléchargez le SDK Splunk, extrayez-le et définissez le répertoire de développement.

Télécharger le SDK Splunk

référence: Create custom search commands | Documentation | Splunk Developer Program Voir: Downloads | Splunk Developer Program Voir aussi: GitHub --splunk / splunk-sdk-python: Kit de développement logiciel Splunk pour Python Voir aussi: Releases · splunk / splunk-sdk-python · GitHub

Le document décrit également comment installer avec pip [^ 4], mais cette fois je n'utiliserai pas l'environnement virtuel Python et n'installerai pas pip. Téléchargez et utilisez le fichier .zip ou .tar.gz.

[^ 4]: cd $ SPLUNKHOME / etc / apps / yourapp / bin; pip install -t. Splunk-sdk, etc. Développement et test dans, et introduction à Splunk.

: point_up_tone3: De «Releases · splunk / splunk-sdk-python · GitHub» au dernier (actuellement 1.6.12) .zip Téléchargez et décompressez le fichier ou le fichier .tar.gz.

Splunk SDK Téléchargez et décompressez


$ wget https://github.com/splunk/splunk-sdk-python/archive/1.6.12.tar.gz
...
2020-03-17 01:50:38 (3.12 MB/s) - ‘1.6.12.tar.gz’ saved [3876452]

$ ls
1.6.12.tar.gz
$ tar xvfz 1.6.12.tar.gz
splunk-sdk-python-1.6.12/
splunk-sdk-python-1.6.12/.gitattributes
...
splunk-sdk-python-1.6.12/utils/cmdopts.py
$

(Il y a setup.py dans le répertoire extrait, mais je ne vais pas l'utiliser cette fois.)

Mise en place d'un répertoire pour les travaux de développement

  1. Après avoir copié le modèle SDK en tant que répertoire de travail HelloWorld-work /, cp -rp splunk-sdk-python-1.6.12/examples/searchcommands_template HelloWorld-work
  2. Créez un répertoire HelloWorld-work / lib / mkdir HelloWorld-work/lib
  3. Copiez le répertoire splunklib en dessous. cp -rp splunk-sdk-python-1.6.12/splunklib/ HelloWorld-work/lib/

HelloWorld-work Installer


$ cp -rp splunk-sdk-python-1.6.12/examples/searchcommands_template HelloWorld-work
$ mkdir HelloWorld-work/lib
$ cp -rp splunk-sdk-python-1.6.12/splunklib/ HelloWorld-work/lib/
$

Vous avez maintenant une structure de répertoires comme celle ci-dessous.

HelloWork-work Arborescence des répertoires


HelloWorld-work/
|-- bin
|   |-- filter.py  ................ Eventing commands (Voir ci-dessous)Modèle.
|   |-- generate.py  .............. Generating commands (Voir ci-dessous)Modèle.
|   |Cette fois, nous utiliserons ce fichier.
|   |-- report.py  ................ Reporting commands (Voir ci-dessous)Modèle.
|   `-- stream.py  ................ Streaming commands (Voir ci-dessous)Modèle.
|-- default  ......................Le répertoire qui stocke le fichier de configuration par défaut du fournisseur.
|   |-- app.conf  .................Correct lors du réglage de Splunk.
|   |-- commands-scpv1.conf  ......Supprimez ce fichier.
|   |-- commands-scpv2.conf  ......Commande ce fichier lors de la configuration de Splunk.Remplacez par conf.
|   |Finalement, il sera supprimé.
|   |-- commands.conf  ............Lors de la configuration de Splunk
|   |Commandez ce fichier-scpv2.Remplacez par conf et corrigez.
|   |-- data
|   |   `-- ui
|   |       `-- nav
|   |           `-- default.xml  .. [Réglage]-[Interface utilisateur]-[Le menu de navigation]-[default]
|   |Il s'agit de la configuration d'affichage de l'application affichée dans.
|   `-- logging.conf  .............Cette fois, supprimez ce fichier.
|-- lib  ..........................Répertoire de la bibliothèque référencé comme PYTHONPATH.
|   |Cet emplacement n'est pas fixe, mais il est recommandé dans la documentation officielle.
|   |Si vous avez ajouté un package qui n'est pas inclus dans splunklib dans l'environnement virtuel Python
|   |                               site-packages/Vous devez mettre la bibliothèque ci-dessous.
|   `-- splunklib  ................Identique au SDK splunklib. Appelez-le avec import splunklib.
|       |-- __init__.py
:       :
:       :
|       `-- six.pyc
`-- metadata
    `-- default.meta  .............référence/L'autorisation d'écriture est spécifiée.

12 directories, 79 files

Cette structure de répertoire imite la structure du répertoire $ SPLUNKHOME / etc / apps / yourapplication /. Vous pouvez vous inscrire en tant qu'application en supprimant les fichiers inutiles et en les copiant dans $ SPLUNKHOME / etc / apps / tels quels.

: point_up_tone3: Il y a default / et local / dans le répertoire du fichier de configuration, le répertoire default / est le paramètre par défaut du fournisseur, et l'utilisateur est le répertoire local / (ou le répertoire sinon). C'est une règle de définir uniquement les modifications (en créant). Cette fois, le développeur est le fournisseur, donc modifiez directement le fichier de paramètres dans le répertoire default /.

développement de

Avant de commencer à créer des commandes de recherche personnalisées, parlons des types.

4 types de commandes de recherche personnalisées

référence: Create custom search commands | Documentation | Splunk Developer Program référence: Python classes | Documentation | Splunk Developer Program

: point_up_tone3: Il existe quatre types de commandes de recherche personnalisées.

The core of the search commands module contains four classes:

  • EventingCommand: Defines a search command that applies a transformation to search results as they travel through the events pipeline. Examples of eventing commands include sort, dedup, and cluster.
  • GeneratingCommand: Defines a search command that generates event records based on command arguments. Examples of generating commands include search (at the beginning of the pipeline), inputcsv, input lookup, and metadata.
  • ReportingCommand: Defines a search command that processes search results and generates a reporting data structure. Examples of reporting commands include stats, top, and timechart.
  • StreamingCommand: Defines a search command that applies a transformation to search results as they travel through the processing pipeline. Examples of streaming commands include search, eval, and where.

L'explication simple est la suivante.

type explication facile Lieu d'exécution Exemple de commande
Eventing commands Une commande qui reçoit une entrée, la traite et la sort Tête de recherche uniquement sort, dedup, cluster
Generating commands ContributionNon reçu, Commande de sortie Tête de recherche uniquement (Écrit au début)search, inputcsv, input lookup, metadata
Reporting commands Commande pour recevoir les entrées et les traiter au format de rapport Tête de recherche uniquement stats, top, timechart
Streaming commands Commandes de traitement et de sortie dans un environnement distribué L'indexeur est également possible en parallèle search, eval, where

Il peut être difficile de faire la distinction entre les commandes Eventing et les commandes Streaming, à la différence que les commandes Eventing ne peuvent être exécutées que dans Search Head, tandis que les commandes Streaming peuvent également être exécutées dans Indexer [^ 7]. (Voir aussi "Types de commandes" pour plus d'informations)

[^ 7]: Il existe également une commande appelée "Commandes de streaming avec état" qui ne peut être exécutée que par Search Head ... Qu'est-ce qui ne va pas ...

Dans un premier temps, nous allons créer des ** commandes de génération ** sans aucune entrée.

Générer un modèle de commandes

référence: Templates - Create custom search commands | Documentation | Splunk Developer Program

Des modèles sont disponibles pour chacun des quatre types. Parcourez le modèle Generating comannds.

Génération de modèle de commandes --generate.py

Il se trouve dans ʻexamples / searchcommands_template / bin / generate.pydans le répertoire Splunk SDK, mais sousbin /` dans le répertoire de travail que vous avez configuré.

generate.py


     1  #!/usr/bin/env python
     2
     3  import sys
     4  import os
     5
     6  sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "lib"))
     7  from splunklib.searchcommands import \
     8      dispatch, GeneratingCommand, Configuration, Option, validators
     9
    10  @Configuration()
    11  class %(command.title())Command(GeneratingCommand):
    12      """ %(synopsis)
    13
    14      ##Syntax
    15
    16      %(syntax)
    17
    18      ##Description
    19
    20      %(description)
    21
    22      """
    23      def generate(self):
    24         # Put your event  code here
    25         pass
    26
    27  dispatch(%(command.title())Command, sys.argv, sys.stdin, sys.stdout, __name__)

Modifier le modèle

Copiez le modèle generate.py dans HelloWorld.py et modifiez le nom de la commande, etc.

Remplacez % (command.title ()) aux lignes 11 et 27 par HelloWorld. Vous pouvez utiliser un éditeur, mais il peut être plus facile de le corriger avec sed.

sed Correction en utilisant


$ sed -e 's/%(command.title())/HelloWorld/' generate.py > HelloWorld.py
$ diff generate.py HelloWorld.py
11c11
< class %(command.title())Command(GeneratingCommand):
---
> class HelloWorldCommand(GeneratingCommand):
27c27
< dispatch(%(command.title())Command, sys.argv, sys.stdin, sys.stdout, __name__)
---
> dispatch(HelloWorldCommand, sys.argv, sys.stdin, sys.stdout, __name__)
$

Modify generate () - ne renvoie qu'un seul événement

Modifiez le champ appelé salutation pour renvoyer un seul "bonjour, monde".

Le type à renvoyer est un type de dictionnaire. À ce stade, Splunk utilise souvent l'heure comme clé, alors définissez l'heure dans le champ _time.

De plus, comme je l'ai écrit ci-dessus, generate () doit être de type iterate. : point_up_tone3: Il y a deux façons de faire cela.

  1. Retour avec retour: Le type de retour doit être une liste. Lors du retour avec retour, lorsque toutes les données sont disponibles, il est nécessaire de lister chaque type de dictionnaire et retour.
  2. Retour par rendement: renvoie un seul type de dictionnaire avec yeild à chaque fois.

Tout d'abord, une seule entrée sera renvoyée, alors essayons-la avec return. Insérez ʻimport time () `sur la ligne 5 pour ajouter l'heure, et modifiez les parties des lignes 24 et 25 comme suit:

     1  #!/usr/bin/env python
     2
     3  import sys
     4  import os
     5  import time      # _Nouvelle importation pour régler l'heure
     6
     7  sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "lib"))
     8  from splunklib.searchcommands import \
     9      dispatch, GeneratingCommand, Configuration, Option, validators
    10
    11  @Configuration()
    12  class HelloWorldCommand(GeneratingCommand):
    13      """ %(synopsis)
    14
    15      ##Syntax
    16
    17      %(syntax)
    18
    19      ##Description
    20
    21      %(description)
    22
    23      """
    24      def generate(self):
    25          return [{"_time": time.time(), "greeting": "hello, world"}] #Notez que c'est une liste
    26
    27
    28  dispatch(HelloWorldCommand, sys.argv, sys.stdin, sys.stdout, __name__)

La 25ème ligne met l'heure dans le champ _time, met" hello, world "dans le champ greeting et retourne sous forme de liste.

Contrôle de fonctionnement

Supprimer le fichier de paramètres inutile

Vous pouvez vérifier l'opération avec python3 HelloWorld.py __EXCECUTE__ </ dev / null, mais si vous l'exécutez telle quelle, une erreur se produira.

Erreur est survenue


$ python3 --version
Python 3.6.9
$ python3 HelloWorld.py __EXECUTE__ < /dev/null
Traceback (most recent call last):
  File "HelloWorld.py", line 8, in <module>
    from splunklib.searchcommands import \
  File "../lib/splunklib/searchcommands/__init__.py", line 145, in <module>
    from .environment import *
  File "../lib/splunklib/searchcommands/environment.py", line 120, in <module>
    splunklib_logger, logging_configuration = configure_logging('splunklib')
  File "../lib/splunklib/searchcommands/environment.py", line 103, in configure_logging
    fileConfig(filename, {'SPLUNK_HOME': splunk_home})
  File "/usr/lib/python3.6/logging/config.py", line 84, in fileConfig
    handlers = _install_handlers(cp, formatters)
  File "/usr/lib/python3.6/logging/config.py", line 131, in _install_handlers
    hlist = cp["handlers"]["keys"]
  File "/usr/lib/python3.6/configparser.py", line 959, in __getitem__
    raise KeyError(key)
KeyError: 'handlers'
$

Il s'agit d'une erreur lors de la lecture du fichier .conf.

Je vais lire les fichiers dans le répertoire default /, mais comme je n'ai rien défini pour le moment, les caractères du modèle sont toujours là.

Dans cet article, nous supprimerons une fois les fichiers inutiles, en supposant que nous effectuerons les réglages nécessaires. La cible cette fois est logging.conf. (Les mots-clés de dépannage sont ʻin configure_loggingetKeyError: 'handlers`` dans l'erreur ci-dessus.)

Supprimez logging.conf dans le répertoire default /. (Si vous souhaitez le restaurer, copiez-le à nouveau à partir du répertoire SDK.)

logging.conf&nbsp;Effacer


$ rm ../default/logging.conf
$ ls ../default/
app.conf  commands-scpv1.conf  commands-scpv2.conf  commands.conf  data
$

Essai

Exécutez le test dans l'environnement de développement.

python3 HelloWorld.py __EXECUTE__ < /dev/null

Il peut être exécuté avec la séquence de commandes. : point_up_tone3: __EXECUTE__ est deux traits de soulignement ( _) avant et après ʻEXECUTE`. Même s'il s'agit d'une commande de génération, elle attendra l'entrée standard [^ 6], spécifiez donc / dev / null comme entrée.

[^ 6]: Lorsqu'il est exécuté sur Splunk, Splunk renseigne les méta-informations pour le traitement par la bibliothèque Splunk.

Essai


$ python3 --version
Python 3.6.9
$ python3 HelloWorld.py __EXECUTE__ < /dev/null

_time,__mv__time,greeting,__mv_greeting
1584528442.0660899,,"hello, world",
$

Les champs inconnus «__mv__time» et «__mv_greeting» ont été ajoutés, que la bibliothèque Splunk ajoute automatiquement. Ici, assurez-vous que le «_time» et le «message d'accueil» prévus sont affichés.

Installation sur Splunk

Installons-le (enregistrons) sur Splunk et exécutons-le.

Modifier le fichier de paramètres

Modifiez ʻapp.confetcommands.conf dans le répertoire default /`.

Modification de ʻApp.conf`

Voir: app.conf --Splunk Documentation

Le modèle ʻapp.conf` ressemble à ceci:

app.conf


     1  # Splunk app configuration file
     2
     3  [ui]
     4  label = %(app_label)<= Corrigez cela par le nom de l'application.
     5  is_visible = 1
     6
     7  [launcher]
     8  description = %(app_description)
     9  author = %(app_author)
    10  version = %(app_version)
    11
    12  [package]
    13  id = %(app_id)
    14
    15  [install]
    16  is_configured = 0

Vous pouvez installer la commande de recherche personnalisée seule, mais elle sera définie dans le répertoire système, alors définissez le nom sur label pour l'enregistrer en tant que nouvelle application.

Ici, c'est "Hello World". D'autres parties doivent être modifiées, mais elles n'affectent pas le fonctionnement de la commande de recherche personnalisée, laissez-les donc telles quelles.

*** app.conf.orig       2020-03-18 20:00:07.303785404 +0900
--- app.conf    2020-03-18 20:00:18.943809800 +0900
***************
*** 1,7 ****
  # Splunk app configuration file

  [ui]
! label = %(app_label)
  is_visible = 1

  [launcher]
--- 1,7 ----
  # Splunk app configuration file

  [ui]
! label = Hello World
  is_visible = 1

  [launcher]

Après modification&nbsp;app.conf


# Splunk app configuration file

[ui]
label = Hello World
is_visible = 1

[launcher]
description = %(app_description)
author = %(app_author)
version = %(app_version)

[package]
id = %(app_id)

[install]
is_configured = 0

Modifiez commands.conf

Voir: commands.conf-Splunk Documentation

C'est commandes.conf qui définit la commande de recherche personnalisée.

Sous le répertoire default /, il y a trois fichiers: commands.conf, commands-scpv1.conf, et commands-scpv2.conf. Deux modèles sont disponibles car il existe des versions v1 et v2 du protocole dans lesquelles la commande de recherche personnalisée interagit avec Splunk. Le modèle, commands.conf, a le contenu de la v1.

À proprement parler, il est nécessaire d'examiner quel protocole utiliser, mais je pense que ce sera la version v2 à l'avenir, alors copiez commandes-scpv2.conf dans commands.conf et modifiez-le.

commands-scpv2.conf&nbsp;copie de


$ cp commands-scpv2.conf commands.conf
$

commands.conf&nbsp;(v2)&nbsp;modèle


     1  # [commands.conf]($SPLUNK_HOME/etc/system/README/commands.conf.spec)
     2  # Configuration for Search Commands Protocol version 2
     3
     4  [%(command.lower()]
     5  filename = %(command.lower()).py
     6  chunked = true

Si le nom de commande appelé depuis SPL et le nom de fichier à l'exclusion de .py sont identiques, il n'est pas nécessaire de définir filename, mais cette fois le nom de la commande à appeler est generatehello et le nom de fichier est HelloWorld.py. Alors, réglez-le.

De plus, comme je l'ai écrit au début, Python3 est utilisé, alors faites ce paramètre. : point_up_tone3: lors de l'utilisation de Python3

python.version = python3

Mettre en place.

Après réécriture&nbsp;commands.conf


     1  # [commands.conf]($SPLUNK_HOME/etc/system/README/commands.conf.spec)
     2  # Configuration for Search Commands Protocol version 2
     3
     4  [generatehello]
     5  filename = HelloWorld.py
     6  chunked = true
     7  python.version = python3

Copier dans le répertoire des applications Splunk

J'ai écrit le nom de l'application dans ʻapp.conf`, donc peu importe le répertoire dans lequel vous l'installez, tant que le nom du répertoire ne correspond pas aux autres applications de Splunk. Ici, appelons cela «helloworld». Supprimez les fichiers de configuration inutiles avant l'installation (copie).

: point_up_tone3: Le répertoire d'installation se trouve sous $ SPLUNKHOME / etc / apps /. Copiez l'intégralité du répertoire HelloWorld-work /. À ce stade, faites attention au propriétaire et aux autorisations du fichier. Soyez particulièrement prudent si vous exécutez Splunk en tant que non-root.

$ rm HelloWorld-work/default/commands-scpv[12].conf; sudo sh -c "cp -rp HelloWorld-work /opt/splunk/etc/apps/helloworld; chown -R splunk:splunk /opt/splunk/etc/apps/helloworld"
$ ls -ld /opt/splunk/etc/apps/helloworld/{*,}
drwxr-xr-x 6 splunk splunk 4096 Mar 18 07:52 /opt/splunk/etc/apps/helloworld/
drwxr-xr-x 2 splunk splunk 4096 Mar 18 09:33 /opt/splunk/etc/apps/helloworld/bin
drwxr-xr-x 3 splunk splunk 4096 Mar 18 11:43 /opt/splunk/etc/apps/helloworld/default
drwxr-xr-x 3 splunk splunk 4096 Mar 18 07:52 /opt/splunk/etc/apps/helloworld/lib
drwxr-xr-x 2 splunk splunk 4096 Feb 13 23:30 /opt/splunk/etc/apps/helloworld/metadata
$

Vérifier avec btool

Voir: Utiliser btool pour dépanner les configurations - Documentation Plunk

Utilisez btool pour vérifier que le fichier de configuration est correct.

$SPLUNKHOME/bin/splunk btool check

S'il n'y a pas de problème, rien ne sera affiché, mais si quelque chose ne va pas, l'écran suivant apparaîtra. (Exemple de modification accidentelle de python.version en ython.version)

Affichage en cas de problème avec le fichier de paramètres


$ sudo su splunk -c "/opt/splunk/bin/splunk btool check"
                Invalid key in stanza [generatehello] in /opt/splunk/etc/apps/helloworld/default/commands.conf, line 7: ython.version  (value:  python3).
$

Avec l'option --debug, vous obtiendrez beaucoup de messages même pour de bons fichiers de configuration.

Actualiser ou redémarrer Splunk

Les paramètres sont chargés sur http (s): // _ yourURL_ / debug / refresh, donc le redémarrage est fondamentalement inutile, mais s'il ne se charge pas, redémarrez Splunk.

Exécution de la commande de recherche personnalisée

Entrée SPL

Enfin, exécutez-le sur Splunk. Sélectionnez «Hello World» dans l'application et entrez la commande dans la fenêtre de recherche.

|generatehello

コマンド実行 (1)

Ça a marché.

  1. Sélectionnez l'application
  2. Assurez-vous que l'application est "Hello World"
  3. Saisissez «| generatehello»
  4. Un événement est affiché, l'heure est affichée, mais «Événement» est vide
  5. "salutation" existe dans les "champs associés"

Le message d'accueil n'apparaît pas comme un "événement" car les données générées ne contiennent pas de champ «_raw». Si vous cliquez sur la partie salutation du menu à gauche, vous verrez que" bonjour, monde "est affiché.

SplunkHelloWorld-002.png

Si vous voulez le sortir explicitement, spécifiez le champ avec table etc. et il sera affiché.

SplunkHelloWorld-003.png

dépannage

Si vous pensez que quelque chose est étrange, consultez le journal des travaux.

image.png

image.png

image.png

L'exemple ci-dessus est un exemple de levée d'une exception pour le test.

Jusqu'à ici pour cette fois. Si vous pouvez faire le premier pas, il sera plus facile de passer à l'étape suivante.

Résumé

La prochaine fois, je réviserai la commande et la terminerai. ⇒ J'ai écrit ce qui suit "Création de commande de recherche personnalisée Splunk partie 2-Qiita".

Recommended Posts

Création d'une commande de recherche personnalisée Splunk - la première étape -
Création d'une commande de recherche personnalisée Splunk, partie 2
Création d'une commande de recherche personnalisée pour Splunk EventingCommand
[Go] Comment créer une erreur personnalisée pour Sentry