2 ユーザーマクロ
概要
Zabbixでは、標準でサポートされているマクロに加えて、より柔軟性を持たせるためにユーザーマクロがサポートされています。
ユーザーマクロは、グローバル、テンプレート、ホストレベルで定義できます。これらのマクロには特別な構文があります。
{$MACRO}Zabbixは、以下の優先順位でマクロを解決します。
- ホストレベルのマクロ（最初にチェックされる）
- ホストの第1レベルテンプレート（ホストに直接リンクされているテンプレート）で定義されたマクロ（テンプレートIDでソート）
- ホストの第2レベルテンプレートで定義されたマクロ（テンプレートIDでソート）
- ホストの第3レベルテンプレートで定義されたマクロ（テンプレートIDでソート）、以下同様
- グローバルマクロ（最後にチェックされる）
つまり、ホストにマクロが存在しない場合、Zabbixは深さを増しながらホストテンプレート内でマクロを探します。それでも見つからない場合、存在すればグローバルマクロが使用されます。
同じ名前のマクロが同じレベルの複数のリンクされたテンプレートに存在する場合、IDが最も小さいテンプレートのマクロが使用されます。したがって、複数のテンプレートで同じ名前のマクロを持つことは、設定上のリスクとなります。
Zabbixがマクロを見つけられない場合、そのマクロは解決されません。
マクロ（ユーザーマクロを含む）は、複雑な設定をより明確にするために、設計上、[設定]セクション（たとえばトリガーリスト）では未解決のまま残されます。
ユーザーマクロは以下で使用できます。
グローバルマクロとホストマクロの一般的な使用例
- グローバルマクロを複数の場所で使用し、マクロの値を変更すると、ワンクリックですべての場所に設定変更が適用されます。
- ホスト固有の属性（パスワード、ポート番号、ファイル名、正規表現など）を持つテンプレートを活用します。
グローバルマクロの追加、更新、削除はすべてのホストのインクリメンタル設定の更新を強制するため、グローバルマクロよりもホストマクロの使用を推奨します。詳細は、Passive and active agent checksを参照してください。
設定
ユーザーマクロを定義するには、フロントエンドの該当する場所に移動します。
- グローバルマクロの場合は、管理 → マクロ にアクセスします
- ホストおよびテンプレートレベルのマクロの場合は、ホストまたはテンプレートのプロパティを開き、マクロ タブを探します
ユーザーマクロには以下の属性があります。
| パラメータ | 説明 |
|---|---|
| マクロ | マクロ名。名前は中括弧で囲み、ドル記号で始める必要があります。 例: {$FRONTEND_URL}。マクロ名で使用できる文字は、A-Z (大文字のみ)、0-9、_、. です。 |
| 値 | マクロの値。3つの値タイプがサポートされています: テキスト (デフォルト) - プレーンテキスト値 シークレットテキスト - 値はアスタリスクでマスクされます Vaultシークレット - 値はVaultシークレットへのパス/クエリを含みます。 値タイプを変更するには、値入力フィールドの最後にあるボタンをクリックします。 ユーザーマクロ値の最大長は2048文字です。 |
| 説明 | このマクロに関する追加情報を提供するためのテキストフィールドです。 |
ユーザーマクロを設定する際は、以下のコンテキスト固有の動作に注意してください。
- テンプレートのアイテムやトリガーでユーザーマクロを使用する場合は、それらのマクロをテンプレートにも追加することを検討してください（グローバルに定義されている場合でも）。そうすることで、テンプレートをXMLにエクスポートして別のシステムにインポートした後も、テキストタイプのマクロが期待通りに動作します（シークレットマクロ値はエクスポートされません）
- トリガー式でユーザーマクロを使用する場合、それらのマクロはパラメータまたは定数を参照している場合のみ解決されます。ホスト、アイテムキー、関数、演算子、または他のトリガー式を参照している場合は解決されません（シークレットマクロはトリガー式で使用できません）
- ホストでユーザーマクロを使用し、そのホストにホストプロトタイプを持つ低レベルディスカバリールールがある場合、検出されたホストは、そのホストで定義されたすべてのユーザーマクロを継承します
例
例 1
"Status of SSH daemon" item キーにホストレベルマクロを使用する。
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
agent の利用不可条件と item の更新間隔を同期させる。:
- {INTERVAL} マクロを定義し、item の更新間隔に使用する。
- {INTERVAL} を agent 使用不可トリガーのパラメータとして使用する。
nodata(/ca_001/agent.ping,{$INTERVAL})=1
例5
勤務時間の設定を集中管理する:
- グローバルマクロ{$WORKING_HOURS}を
1-5,09:00-18:00に設定する - 管理 → 一般 → GUIの勤務時間フィールドで使用する
- ユーザー → ユーザーのメディアタブの有効期間フィールドで使用する
- 勤務時間中により頻繁にアイテムのポーリングを行うために使用する
- アクションの期間条件で使用する
- 必要に応じて管理 → マクロで勤務時間を調整する
例 6
ホストプロトタイプマクロを使用して、検出されたホストの item を設定します:
ホストプロトタイプで、{$SNMPVALUE} を {#SNMPVALUE}low-level discovery マクロ値として定義します:
- ホストプロトタイプに Generic SNMPv2 テンプレートを割り当てます。
- {SNMPVALUE} を使用します。汎用SNMPv2テンプレート項目の SNMP OID* フィールドに {$SNMPVALUE} を使用します。
ユーザーマクロのコンテキスト
user macros with context を参照してください。