- 2 アイテムの値の保存前処理
- 概要
- 設定
- サポートされている変換
- 正規表現
- 置換
- トリム
- 右トリム
- 左トリム
- XML XPath
- JSON Path
- CSVからJSONへ
- XMLからJSONへ
- SNMP walk value
- SNMP walk から JSON へ
- SNMP get value
- カスタム乗数
- 単純変化
- 1秒あたりの変化量
- ブール値から10進数へ
- 8進数から10進数へ
- 16進数から10進数へ
- JavaScript
- 範囲内
- 正規表現 {#matchesregexp} に一致
- 正規表現 {#doesnotmatchregexp} に一致しない
- JSON のエラーを確認
- XMLのエラーを確認
- 正規表現を使用したエラーのチェック
- サポートされていない値を確認
- 変更されていない値を破棄
- 変更がない場合にハートビートで破棄
- Prometheusパターン
- PrometheusからJSONへ
- マクロのサポート
- Testing
2 アイテムの値の保存前処理
概要
前処理を使用すると、受信したアイテム値をデータベースに保存する前に変換できます。 これらの変換/前処理ステップは、Zabbix サーバーまたはプロキシ（アイテムがプロキシで監視されている場合）によって実行されます。
この機能は、次のようなさまざまな用途に対応しています。
- バイトをビットに変換する（例: ネットワークトラフィック値に "8" を掛ける）;
- 増加し続ける値に対して 1 秒あたりの統計を計算する;
- 正規表現を適用して値を抽出または変更する;
- 値に対してカスタムスクリプトを実行する;
- 変化のない値を破棄してデータベースの保存領域を最適化する。
1 つ以上の前処理ステップをアイテムに設定できます。 これらのステップは、設定された順序で実行されます。
前処理ステップが失敗すると、アイテムは unsupported になります。
これは、Custom on fail のエラー処理（ほとんどの変換で利用可能）を使用することで回避でき、値を破棄したり、カスタム値を設定したりできます。
ログアイテムでは、ログメタデータ（値なし）が常にアイテムの unsupported 状態をリセットし、再びサポート対象にします。
これは、最初のエラーがエージェントからログ値を受信した後に発生した場合でも同様です。
前処理に渡されるすべての値は、最初は文字列として扱われます。 目的の値タイプ（アイテム設定で定義される）への変換は、前処理パイプラインの最後で実行されます。 ただし、特定の前処理ステップでは、必要に応じてより早い段階で変換が行われる場合があります。 詳細な技術情報については、前処理の詳細 を参照してください。
前処理設定が期待どおりに動作することを確認するには、テスト できます。
関連情報: 前処理の例
設定
前処理ステップは、アイテムの設定フォームの前処理タブで定義します。
追加をクリックして、サポートされている変換を選択します。
少なくとも1つの前処理ステップが定義されている場合、情報の型フィールドがタブの下部に表示されます。 必要に応じて、前処理タブを離れることなく情報の型を変更できます。 パラメータの詳細な説明については、アイテムの作成を参照してください。
サポートされている変換
サポートされているすべての変換を以下に示します。
変換名をクリックすると、その詳細を確認できます。
| 名前 | 説明 | タイプ |
|---|---|---|
| 正規表現 | 値を正規表現と照合し、必要な出力に置き換えます。 | テキスト |
| 置換 | 検索文字列を検索し、別の文字列（または何も指定しない）に置き換えます。 | |
| トリム | 値の先頭と末尾から指定した文字を削除します。 | |
| 右トリム | 値の末尾から指定した文字を削除します。 | |
| 左トリム | 値の先頭から指定した文字を削除します。 | |
| XML XPath | XPath機能を使用して、XMLデータから値またはフラグメントを抽出します。 | 構造化データ |
| JSON Path | JSONPath機能を使用して、JSONデータから値またはフラグメントを抽出します。 | |
| CSVからJSON | CSVファイルのデータをJSON形式に変換します。 | |
| XMLからJSON | XML形式のデータをJSONに変換します。 | |
| SNMP walk値 | 指定したOID/MIB名で値を抽出し、書式設定オプションを適用します。 | SNMP |
| SNMP walkからJSON | SNMP値をJSONに変換します。 | |
| SNMP get値 | SNMP get値に書式設定オプションを適用します。 | |
| カスタム乗数 | 値に指定した整数または浮動小数点値を乗算します。 | 算術 |
| 単純変化 | 現在の値と前回の値の差を計算します。 | 変化 |
| 1秒あたりの変化 | 値の変化（現在の値と前回の値の差）の1秒あたりの速度を計算します。 | |
| ブール値から10進数 | 値をブール形式から10進数に変換します。 | 数体系 |
| 8進数から10進数 | 値を8進数形式から10進数に変換します。 | |
| 16進数から10進数 | 値を16進数形式から10進数に変換します。 | |
| JavaScript | JavaScriptコードを入力します。 | カスタムスクリプト |
| 範囲内 | 値が含まれるべき範囲を定義します。 | 検証 |
| 正規表現に一致 | 値が一致しなければならない正規表現を指定します。 | |
| 正規表現に一致しない | 値が一致してはならない正規表現を指定します。 | |
| JSONのエラーを確認 | JSONPathにあるアプリケーションレベルのエラーメッセージを確認します。 | |
| XMLのエラーを確認 | XPathにあるアプリケーションレベルのエラーメッセージを確認します。 | |
| 正規表現を使用してエラーを確認 | 正規表現を使用してアプリケーションレベルのエラーメッセージを確認します。 | |
| サポートされていない値を確認 | アイテムの値を取得できなかったかどうかを確認します。 | |
| 変更されていない値を破棄 | 値が変更されていない場合、その値を破棄します。 | スロットリング |
| ハートビート付きで変更されていない値を破棄 | 定義した期間内に値が変更されていない場合、その値を破棄します。 | |
| Prometheusパターン | 次のクエリを使用して、Prometheusメトリクスから必要なデータを抽出します。 | Prometheus |
| PrometheusからJSON | 必要なPrometheusメトリクスをJSONに変換します。 |
選択した変換で失敗時のカスタム処理チェックボックスが有効になっている場合は、これを選択してカスタムのエラー処理オプションを指定できます。値を破棄（値を破棄）、値を設定（指定した値を設定）、またはエラーを設定（指定したエラーメッセージを設定）から選択できます。
前処理ステップが失敗した場合、値を破棄または値を設定オプションのいずれかが選択されていれば、アイテムはサポートされていない状態にはなりません。
変化およびスロットリングの前処理ステップでは、必要に応じて新しい値を計算または比較するため、Zabbixは最後の値を記憶しておく必要があります。
これらの前回の値は前処理マネージャーによって処理されます。
Zabbixサーバーまたはプロキシが再起動された場合、または前処理ステップに変更が加えられた場合、該当するアイテムの最後の値はリセットされます。その結果、次のようになります。
- 単純変化、1秒あたりの変化のステップでは、変化を計算するための前回の値がないため、次の値は無視されます。
- 変更されていない値を破棄、ハートビート付きで変更されていない値を破棄のステップでは、破棄ルールにより破棄されるべき場合でも、次の値が破棄されることはありません。
正規表現
値を正規表現と照合し、必要な出力に置き換えます。
パラメータ:
- pattern - 正規表現;
- output - 出力形式のテンプレート。 \N（N=1…9）エスケープシーケンスは、N番目に一致したグループに置き換えられます。 \0エスケープシーケンスは、一致したテキストに置き換えられます。
コメント:
- 入力値が一致しない場合、アイテムはサポート対象外になります;
- 正規表現では、\Nシーケンスを使用して最大10個のキャプチャグループを抽出できます;
- 既存の例については、正規表現のセクションを参照してください。
置換
検索文字列を見つけて、別の文字列（または何もない文字列）に置き換えます。
パラメータ:
- 検索文字列 - 検索して置換する文字列です。大文字と小文字は区別されます（必須）。
- 置換文字列 - 検索文字列を置き換える文字列です。
置換文字列は空にすることもでき、その場合、見つかった検索文字列を実質的に削除できます。
コメント:
- 検索文字列のすべての出現箇所が置換されます。
- エスケープシーケンスを使用して、改行、キャリッジリターン、タブ、スペース "\n \r \t \s" を検索または置換できます。バックスラッシュは "\\" としてエスケープでき、エスケープシーケンスは "\\n" のようにエスケープできます。
- 改行、キャリッジリターン、タブのエスケープは、ローレベルディスカバリ中に自動的に行われます。
トリム
値の先頭と末尾から指定した文字列を削除
右トリム
値の末尾から指定した文字列を削除
左トリム
値の先頭から指定した文字列を削除
XML XPath
XPath機能を使用して、XMLデータから値またはフラグメントを抽出します。
コメント:
- このオプションを使用するには、Zabbixサーバー（またはZabbixプロキシ）がlibxmlサポート付きでコンパイルされている必要があります。
- 名前空間はサポートされていません。
例:
number(/document/item/value) #<document><item><value>10</value></item></document> から「10」を抽出します
number(/document/item/@attribute) #<document><item attribute="10"></item></document> から「10」を抽出します
/document/item #<document><item><value>10</value></item></document> から「<item><value>10</value></item>」を抽出しますJSON Path
JSONPath機能を使用して、JSONデータから値またはフラグメントを抽出します。
CSVからJSONへ
CSVファイルのデータをJSON形式に変換します。
詳細については、CSVからJSONへの前処理を参照してください。
XMLからJSONへ
XML形式のデータをJSONに変換します。
詳細については、シリアライズのルールを参照してください。
SNMP walk value
指定したOID/MIB名で値を抽出し、書式設定オプションを適用します。
- 変更なし - 16進文字列をエスケープされていない16進文字列として返します（注：表示ヒントは引き続き適用されます）。
- 16進STRINGからUTF-8 - 16進文字列をUTF-8文字列に変換します。
- 16進STRINGからMAC - 16進文字列をMACアドレスとして検証し、適切なMACアドレス文字列を返します（
' 'は':'に置き換えられます）。 - BITSから整数 - 16進文字のシーケンス（例：「1A 2B 3C 4D」）として表現されたビット文字列の最初の8バイトを、64ビット符号なし整数に変換します。 8バイトを超えるビット文字列では、後続のバイトは無視されます。
SNMP walk から JSON へ
SNMP の値を JSON に変換します。
JSON のフィールド名と、対応する SNMP OID パスを指定します。 フィールドの値には、指定した SNMP OID パスの値が設定されます。
コメント:
- SNMP walk value ステップと同様の値のフォーマットオプションを使用できます。
- この前処理ステップは、SNMP OID ディスカバリに使用できます。
SNMP get value
SNMP get value に書式設定オプションを適用します。
- Hex-STRING から UTF-8 - 16進文字列をUTF-8文字列に変換します。
- Hex-STRING から MAC - 16進文字列をMACアドレスとして検証し、適切なMACアドレス文字列を返します（
' 'は':'に置き換えられます）。 - BITS から整数 - 16進文字のシーケンス（例: "1A 2B 3C 4D"）として表現されたビット文字列の最初の8バイトを、64ビット符号なし整数に変換します。 8バイトを超えるビット文字列では、後続のバイトは無視されます。
カスタム乗数
値に指定した整数または浮動小数点数を乗算します。
コメント:
- このオプションを使用すると、KB、MBps などで受信した値を B、Bps に変換できます。
これを行わない場合、Zabbix は接頭辞（K、M、G など）を正しく設定できません。
- アイテムの情報のタイプが Numeric (unsigned) の場合、カスタム乗数が適用される前に、小数部分を含む受信値は切り捨てられる（つまり、「0.9」は「0」になる）ことに注意してください。
- 情報のタイプが Numeric (unsigned) に設定されたアイテムで、カスタム乗数を使用するか、値を Change per second として保存し、計算結果が実際には浮動小数点数になる場合でも、小数部分を切り捨てて値を整数として保存することで、計算値は正しい値として受け入れられます。
- サポート対象:
1e+70などの指数表記、ユーザーマクロおよび LLD マクロ、{#MACRO}e+10、{$MACRO1}e+{$MACRO2}などのマクロを含む文字列。 マクロは整数または浮動小数点数に解決される必要があります。
単純変化
現在の値と前回の値の差を計算します。
コメント:
- 常に増加する値の測定に役立ちます。
- value-prev_value として評価されます。value は現在の値、prev_value は前回受信した値です。
- 1つのアイテムにつき、変化の計算は1種類（「単純変化」または「1秒あたりの変化」）のみ設定できます。
- 現在の値が前回の値より小さい場合、Zabbixはその差を破棄し（何も保存せず）、次の値を待ちます。
1秒あたりの変化量
現在の値と前回の値の差分を、1秒あたりの変化量として計算します。
コメント:
- このステップは、継続的に増加する値の1秒あたりの変化量を計算する場合に便利です。
- この計算では浮動小数点数が生成される可能性があるため、受信する未加工の値が整数であっても、「情報の種類」を 数値 (浮動小数) に設定することを推奨します。
これは、小さい数値で小数部分が重要になる場合に特に当てはまります。
浮動小数点値が大きく、「float」フィールドの長さを超える可能性があり、その場合に値全体が失われる可能性があるときは、数値 (符号なし) を使用して小数部分だけを切り捨てることが推奨されます。
- (value-prev_value)/(time-prev_time) として評価されます。value は現在の値、prev_value は直前に受信した値、time は現在のタイムスタンプ、prev_time は前回の値のタイムスタンプを表します。
- 1つのアイテムにつき、変化の操作（「単純な変化」または「1秒あたりの変化量」）は1つだけ許可されます。
- 現在の値が前回の値より小さい場合、Zabbixはその差分を破棄し（何も保存せず）、次の値を待機します。 これは、32ビットSNMPカウンターのラップ（オーバーフロー）などを正しく処理するのに役立ちます。
ブール値から10進数へ
値をブール形式から10進数に変換します。
コメント:
- テキスト表現は 0 または 1 のいずれかに変換されます。 したがって、'TRUE' は 1 として保存され、'FALSE' は 0 として保存されます。 すべての値は大文字と小文字を区別せずに照合されます。 現在認識される値は、TRUE の場合は true、t、yes、y、on、up、running、enabled、available、ok、master、FALSE の場合は false、f、no、n、off、down、unused、disabled、unavailable、err、slave です。 さらに、0 以外の数値は TRUE、0 は FALSE とみなされます。
8進数から10進数へ
値を8進数形式から10進数に変換します。
16進数から10進数へ
値を16進数形式から10進数に変換します。
JavaScript
パラメーターフィールド内、またはその横にある鉛筆アイコンをクリックすると開くモーダルエディターに、JavaScriptコードを入力します。
前処理のJavaScriptでは、宣言されていない代入を使用しないでください。
ローカル変数の宣言には var を使用してください。
コメント:
- 使用可能なJavaScriptの長さは、使用しているデータベース に依存します。
- 詳細については、JavaScriptによる前処理 を参照してください。
範囲内
最小値と最大値（両端を含む）を指定して、値が収まる範囲を定義します。
コメント:
- 数値を指定できます（桁数に制限はなく、小数部および指数部は任意で、負の値も指定可能です）。
- 最小値は最大値より小さくする必要があります。
- 少なくとも1つの値を指定する必要があります。
- ユーザーマクロおよびローレベルディスカバリマクロを使用できます。
正規表現 {#matchesregexp} に一致
値が一致する必要がある正規表現を指定します。
正規表現 {#doesnotmatchregexp} に一致しない
値が一致してはならない正規表現を指定します。
JSON のエラーを確認
JSONPath にあるアプリケーションレベルのエラーメッセージを確認します。成功し、メッセージが空でない場合は処理を停止します。それ以外の場合は、この前処理ステップの前にあった値で処理を続行します。
コメント:
- これらの外部サービスのエラーは、前処理ステップの情報を追加せず、そのままユーザーに報告されます。
- 無効な JSON の解析に失敗した場合、エラーは報告されません。
XMLのエラーを確認
XPathで指定されたアプリケーションレベルのエラーメッセージを確認します。 成功し、メッセージが空でない場合は処理を停止します。それ以外の場合は、この前処理ステップの前にあった値で処理を続行します。
コメント:
- これらの外部サービスエラーは、前処理ステップの情報を追加せず、そのままユーザーに報告されます。
- 無効なXMLの解析に失敗した場合、エラーは報告されません。
正規表現を使用したエラーのチェック
正規表現を使用して、アプリケーションレベルのエラーメッセージをチェックします。
成功し、メッセージが空でない場合は処理を停止します。それ以外の場合は、この前処理ステップの前の値で処理を続行します。
パラメータ:
- pattern - 正規表現;
- output - 出力フォーマット用テンプレート。
\N（N=1…9）エスケープシーケンスは、N番目に一致したグループに置き換えられます。
\0エスケープシーケンスは、一致したテキストに置き換えられます。
コメント:
- これらの外部サービスエラーは、前処理ステップの情報を追加せず、そのままユーザーに報告されます。
サポートされていない値を確認
アイテムの値を取得できなかったかどうかを確認します。 返されたエラーメッセージを調べ、その内容に基づいてエラーを処理する方法を指定します。
パラメータ:
- scope - エラー処理の範囲を選択します:
any error - すべてのエラー;
error matches - pattern に指定した正規表現に一致するエラーのみ;
error does not match - pattern に指定した正規表現に一致しないエラーのみ - pattern - エラーとの照合に使用する正規表現。
scope パラメータで any error を選択した場合、このフィールドは表示されません。
表示される場合、このフィールドは必須です。
コメント:
- 通常、値が存在しない場合や値の取得に失敗した場合、アイテムはサポートされていない状態になります。 この前処理ステップを使用すると、この動作を変更できます。
- この前処理ステップでは、アイテムの値を取得できなかったかどうかのみを確認します。 取得した値のタイプ（文字列など）がアイテムのデータ型（数値など）と一致するかどうかは確認しません。詳細については、前処理の例を参照してください。 タイプが一致しない場合、すべての前処理ステップの実行後も、アイテムがサポートされていない状態になる可能性があります。 タイプの不一致を確認するには、たとえば Custom multiplier 前処理ステップを使用できます。詳細については、前処理の例を参照してください。
- 正規表現のキャプチャグループは、Set value to または Set error to フィールドで使用できます。 一致したN番目のグループを取得するには \N（N=1…9）を使用し、一致したテキストを取得するには \0 を使用します。
- これらのステップは常に最初の前処理ステップとして実行され、アイテムへの変更を保存すると、他のすべてのステップより上に配置されます。
- 複数の Check for not supported value ステップを、指定した順序で使用できます。 any error のステップは、このグループの最後のステップとして自動的に配置されます。
変更されていない値を破棄
値が変更されていない場合、その値を破棄します。
コメント:
- 値が破棄された場合、その値はデータベースに保存されず、Zabbixサーバーはその値を受信したことを認識しません。
トリガー式は評価されないため、関連するトリガーの障害は作成も復旧もされません。
関数は、実際にデータベースに保存されたデータのみに基づいて動作します。
トレンドはデータベース内のデータに基づいて作成されるため、1時間の間に保存された値がない場合、その1時間のトレンドデータも存在しません。
- アイテムごとに指定できるスロットリングオプションは1つだけです。
変更がない場合にハートビートで破棄
定義した期間（秒単位）内に値が変更されていない場合、その値を破棄します。
コメント:
- 秒数を指定するには、正の整数値を使用できます（最小値は1秒です）。
- 時間のサフィックスを使用できます（例:
30s、1m、2h、1d）。
- ユーザーマクロおよびローレベルディスカバリマクロを使用できます。
- 値が破棄された場合、その値はデータベースに保存されず、Zabbixサーバーはこの値が受信されたことを認識しません。
その結果、トリガーの条件式は評価されず、関連するトリガーの障害が作成または解決されることもありません。
関数は、実際にデータベースに保存されたデータに基づいてのみ動作します。
トレンドはデータベース内のデータに基づいて作成されるため、1時間にわたって値が保存されなかった場合、その時間のトレンドデータも存在しません。
- 1つのアイテムにつき、指定できるスロットリングオプションは1つだけです。
Prometheusパターン
Prometheusメトリクスから必要なデータを抽出するには、次のクエリを使用します。
詳細については、Prometheusチェックを参照してください。
PrometheusからJSONへ
必要なPrometheusメトリクスをJSONに変換します。
詳細はPrometheusチェックを参照してください。
マクロのサポート
ユーザーマクロおよびコンテキスト付きユーザーマクロは、以下でサポートされています:
- JavaScriptコードを含む前処理ステップのパラメータ。
- カスタムエラー処理のパラメータ（Set value to フィールドおよび Set error to フィールド）。
マクロがその値に置き換えられる際、マクロのコンテキストは無視されます。 マクロ値はそのままコードに挿入されるため、JavaScriptコード内に値を配置する前に追加のエスケープを行うことはできません。 このため、場合によってはJavaScriptエラーが発生する可能性があることにご注意ください。
Testing
前処理テストを参照してください。