ユーザーマクロ
概要
Zabbixでは、標準でサポートされているマクロに加えて、柔軟性を高めるためにユーザーマクロがサポートされています。
ユーザーマクロは、グローバル、テンプレート、ホストの各レベルで定義できます。これらのマクロには、次の特殊な構文があります。
{$MACRO}Zabbixは、次の優先順位に従ってマクロを解決します。
- ホストレベルのマクロ（最初に確認）。
- ホストの第1レベルのテンプレート（ホストに直接リンクされているテンプレート）に定義されたマクロ。テンプレートID順に確認されます。
- ホストの第2レベルのテンプレートに定義されたマクロ。テンプレートID順に確認されます。
- ホストの第3レベルのテンプレートに定義されたマクロ。テンプレートID順に確認されます。以降も同様です。
- グローバルマクロ（最後に確認）。
つまり、ホストにマクロが存在しない場合、Zabbixはテンプレートの階層を順に深くたどって、ホストのテンプレート内からマクロを検索します。それでも見つからない場合、グローバルマクロが存在すれば、それが使用されます。
同じレベルの複数のリンクされたテンプレートに同じ名前のマクロが存在する場合、IDが最も小さいテンプレートのマクロが使用されます。そのため、複数のテンプレートで同じ名前のマクロを使用することは、設定上のリスクになります。
Zabbixがマクロを見つけられない場合、そのマクロは解決されません。
マクロ（ユーザーマクロを含む）は、複雑な設定をより分かりやすくするため、仕様上、設定セクション（たとえば、トリガーの一覧）では未解決のまま表示されます。
ユーザーマクロは、次の場所で使用できます。
グローバルマクロとホストマクロの一般的な使用例
- グローバルマクロを複数の場所で使用し、マクロの値を変更すると、ワンクリックですべての場所に設定変更が適用されます。
- ホスト固有の属性（パスワード、ポート番号、ファイル名、正規表現など）を持つテンプレートを活用します。
グローバルマクロの追加、更新、削除を行うと、すべてのホストに対して増分設定更新が強制されるため、グローバルマクロの代わりにホストマクロを使用することを推奨します。詳細については、Passive and active agent checksを参照してください。
設定
ユーザーマクロを定義するには、Webインターフェースの該当する場所に移動します。
- グローバルマクロの場合は、Administration > Macros を開きます。
- ホストおよびテンプレートレベルのマクロの場合は、ホストまたはテンプレートのプロパティを開き、Macros タブを確認します。
ユーザーマクロには、次の属性があります。
| Parameter | Description |
|---|---|
| Macro | マクロ名。名前は中括弧で囲み、ドル記号で始める必要があります。 例: {$FRONTEND_URL}。マクロ名に使用できる文字は、A-Z（大文字のみ）、0-9、_、. です。 |
| Value | マクロの値。3種類の値タイプがサポートされています: Text（デフォルト） - プレーンテキストの値 Secret text - 値はアスタリスクでマスクされます Vault secret - 値には vault secret へのパス/クエリが含まれます。 値タイプを変更するには、値入力フィールドの末尾にあるボタンをクリックします。 ユーザーマクロ値の最大長は 2048 文字です。 |
| Description | このマクロに関する追加情報を記載するためのテキストフィールドです。 |
ユーザーマクロを設定する際は、コンテキストに応じて次の動作に注意してください。
- ユーザーマクロがテンプレートのアイテムやトリガーで使用される場合は、それらのマクロをテンプレートにも追加することを検討してください（グローバルに定義されている場合でも同様です）。そうすることで、Text タイプのマクロは、テンプレートを XML にエクスポートして別のシステムにインポートした後も、期待どおりに動作します（secret macro の値はエクスポートされません）。
- ユーザーマクロがトリガー式で使用される場合、それらのマクロはパラメータまたは定数を参照している場合にのみ解決されます。ホスト、アイテムキー、関数、演算子、または別のトリガー式を参照している場合は解決されません（secret macro はトリガー式では使用できません）。
- ユーザーマクロが、ホストプロトタイプを持つ低レベルディスカバリルールがあるホストで使用される場合、検出されたホスト は、そのホストで定義されたすべてのユーザーマクロを継承します。
例
例 1
「SSHデーモンのステータス」アイテムキーでのホストレベルマクロの使用:
net.tcp.service[ssh,,{$SSH_PORT}]
このアイテムは、複数のホストに割り当てることができます。ただし、それらのホストで {$SSH_PORT} の値が定義されている必要があります。
例 2
「CPU load is too high」トリガーでのホストレベルマクロの使用:
last(/ca_001/system.cpu.load[,avg1])>{$MAX_CPULOAD}
このようなトリガーはテンプレート上で作成し、個々のホストで編集することはありません。
値の数を関数パラメータとして使用する場合（例: max(/host/key,#3)）、次のようにマクロ定義にハッシュ記号を含めます: SOME_PERIOD => #3。
例 3
「CPU load is too high」トリガーでの 2 つのマクロの使用:
min(/ca_001/system.cpu.load[,avg1],{$CPULOAD_PERIOD})>{$MAX_CPULOAD}
マクロはトリガー関数のパラメータとして使用できます。この例では min() 関数が該当します。
例 4
エージェントが利用できない状態の条件を、アイテムの更新間隔と同期します。
{$INTERVAL}マクロを定義し、アイテムの更新間隔で使用する{$INTERVAL}をエージェントが利用できない状態のトリガーのパラメータとして使用する
nodata(/ca_001/agent.ping,{$INTERVAL})=1
例 5
稼働時間の設定を一元化します。
{$WORKING_HOURS}マクロを作成し、1-5,09:00-18:00と設定します。- 管理 > 一般設定 > GUI の 稼働時間 フィールドで使用します。
- ユーザーの ユーザー > ユーザー の メディア タブにある 有効な時間帯 フィールドで使用します。
- 稼働時間中のアイテムのポーリング頻度を高くするために使用します。
- アクションの条件の 期間 で使用します。
- 必要に応じて、管理 > マクロ で稼働時間を調整します。
例 6
ホストプロトタイプマクロを使用して、ディスカバリされたホストのアイテムを設定します。
- ホストプロトタイプで、ユーザーマクロ
{$SNMPVALUE}を定義し、値として{#SNMPVALUE}ローレベルディスカバリ マクロを指定します。
- Generic SNMPv2 テンプレートをホストプロトタイプに割り当てます。
- Generic SNMPv2 テンプレートのアイテムの SNMP OID フィールドで
{$SNMPVALUE}を使用します。
ユーザーマクロのコンテキスト
コンテキスト付きユーザーマクロを参照してください。