個人用ツール

Pandora:Documentation ja:Anexo Agent Plugins

提供: Pandora FMS Wiki JP

移動先: 案内, 検索

Pandora FMS ドキュメント一覧に戻る

エージェントプラグイン開発

エージェントプラグインの基本機能

The agent plugin is executed by the Pandora FMS Software Agent so it should have some special features:

エージェントプラグインは、Pandora FMS ソフトウエアエージェントで実行され、いくつかの特別な機能があります。

  • Each execution of the plugin could return one or several modules with their correspondent values. The exit should have a XML format as we will explain later:
  • それぞれのプラグインの実行では、一つまたは複数のモジュールの値を返します。出力は後述する XML フォーマットである必要があります。
  • It could have access both local resources to the machine or a resources from other machine in a remote way.
  • ローカルマシンのリソースおよび、リモートで他のマシンのリソースの両方にアクセスすることができます。
  • It is possible to use any kind of programming language supported by the operative system where the Pandora software agent would be installed.
  • Pandora ソフトウエアエージェントがインストールされている OS でサポートしている、任意のプログラミング言語を利用することができます。
  • All dependencies or necessary software to execute the plugin should be available and be installed in the same machine that executes the Pandora software.
  • プラグインを実行するために必要な依存プログラムは、Pandora ソフトウエアエージェントを実行するのと同じマシンにインストールされている必要があります。

The agent plugins could do a kind of "recon task" so the plugin could return several modules in one execution and the number could change between different executions.

エージェントプラグインは、"自動検出タスク" のようなことを実行でき、プラグインは一度の実行で複数のモジュールを返すことができ、また、実行ごとに異なる数を返すことができます。

Template warning.png

In UNIX and Linux the exit status value of the plugin must be 0, otherwise the plugin output will be ignored


Template warning.png

UNIX および Linux では、プラグインの終了ステータスは 0 でなければなりません。そうでないと、プラグインの出力は無視されます。


エージェントプラグイン開発の例

We are going to explain now an example of a simple plugin. This agent plugin returns the percentage of use of the system filesystems. The code is the following one:

簡単なプラグインの例を説明します。このエージェントプラグインは、ファイルシステムの利用率を返します。プログラムコードは次の通りです。

#!/usr/bin/perl
 
use strict;

sub usage() {
        print "\npandora_df.pl v1r1\n\n"; 
        print "usage: ./pandora_df\n";
        print "usage: ./pandora_df tmpfs /dev/sda1\n\n";
}
 
# Retrieve information from all filesystems
my $all_filesystems = 0;

# Check command line parameters
if ($#ARGV < 0) {
        $all_filesystems = 1;
}

if ($ARGV[0] eq "-h") {
        usage();
        exit(0);
}

# Parse command line parameters
my %filesystems;
foreach my $fs (@ARGV) {
        $filesystems{$fs} = '-1%';
}

# Retrieve filesystem information
# -P use the POSIX output format for portability
my @df = `df -P`;
shift (@df);

# No filesystems? Something went wrong.
if ($#df < 0) {
        exit 1;
}

