2 アイテムの値の保存前処理

概要

前処理では、受信したアイテムの値をデータベースに保存する前に変換を適用できます。 これらの変換/前処理ステップは、Zabbixサーバーまたはプロキシ（アイテムがプロキシによって監視されている場合）によって実行されます。

この機能は、例えば次のようなさまざまな用途に対応しています。

• バイトをビットに変換する（例: ネットワークトラフィックの値に「8」を掛ける）;
• 増加し続ける値について1秒あたりの統計を計算する;
• 正規表現を適用して値を抽出または変更する;
• 値に対してカスタムスクリプトを実行する;
• 変更されていない値を破棄してデータベースストレージを最適化する。

1つのアイテムに対して、1つ以上の前処理ステップを設定できます。 これらのステップは、設定された順序で実行されます。

前処理に渡されるすべての値は、最初は文字列として扱われます。 目的の値の型（アイテム設定で定義）への変換は、前処理パイプラインの最後に実行されます。 ただし、特定の前処理ステップでは、必要に応じてそれより前に変換が行われる場合があります。 詳細な技術情報については、前処理の詳細を参照してください。

前処理の設定が期待どおりに動作することを確認するには、テストできます。

関連項目: 前処理の例

設定

前処理ステップは、アイテムの設定フォームの前処理タブで定義します。

追加をクリックして、サポートされている変換を選択します。

少なくとも1つの前処理ステップが定義されている場合、情報の型フィールドがタブの下部に表示されます。 必要に応じて、前処理タブを離れることなく情報の型を変更できます。 パラメータの詳細な説明については、アイテムの作成を参照してください。

サポートされている変換

サポートされているすべての変換を以下に示します。 変換名をクリックすると、その詳細を確認できます。

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個のキャプチャグループを抽出できます。
  
• Custom on fail チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。 前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、アイテムは未サポートになりません。
  
• 既存の例については、正規表現 セクションを参照してください。

置換

検索文字列を見つけて、別の文字列（または何もない文字列）に置き換えます。

パラメータ:

• 検索文字列 - 検索して置換する文字列です。大文字と小文字は区別されます（必須）。
  
• 置換文字列 - 検索文字列を置き換える文字列です。
  置換文字列は空にすることもでき、その場合、見つかった検索文字列を実質的に削除できます。

コメント:

• 検索文字列のすべての出現箇所が置換されます。
• エスケープシーケンスを使用して、改行、キャリッジリターン、タブ、スペース "\n \r \t \s" を検索または置換できます。バックスラッシュは "\\" としてエスケープでき、エスケープシーケンスは "\\n" のようにエスケープできます。
• 改行、キャリッジリターン、タブのエスケープは、ローレベルディスカバリ中に自動的に行われます。

