- 2 アイテムの値の保存前処理
- 概要
- 設定
- サポートされている変換
- 正規表現
- {#replace} の置換
- Trim
- 右側トリム
- 左トリム
- 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へ
- マクロのサポート
- テスト
2 アイテムの値の保存前処理
概要
保存する前に、前処理を使用して受信したアイテムの値に変換を適用できます。 これらの変換/前処理ステップは、Zabbixサーバーまたはプロキシ（アイテムがプロキシによって監視されている場合）によって実行されます。
この機能は、次のようなさまざまな用途に対応しています。
- バイトをビットに変換する（例: ネットワークトラフィック値に「8」を掛ける）;
- 増加し続ける値について、1秒あたりの統計を計算する;
- 正規表現を適用して値を抽出または変更する;
- 値に対してカスタムスクリプトを実行する;
- データベースストレージを最適化するために、変更されていない値を破棄する。
1つのアイテムに対して、1つ以上の前処理ステップを設定できます。 これらのステップは、設定された順序で実行されます。
前処理ステップが失敗すると、アイテムはサポートされていない状態になります。
これは、Custom on fail エラーハンドリング（ほとんどの変換で利用可能）を使用することで回避でき、値を破棄したり、カスタム値を設定したりできます。
ログアイテムの場合、ログメタデータ（値を含まない）によって、アイテムのサポートされていない状態は常にリセットされ、再びサポートされる状態になります。
これは、最初のエラーがエージェントからログ値を受信した後に発生した場合でも同様です。
前処理に渡されるすべての値は、最初は文字列として扱われます。 目的の値の型（アイテム設定で定義）への変換は、前処理パイプラインの最後に実行されます。 ただし、特定の前処理ステップでは、必要に応じてそれより前に変換が行われる場合があります。 技術的な詳細については、前処理の詳細を参照してください。
前処理の設定が期待どおりに動作することを確認するには、テストできます。
関連項目: 前処理の例
設定
前処理ステップは、アイテム設定フォームの前処理タブで定義します。
追加をクリックして、サポートされている変換を選択します。
少なくとも1つの前処理ステップが定義されている場合、タブの下部に情報の種類フィールドが表示されます。 必要に応じて、前処理タブを離れずに情報の種類を変更できます。 パラメータの詳細については、アイテムの作成を参照してください。
サポートされている変換
サポートされているすべての変換を以下に示します。 変換名をクリックすると、その詳細を確認できます。
| Name | Description | Type |
|---|---|---|
| 正規表現 | 値を正規表現と照合し、必要な出力に置き換えます。 | Text |
| 置換 | 検索文字列を検索し、別の文字列（または何もない状態）に置き換えます。 | |
| トリム | 値の先頭と末尾から指定した文字を削除します。 | |
| 右トリム | 値の末尾から指定した文字を削除します。 | |
| 左トリム | 値の先頭から指定した文字を削除します。 | |
| XML XPath | XPath機能を使用して、XMLデータから値またはフラグメントを抽出します。 | Structured data |
| 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値に書式設定オプションを適用します。 | |
| カスタム乗数 | 指定した整数または浮動小数点値を値に乗算します。 | Arithmetic |
| 単純変化 | 現在の値と前回の値の差を計算します。 | Change |
| 1秒あたりの変化 | 値の変化（現在の値と前回の値の差）の1秒あたりの速度を計算します。 | |
| ブール値から10進数 | 値をブール形式から10進数に変換します。 | Numeral systems |
| 8進数から10進数 | 値を8進数形式から10進数に変換します。 | |
| 16進数から10進数 | 値を16進数形式から10進数に変換します。 | |
| JavaScript | JavaScriptコードを入力します。 | Custom scripts |
| 範囲内 | 値が含まれるべき範囲を定義します。 | Validation |
| 正規表現に一致 | 値が一致する必要がある正規表現を指定します。 | |
| 正規表現に一致しない | 値が一致してはならない正規表現を指定します。 | |
| JSONのエラーを確認 | JSONPathにあるアプリケーションレベルのエラーメッセージを確認します。 | |
| XMLのエラーを確認 | XPathにあるアプリケーションレベルのエラーメッセージを確認します。 | |
| 正規表現を使用してエラーを確認 | 正規表現を使用してアプリケーションレベルのエラーメッセージを確認します。 | |
| サポートされていない値を確認 | アイテムの値を取得できなかったかどうかを確認します。 | |
| 変更されていない値を破棄 | 変更されていない値を破棄します。 | Throttling |
| ハートビート付きで変更されていない値を破棄 | 定義した期間内に変更されていない値を破棄します。 | |
| Prometheusパターン | 次のクエリを使用して、Prometheusメトリクスから必要なデータを抽出します。 | Prometheus |
| PrometheusからJSON | 必要なPrometheusメトリクスをJSONに変換します。 |
選択した変換でCustom on failチェックボックスが有効になっている場合は、これを選択して、カスタムのエラー処理オプションを指定できます。Discard value（値を破棄）、Set value to（指定した値を設定）、またはSet error to（指定したエラーメッセージを設定）を選択できます。 前処理ステップが失敗した場合、Discard valueまたはSet value toオプションのいずれかが選択されていれば、アイテムはサポートされていない状態になりません。
ChangeおよびThrottlingの前処理ステップでは、必要に応じて新しい値を計算または比較するために、Zabbixは最後の値を記憶する必要があります。 これらの以前の値は前処理マネージャーによって処理されます。 Zabbixサーバーまたはプロキシが再起動された場合、または前処理ステップに変更が加えられた場合、該当するアイテムの最後の値はリセットされ、その結果は次のようになります。
- Simple change、Change per secondステップの場合 - 変化を計算するための以前の値がないため、次の値は無視されます。
- Discard unchanged、Discard unchanged with heartbeatステップの場合 - 破棄ルールにより破棄されるべき場合でも、次の値は破棄されません。
正規表現
値を正規表現と照合し、必要な出力に置き換えます。
パラメータ:
- pattern - 正規表現;
- output - 出力形式のテンプレート。 \N（N=1…9）エスケープシーケンスは、N番目に一致したグループに置き換えられます。 \0エスケープシーケンスは、一致したテキストに置き換えられます。
コメント:
- 入力値との照合に失敗すると、アイテムはサポートされていない状態になります;
- 正規表現では、\Nシーケンスを使用して最大10個のキャプチャグループを抽出できます;
- 既存の例については、正規表現のセクションを参照してください。
{#replace} の置換
検索文字列を見つけて、別の文字列(または何もない)に置き換えます。
パラメータ:
- 検索文字列 - 見つけて置き換える文字列、大文字と小文字を区別します(必須);
- 置換文字列 - 検索文字列を置き換える文字列。 置換文字列を空にすることもでき、見つかった検索文字列を削除することができます。
コメント:
- 検索文字列のすべての出現箇所が置換されます;
- エスケープシーケンスを使用して、改行、復帰、タブ、スペース "\n \r \t \s" を検索または置換できます; バックスラッシュは "\\" でエスケープでき、エスケープシーケンスは "\\n" でエスケープできます;
- 改行、復帰、タブのエスケープは、低レベルディスカバリ中に自動的に行われます。
Trim
値の先頭と末尾から指定した文字を削除します。
右側トリム
値の末尾から指定した文字を削除します。
左トリム
値の先頭から指定した文字を削除します。
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進文字列として返します（注：表示ヒントは引き続き適用されます）。
- hex-STRING から UTF-8 - 16進文字列を UTF-8 文字列に変換します。
- hex-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 を選択した場合、このフィールドは表示されません。
表示される場合、このフィールドは必須です。
コメント:
- 通常、値を取得できない場合、アイテムは未サポートになります。 この前処理ステップを使用すると、この動作を変更できます。
- この前処理ステップでは、アイテムの値を取得できなかったかどうかのみを確認します。 取得した値のタイプ（文字列など）がアイテムのデータ型（数値など）と一致するかどうかは確認しません。詳細については、前処理の例を参照してください。 タイプが一致しない場合、すべての前処理ステップの実行後もアイテムが未サポートになる可能性があります。 タイプの不一致を確認するには、たとえば カスタム乗数 前処理ステップを使用できます。詳細については、前処理の例を参照してください。
- 正規表現のキャプチャグループは、Set value to または Set error to フィールドで使用できます。 一致した N 番目のグループを取得するには \N（N=1…9）を使用し、一致したテキストを取得するには \0 を使用します。
- これらのステップは常に最初の前処理ステップとして実行され、アイテムへの変更を保存した後、他のすべてのステップより上に配置されます。
- 複数の 未サポート値のチェック ステップを、指定した順序で使用できます。 any error のステップは、このグループの最後のステップとして自動的に配置されます。
変更されていない値を破棄する
値が変更されていない場合は破棄します。
コメント:
- 値が破棄された場合、データベースには保存されず、Zabbixサーバーはこの値が受信されたことを認識しません。
トリガー式は評価されず、その結果、関連するトリガーの問題は作成/解決されません。
関数は、実際にデータベースに保存されたデータに基づいてのみ動作します。
トレンドはデータベース内のデータに基づいて構築されるため、1時間に値が保存されていない場合、その時間のトレンドデータもありません。
- アイテムごとに指定できるスロットリングオプションは1つだけです。
変更されない値をハートビートで破棄
定義した期間（秒単位）内に変更されなかった値を破棄します。
コメント:
- 秒数を指定するには、正の整数値を使用できます（最小値は1秒）。
- 時間のサフィックスを使用できます（例:
30s、1m、2h、1d）。
- ユーザーマクロおよびローレベルディスカバリマクロを使用できます。
- 値が破棄された場合、その値はデータベースに保存されず、Zabbixサーバーはこの値が受信されたことを認識しません。
その結果、トリガーの条件式は評価されず、関連するトリガーの障害は作成または解決されません。
関数は、実際にデータベースに保存されたデータに基づいてのみ動作します。
トレンドはデータベース内のデータに基づいて作成されるため、1時間値が保存されなかった場合、その1時間分のトレンドデータも存在しません。
- 1つのアイテムにつき、指定できるスロットリングオプションは1つだけです。
Prometheusパターン
Prometheusメトリクスから必要なデータを抽出するには、次のクエリを使用します。
詳細はPrometheusチェックを参照してください。
PrometheusからJSONへ
必要なPrometheusメトリクスをJSONに変換します。
詳細はPrometheusチェックを参照してください。
マクロのサポート
ユーザーマクロおよびコンテキスト付きユーザーマクロは、以下でサポートされています。
- 前処理ステップのパラメータ（JavaScriptコードを含む）
- カスタムエラーハンドリングパラメータ（値を設定およびエラーを設定フィールド）
マクロが値に置き換えられるとき、マクロのコンテキストは無視されます。 マクロ値はそのままコードに挿入され、JavaScriptコードに値を配置する前に追加のエスケープを行うことはできません。 このため、場合によってはJavaScriptエラーが発生する可能性があることにご注意ください。
テスト
事前処理のテストを参照してください。