# Parse filesystem usage
foreach my $row (@df) {
        my @columns = split (' ', $row);
        exit 1 if ($#columns < 4);
        $filesystems{$columns[0]} = $columns[4] if (defined ($filesystems{$columns[0]}) || $all_filesystems == 1);
}

while (my ($filesystem, $use) = each (%filesystems)) {

        # Remove the trailing %
        chop ($use); 

        # Print module output
        print "<module>\n";
        print "<name><![CDATA[" . $filesystem . "]]></name>\n";
        print "<type><![CDATA[generic_data]]></type>\n";
        print "<![CDATA[" . $use . "]]>\n";
        print "<description>% of usage in this volume</description>\n";
        print "</module>\n";
}

exit 0;

An important part of the code is the usage function:

コードの重要部分は、利用方法を表示する関数です。

sub usage() {
        print "\npandora_df.pl v1r1\n\n"; 
        print "usage: ./pandora_df\n";
        print "usage: ./pandora_df tmpfs /dev/sda1\n\n";
}


In this function it describes the version and how to use the plugin. It is very important and it should be shown when executing the plugin without any kind of parameter or with an action type -h or --help. In this example is executed when the parameter -h is executed, the following lines verify it:

この関数では、プラグインのバージョンと利用方法を説明します。これはとても重要で、パラメータ無しや -h, --help といったオプションをつけてプラグインを実行したときに表示すべきです。この例では、-h オプションをつけて実行した場合、次の処理でそれを判断します。

if ($ARGV[0] eq "-h") {
        usage();
        exit(0);
}


Regarding the values returned by the plugin, you can notice that onece the data has been collected from the following file systems, an XML part is created and printe by the standard exit for any one of them. This task is done in the following lines:

プラグインから返される値としては、ファイルシステムから一回データが収集されることがわかると思います。データを含めた XML の書式を生成し標準出力に出力します。この処理は次の部分で行われています。


while (my ($filesystem, $use) = each (%filesystems)) {

        # Remove the trailing %
        chop ($use); 

        # Print module output
        print "<module>\n";
        print "<name><![CDATA[" . $filesystem . "]]></name>\n";
        print "<type><![CDATA[generic_data]]></type>\n";
        print "<![CDATA[" . $use . "]]>\n";
        print "<description>% of usage in this volume</description>\n";
        print "</module>\n";
}

An example of the result that this plugin returns could be:

このプラグインの出力結果は、次のようになります。


<module>
<name><![CDATA[tmpfs]]></name>
<type><![CDATA[generic_data]]></type>
<![CDATA[0]]>
<description>% of usage in this volume</description>
</module>
<module>
<name><![CDATA[/dev/mapper/VolGroup-lv_home]]></name>
<type><![CDATA[generic_data]]></type>
<![CDATA[26]]>
<description>% of usage in this volume</description>
</module>
<module>
<name><![CDATA[/dev/sda9]]></name>
<type><![CDATA[generic_data]]></type>
<![CDATA[34]]>
<description>% of usage in this volume</description>
</module>


The number of returned modules by this plugin will depend on the number of configured filesystems and it could change between different executions.

このプラグインから返されるモジュール数は、設定したファイルシステムの数に依存し、実行ごとに変更することができます。

The XML piece is added to the general XML that the software agent generates and it is sent to the Pandora server to be processed by the Data Server

この XML がソフトウエアエージェントが生成する全体の XML に追加され、Pandora サーバへ送信され、データサーバ にて処理されます。

トラブルシューティング

If Pandora FMS does not recognize your agent plugin, you don't get the information you expect or the agent just doesn't want to work, there are a few things which you have to keep in mind:

Pandora FMS がエージェントプラグインを認識できないと、期待した値が取得できなかったりエージェントが動作しません。その場合の確認ポイントを以下に示します。

pandora_agent.conf のドキュメント確認

The Software Agent needs a line in this file with the correct path of the plugin.

ソフトウエアエージェントでは、プラグインの 正しいパス がこのファイル内に書かれている必要があります。

For example:

例:

 module_plugin /etc/pandora/plugins/MyMonitor.pl /etc/pandora/plugins/MyMonitor.conf 2> /etc/pandora/plugins/MyMonitor.err

MyMonitor.pl is the agent plugin, MyMonitor.conf is the configuration file passed as an argument, and MyMonitor.err is a file that will receive the possible errors of the plugin execution and will keep clean the standard output.

MyMonitor.pl はエージェントプラグインで、MyMonitor.conf は引数として渡される設定ファイルです。また、MyMonitor.err はプラグインを実行した場合に出力されるエラーを書き込むファイルです。

pandora_agent_daemon の再起動

If you have the basic version of Pandora FMS (not Enterprise), the Software Agent will run the plugins every five minutes. For those people who can not wait, it is possible to restart the Software Agent from the command line.

Pandora FMS の (Enterprise 版ではなく) OSS 版 を利用している場合は、ソフトウエアエージェントは 5分ごとにプラグインを実行します。次回の実行まで待てない場合は、コマンドラインからソフトウエアエージェントを再起動します。

For example:

例:

/etc/init.d/pandora_agent_daemon restart

プラグインのパーミッションの確認

The plugin, and the files which are going to be used for it, must have the correct read, write and execute permissions. In Unix this should be enough:

プラグインおよび利用するファイルは、リード、ライト、実行の権限を正しく設定する必要があります。Unix であれば、次のようにします。

chmod 755 <plugin_path>
chmod 755 <プラグインファイル>

出力の確認

An easy way to find the errors is run the plugin manually in the command line. Sit down and check the output carefully, for example:

エラーを見つける簡単な方法は、コマンドラインでプラグインを手動実行することです。注意して出力結果を確認してください。例えば、次のように実行します。

popeye:/etc/pandora/plugins # ./pandora_df 
<module>
<name><![CDATA[/dev/sda2]]></name>
<type><![CDATA[generic_data]]></type>
<data><![CDATA[19]]></data>
<description>% of usage in this volume</description>
</module>
<module>
<name><![CDATA[udev]]></name>
<type><![CDATA[generic_data]]></type>
<data><![CDATA[1]]></data>
<description>% of usage in this volume</description>
</module>

XMLの確認

The XML that prints the plugin must have valid XML syntax. The XML also needs to be well formed. To check if it is, you could follow this steps from the command line:

  1. Create an XML document with the plugin output: ./Plugin.pl > Plugin.xml
  2. Check the XML document: xmllint Plugin.xml

プラグインが出力する XML は、独自プラグインの作成方法 に従っている必要があります。 XML はまた、正しく整形されている必要があります。それを確認するためには、コマンドラインから次の手順を実行します。

  1. プラグインの出力を xml ファイルに落とします。: ./Plugin.pl > Plugin.xml
  2. xml ファイルの書式をチェックします。: xmllint Plugin.xml

デバッグモード

You can activate the debug mode by changing the value of the label debug in your pandora_agent.conf file from 0 to 1. Once you do this, when the Software Agent run the plugin, the results will be saved in an XML document with all the agent information.

pandora_agent.conf ファイル内で、debug の値を 0 から 1に変更することで、デバッグモードを有効にすることができます。これを行うと、ソフトウエアエージェントがプラグインを実行した結果が、エージェントのその他の情報とあわせて xml ファイルに保存されます。

The name of the document will be the agent name with .data, and will be located in /tmp directory (checkout the pandora agent log at /var/log/pandora/pandora_agent.log). By checking the document, you can see if the data of your plugin are being collected and if it what you expect.

ファイル名は、エージェント名と .data を含むもので、/tmp ディレクトリに保存されます(pandoraエージェントのログは、/var/log/pandora/pandora_agent.log を確認してください)。内容を確認し、期待したプラグインの実行結果が含まれているかどうかを見ます。

Info.png

When you enable Debug mode, the agent executes only once and exits


Info.png

デバッグモードを有効にすると、エージェントは 1回の実行で終了します。


フォーラム

If the error remains after all, fell free to ask in our forum.

それでもまだうまくいかない場合は、我々の フォーラム (日本語フォーラムは こちら) で聞いてみてください。

Pandora FMS ドキュメント一覧に戻る