{#trim} のトリム

値の先頭と末尾から指定した文字を削除します。

右トリム

値の末尾から指定した文字を削除します。

左トリム

値の先頭から指定した文字を削除します。

XML XPath

XPath機能を使用して、XMLデータから値またはフラグメントを抽出します。

コメント:

• このオプションを機能させるには、Zabbixサーバー（またはZabbixプロキシ）がlibxmlサポート付きでコンパイルされている必要があります。
  
• 名前空間はサポートされていません。
  
• Custom on failチェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかです。 前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

例:

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 functionality を使用して、JSONデータから値またはフラグメントを抽出します。

Custom on fail チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。 前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

CSVからJSONへ

CSVファイルのデータをJSON形式に変換します。

詳細については、CSVからJSONへの前処理を参照してください。

XMLからJSONへ

XML形式のデータをJSONに変換します。

詳細については、シリアライズルールを参照してください。

Custom on failチェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定することが可能です。 前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

SNMP walk値

指定したOID/MIB名で値を抽出し、書式設定オプションを適用します:

• Unchanged - 16進文字列をエスケープされていない16進文字列として返します（注意: 表示ヒントは引き続き適用されます）。
  
• UTF-8 from hex-STRING - 16進文字列をUTF-8文字列に変換します。
  
• MAC from hex-STRING - 16進文字列がMACアドレスとして正しいか検証し、適切なMACアドレス文字列として返します（' ' は ':' に置き換えられます）。
  
• Integer from BITS - 16進文字の並びで表現されたビット文字列（例: "1A 2B 3C 4D"）の先頭8バイトを、64ビット符号なし整数に変換します。 8バイトを超えるビット文字列では、それ以降のバイトは無視されます。

Custom on failチェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。 前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、そのアイテムは未サポートにはなりません。

SNMP walkからJSONへ

SNMP値をJSONに変換します。

JSON内のフィールド名と、それに対応するSNMP OIDパスを指定します。 フィールド値には、指定したSNMP OIDパス内の値が設定されます。

コメント:

• SNMP walk value ステップと同様の値のフォーマットオプションを利用できます。
  
• この前処理ステップは、SNMP OID discovery に使用できます。
  
• Custom on fail チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。 前処理ステップが失敗した場合でも、値を破棄する、または指定した値を設定するオプションが選択されていれば、そのアイテムは未サポートにはなりません。

SNMP取得値

SNMP取得値に書式設定オプションを適用します。

• Hex-STRINGからUTF-8 - hex-stringをUTF-8文字列に変換します。
  
• Hex-STRINGからMAC - hex-stringがMACアドレスとして有効か検証し、適切なMACアドレス文字列を返します（' ' は ':' に置き換えられます）。
  
• BITSから整数 - 16進文字の並びで表現されたビット文字列（例: "1A 2B 3C 4D"）の先頭8バイトを、64ビット符号なし整数に変換します。 8バイトを超えるビット文字列では、それ以降のバイトは無視されます。

Custom on failチェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。 前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

カスタム乗数

値を、指定した整数値または浮動小数点値で乗算します。

コメント:

• このオプションを使用すると、KB、MBps などで受信した値を B、Bps に変換できます。 そうしないと、Zabbix はprefixes（K、M、G など）を正しく設定できません。
  
• アイテムの情報の型が Numeric (unsigned) の場合、小数部を含む受信値はカスタム乗数が適用される前に切り捨てられることに注意してください（つまり、'0.9' は '0' になります）。
  
• 情報の型が Numeric (unsigned) に設定されているアイテムで、カスタム乗数を使用するか、保存する値として Change per second を使用し、その結果として計算値が実際には浮動小数点数になる場合でも、計算値は小数部を切り捨てて整数として保存されることで、正しい値として受け入れられます。
  
• サポート対象: たとえば 1e+70 のような科学表記、ユーザーマクロおよび LLD マクロ、ならびに {#MACRO}e+10、{$MACRO1}e+{$MACRO2} のようにマクロを含む文字列。 マクロは整数または浮動小数点数に解決される必要があります。
• Custom on fail チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかです。 前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、そのアイテムは未サポートにはなりません。

単純な変化量

現在の値と前回の値の差を計算します。

コメント:

• このステップは、継続的に増加する値の測定に役立ちます。
  
• value-prev_value として評価されます。ここで、value は現在の値、prev_value は前回受信した値です。
  
• 1つのアイテムにつき、変更操作（「単純な変化量」または「1秒あたりの変化量」）は1つだけ許可されます。
• 現在の値が前回の値より小さい場合、Zabbix はその差を破棄し（何も保存せず）、次の値を待ちます。
  
• Custom on fail チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。
  前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

1秒あたりの変化量

値の変化量（現在の値と前回の値の差）の1秒あたりの速度を計算します。

コメント:

• このステップは、継続的に増加する値の1秒あたりの速度を計算するのに便利です。
  
• この計算では浮動小数点数が生成される可能性があるため、受信する生の値が整数であっても、'Type of information' は Numeric (float) に設定することを推奨します。 これは、小数部分が重要になる小さな数値で特に重要です。 一方、浮動小数点値が大きく、'float' フィールド長を超えて値全体が失われる可能性がある場合は、Numeric (unsigned) を使用し、小数部分のみを切り捨てることを推奨します。
  
• (value-prev_value)/(time-prev_time) として評価されます。ここで、value は現在の値、prev_value は前回受信した値、time は現在のタイムスタンプ、prev_time は前回の値のタイムスタンプです。
  
• 1つのアイテムにつき、変更操作（"Simple change" または "Change per second"）は1つだけ使用できます。
• 現在の値が前回の値より小さい場合、Zabbix はその差分を破棄し（何も保存せず）、次の値を待ちます。 これは、たとえば32ビットSNMPカウンターのラップアラウンド（オーバーフロー）に対して正しく動作させるのに役立ちます。
  
• Custom on fail チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかです。 前処理ステップが失敗した場合でも、値を破棄する、または指定した値を設定するオプションが選択されていれば、そのアイテムは未サポートにはなりません。

ブール値を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 と見なされます。
  
• Custom on fail チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。
  前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

8進数から10進数へ

値を8進数形式から10進数に変換します。

失敗時のカスタム処理チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。 前処理のステップが失敗した場合でも、値を破棄する、または指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

16進数から10進数へ

値を16進数形式から10進数に変換します。

失敗時のカスタムチェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。 前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

JavaScript

パラメーターフィールド内、またはその横にある鉛筆アイコンをクリックすると開くモーダルエディターに、JavaScriptコードを入力します。

コメント:

• 使用可能なJavaScriptの長さは、使用しているデータベース によって異なります。
  
• 詳細については、JavaScriptによる前処理 を参照してください。

範囲内

最小値/最大値（両端を含む）を指定して、値が入るべき範囲を定義します。

コメント:

• 数値を使用できます（桁数は任意、小数部は任意、指数部は任意、負の値も可）。
  
• 最小値は最大値より小さくなければなりません。
  
• 少なくとも1つの値が存在している必要があります。
  
• ユーザーマクロおよびローレベルディスカバリマクロを使用できます。
  
• Custom on fail チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。

前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、そのアイテムは未サポートにはなりません。

正規表現に一致

値が一致しなければならない正規表現を指定します。

Custom on failチェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。 前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、そのアイテムは未サポートにはなりません。

正規表現 {#doesnotmatchregexp} に一致しない

値が一致してはならない正規表現を指定します。

失敗時のカスタムチェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。 前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

JSON内のエラーをチェック

JSONPath にあるアプリケーションレベルのエラーメッセージをチェックします。 成功し、かつメッセージが空でない場合は処理を停止します。それ以外の場合は、この前処理ステップの前の値を使用して処理を続行します。

コメント:

• これらの外部サービスエラーは、前処理ステップの情報を追加せずに、そのままユーザーに報告されます。
  
• 無効なJSONの解析に失敗した場合、エラーは報告されません。
  
• Custom on fail チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。 前処理ステップが失敗した場合でも、値を破棄する、または指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

XML内のエラーを確認

XPath にあるアプリケーションレベルのエラーメッセージを確認します。 成功し、かつメッセージが空でない場合は処理を停止します。それ以外の場合は、この前処理ステップの前の値で処理を続行します。

コメント:

• これらの外部サービスエラーは、前処理ステップの情報を追加せずに、そのままユーザーに報告されます。
  
• 無効な XML の解析に失敗した場合、エラーは報告されません。
  
• Custom on fail チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。 前処理ステップが失敗した場合でも、値を破棄する、または指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

正規表現を使用したエラーチェック

正規表現を使用して、アプリケーションレベルのエラーメッセージをチェックします。
成功し、かつメッセージが空でない場合は処理を停止します。それ以外の場合は、この前処理ステップの前の値で処理を続行します。

パラメータ:

• pattern - 正規表現;
  
• output - 出力書式テンプレート。
  \N（N=1…9）エスケープシーケンスは、N番目に一致したグループに置き換えられます。
  \0 エスケープシーケンスは、一致したテキストに置き換えられます。

コメント:

• これらの外部サービスエラーは、前処理ステップの情報を追加せずに、そのままユーザーに報告されます;
  
• Custom on fail チェックボックスをオンにすると、カスタムのエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかを選択できます。
  前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

未サポートの値をチェック

アイテムの値を取得できなかったかどうかを確認します。
返されたエラーメッセージを調べて、失敗をどのように処理するかを指定します。

パラメータ:

• scope - エラー処理の範囲を選択します:
  any error - 任意のエラー;
  error matches - pattern で指定した正規表現に一致するエラーのみ;
  error does not match - pattern で指定した正規表現に一致しないエラーのみ
  
• pattern - エラーを照合するための正規表現です。
  scope パラメータで any error が選択されている場合、このフィールドは表示されません。
  表示される場合、このフィールドは必須です。
  

コメント:

• 通常、値が存在しない、または値の取得に失敗すると、アイテムは未サポートになります。
  この前処理ステップを使用すると、この動作を変更できます。
  Custom on fail チェックボックスをオンにすると（この前処理ステップでは常にオンかつグレーアウトされています）、カスタムのエラー処理オプションを指定できます。具体的には、値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定することが可能です。
  前処理ステップが失敗した場合でも、値を破棄するオプションまたは指定した値を設定するオプションが選択されていれば、アイテムは未サポートになりません。
• この前処理ステップは、アイテムの値を取得できなかったかどうかのみを確認します。
  たとえば、取得した値の型（例: string）がアイテムの情報の型（例: numeric）と一致するかどうかは確認しません。詳細は Preprocessing examples を参照してください。
  型の不一致がある場合、すべての前処理ステップの実行後にアイテムが未サポートになることがあります。
  型の不一致を確認するには、たとえば Custom multiplier 前処理ステップを使用できます。詳細は Preprocessing examples を参照してください。
• 正規表現のキャプチャグループは、Set value to または Set error to フィールドで使用できます。
  N 番目に一致したグループを取得するには \N（N=1…9）を使用し、一致したテキスト全体を取得するには \0 を使用します。
• これらのステップは常に最初の前処理ステップとして実行され、アイテムへの変更を保存した後は、他のすべてのステップより上に配置されます。
• 複数の Check for not supported value ステップを、指定した順序で使用できます。
  any error 用のステップは、このグループ内の最後のステップとして自動的に配置されます。

未変更の値を破棄

値が変更されていない場合、その値を破棄します。

コメント:

• 値が破棄された場合、その値はデータベースに保存されず、Zabbixサーバーはその値を受信したことを認識しません。 その結果、トリガー条件式は評価されず、関連するトリガーに対して障害の作成/復旧は行われません。 関数は、実際にデータベースに保存されたデータのみに基づいて動作します。 トレンドはデータベース内のデータに基づいて作成されるため、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 フィールド）

テスト

前処理のテストを参照してください。