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

概要

保存前処理を行うことで、受け取った項目の値の変換ルールを定義することができます。
データベースに保存する前に、1つまたは複数の変換を行うことができます。

変換は定義された順番に実行されます。
保存前処理はZabbixサーバまたはプロキシ(プロキシでアイテムを監視している場合)で実行されます。

保存前処理に渡される値はすべて文字列型であり、(アイテムの設定で定義された)目的の値の型への変換は、
保存前処理パイプラインの最後に実行されることに注意してください。
ただし、変換は対応する保存前処理工程で必要とされる場合に行われることもあります。
詳細は保存前処理の詳細をご参照ください。

使用例も併せてご参照ください。

設定

保存前処理のルールは、アイテム設定の保存前処理タブで定義します。

ユーザーマクロおよびユーザーマクロのコンテキストは、アイテム保存前処理のパラメータやJavaScriptのコード内でサポートされています。

アイテムのデータ型パラメータは、少なくとも1つの保存前処理工程が定義されている場合、タブの下部に表示されます。
必要であれば、保存前処理タブを開いたまま情報の種類を変更することができます。
アイテムの作成 を参照してください。

サポートされている変換

サポートされているすべての変換は以下に記載されています。変換名をクリックすると、詳細が表示されます。

変更およびスロットルの前処理ステップでは、必要に応じて新しい値を計算/比較するために、Zabbixは最後の値を記憶しておく必要があることに注意してください。これらの前の値は、前処理マネージャーによって処理されます。 Zabbixサーバーまたはプロキシが再起動された場合、または前処理ステップに変更が加えられた場合、対応する項目の最後の値がリセットされ、以下のようになります。

• 単純な変更、1秒あたりの変更ステップの場合 - 変更を計算するための前の値がないため、次の値は無視されます。
• 変更せずに破棄、ハートビート付きで変更せずに破棄 ステップの場合 - 破棄ルールにより、次の値は破棄されるべきであっても破棄されません。

正規表現

値を正規表現に一致させ、必要な出力に置き換えます。

パラメーター:

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

コメント:

• 入力値と一致しない場合、その項目はサポートされません。
  
• この正規表現は、\N シーケンスを含む最大10個のキャプチャグループの抽出をサポートします。
  
• 失敗時のカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定する、のいずれかです。前処理ステップが失敗した場合、値を破棄するか指定値を設定するオプションが選択されていれば、項目はサポート対象外になりません。
  
• 既存の例については、正規表現セクションを参照してください。

Replace

検索文字列を検索し、別の文字列（または何もない文字列）に置換します。

パラメータ:

• 検索文字列 - 検索および置換する文字列。大文字と小文字が区別されます（必須）
  
• 置換文字列 - 検索文字列を置換する文字列。置換文字列は空でも構いません。空の場合は、検索文字列が見つかった時点で削除できます。

コメント:

• 検索文字列のすべての出現箇所が置換されます。
• エスケープシーケンスを使用して、改行、復帰、タブ、スペースを検索または置換できます（"\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> から '<item><value>10</value></item>' を抽出します。

JSON パス

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

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

CSV から JSON へ変換

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

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

XML から JSON へ変換

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

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

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

SNMP ウォーク値

指定された OID/MIB 名で値を抽出し、フォーマットオプションを適用します。

• 変更なし - 16 進文字列をエスケープされていない 16 進文字列として返します（注 表示ヒントは引き続き適用されます）
  
• 16 進文字列から UTF-8 に変換 - 16 進文字列を UTF-8 文字列に変換します。
  
• 16 進文字列から MAC に変換 - 16 進文字列が MAC アドレスであることを検証し、適切な MAC アドレス文字列を返します（' ' は ':' に置き換えられます）
  
• BITS から整数に変換 - 16 進文字のシーケンス（例: "1A 2B 3C 4D"）として表現されたビット文字列の最初の 8 バイトを 64 ビットの符号なし整数に変換します。8 バイトを超えるビット文字列の場合、後続のバイトは無視されます。

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

SNMP walk to JSON

SNMP値をJSONに変換します。

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

コメント:

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

SNMP get 値

SNMP get 値にフォーマットオプションを適用します。

• 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バイトを超えるビット文字列の場合、後続のバイトは無視されます。

失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定することができます。前処理手順が失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていると、項目はサポートされなくなります。

カスタム乗数

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

コメント:

• このオプションを使用すると、KB、MBps などで受信した値を B、Bps に変換できます。そうでない場合、Zabbixはプレフィックス（K、M、Gなど）を正しく設定できません。
  
• アイテム情報タイプが数値（符号なし）の場合、小数部を含む入力値は、カスタム乗数が適用される前に切り捨てられます（例：0.9は0になります）
  
• アイテム情報タイプが数値（符号なし）に設定されている場合に、カスタム乗数を使用したり、値を秒あたりの変化として保存したりして、計算結果が実際には浮動小数点数になった場合でも、小数部を切り捨てて整数として保存することで、計算値は正しいものとして受け入れられます。
  
• サポート対象：科学的記数法（例：1e+70）、ユーザーマクロ、LLDマクロ。マクロを含む文字列（例：{#MACRO}e+10、{$MACRO1}e+{$MACRO2}）マクロは整数または浮動小数点数に解決される必要があります。
• 失敗時にカスタムチェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定値を設定する、または指定エラーメッセージを設定する、のいずれかを選択できます。前処理ステップが失敗した場合、値を破棄するか指定値を設定するオプションが選択されていれば、項目はサポート対象外になりません。

単純な変更

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

コメント:

• このステップは、常に増加する値を測定する場合に便利です。
  
• value-prev_value として評価されます。ここで、value は現在の値、prev_value は前回受信した値です。
  
• アイテムごとに変更操作（"単純な変更"または"1秒あたりの変更"）は1回のみ許可されます。
• 現在の値が前回の値より小さい場合、Zabbixはその差を破棄（何も保存せず）し、次の値を待機します。
  
• 失敗時のカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、特定の値を設定する、または特定のエラーメッセージを設定するオプションです。前処理ステップが失敗した場合、値を破棄するか特定の値を設定するオプションが選択されていれば、アイテムはサポート対象外になりません。

1秒あたりの変化

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

コメント:

• この手順は、常に増加する値の1秒あたりの速度を計算するのに役立ちます。
  
• この計算では浮動小数点数が生成される可能性があるため、入力される生の値が整数であっても、"情報の種類"を数値（float）に設定することをお勧めします。これは、小数点部分が重要となる小さな数値の場合に特に重要です。浮動小数点値が大きく、floatフィールドの長さを超える可能性があり、値全体が失われる可能性がある場合は、実際には数値（符号なし）を使用して小数点部分のみを切り捨てることをお勧めします。
  
• (value-prev_value)/(time-prev_time) として評価されます。ここで、value は現在の値、prev_value は前回受信した値です。 time - 現在のタイムスタンプ。prev_time - 前回の値のタイムスタンプ。
  
• アイテムごとに変更操作（"単純な変更"または"1秒あたりの変更"）は1回のみ許可されます。
• 現在の値が前回の値より小さい場合、Zabbixはその差を破棄（何も保存せず）し、次の値を待機します。これは、例えば32ビットSNMPカウンターのラップ（オーバーフロー）を正しく処理するのに役立ちます。
  
• *"失敗時にカスタム"チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定値を設定する、または指定エラーメッセージを設定する、のいずれかです。前処理ステップが失敗した場合、値を破棄するか指定値を設定するオプションが選択されていれば、アイテムはサポート対象外になりません。

ブール値を小数点に変換

値をブール値形式から小数点形式に変換します。

コメント:

• テキスト表現は 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、available、err、slave です。さらに、0 以外の数値はすべて TRUE とみなされ、0 は FALSE とみなされます。
  
• 失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定することができます。前処理手順が失敗した場合、値を破棄するか指定された値を設定するオプションが選択されていると、項目はサポート対象外になりません。

8進数から10進数へ

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

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

16進数から10進数へ

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

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

JavaScript

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

コメント:

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

範囲内

最小値/最大値（両端を含む）を指定して、値の範囲を定義します。

コメント:

• 数値（任意の桁数、小数部と指数部（オプション）、負の値を含む）が使用できます。
  
• 最小値は最大値より小さくする必要があります。
  
• 少なくとも1つの値が存在する必要があります。
  
• ユーザーマクロと低レベル検出マクロを使用できます。
  
• 失敗時にカスタム チェックボックスをオンにすると、カスタムエラー処理オプションを指定できます。値を破棄する、指定値を設定する、または指定エラーメッセージを設定する、のいずれかです。前処理ステップが失敗した場合、値を破棄するか指定値を設定するオプションが選択されていると、アイテムはサポート対象外になりません。

正規表現に一致

値が一致する必要がある正規表現を指定します。

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

正規表現に一致しません

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

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

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 を選択した場合、このフィールドは表示されません。表示される場合は、必須です。
  

コメント:

• 通常、値の取得が存在しない、または失敗すると、そのアイテムはサポート対象外になります。この前処理手順により、この動作を変更できます。 失敗時にカスタムチェックボックスをオンにすると（この前処理ステップでは常にオンになり、グレー表示されます）、カスタムエラー処理オプションを指定できます。値を破棄する、指定した値を設定する、指定したエラーメッセージを設定する、のいずれかです。前処理ステップが失敗した場合、値を破棄するか指定した値を設定するオプションが選択されていると、アイテムはサポート対象外になりません。
• この前処理ステップは、アイテム値が取得できなかったかどうかのみをチェックします。たとえば、取得された値の型（例：文字列）がアイテムの情報の型（例：数値）と一致するかどうかはチェックしません。詳細については、前処理の例を参照してください。型の不一致がある場合、すべての前処理ステップを実行した後でも、アイテムはサポート対象外になる可能性があります。型の不一致をチェックするには、たとえばカスタム乗数前処理ステップを使用できます。 前処理の例を参照してください。
• 正規表現グループの取得は、値の設定 フィールドまたは エラーの設定 フィールドでサポートされています。N番目に一致したグループを取得するには\N（N=1…9）を使用します。一致したテキストを取得するには\0を使用します。
• これらのステップは常に最初の前処理ステップとして実行され、アイテムへの変更を保存した後、他のすべてのステップよりも優先されます。
• 複数のサポートされていない値の確認 ステップを、指定された順序でサポートしています。エラーのステップは、このグループの最後のステップとして自動的に配置されます。

変更されていない値を破棄

変更されていない値を破棄します。

コメント:

• 値が破棄された場合、その値はデータベースに保存されず、Zabbixサーバーはこの値が受信されたことを認識しません。トリガー式は評価されず、結果として、関連するトリガーに関する問題は発生/解決されません。関数は、データベースに実際に保存されたデータに基づいてのみ動作します。トレンドはデータベースのデータに基づいて構築されるため、1時間にわたって値が保存されていない場合、その時間のトレンドデータも存在しません。
  
• アイテムごとに指定できるスロットリングオプションは1つだけです。

ハートビート付きで変更なし破棄

定義された時間（秒）内に値が変更されなかった場合、その値を破棄します。

コメント:

• 秒数を指定するために正の整数値がサポートされています（最小値は1秒）
  
• 時間の接尾辞を使用できます（例：30s、1m、2h、1d）
  
• ユーザーマクロと低レベル検出マクロを使用できます。
  
• 値が破棄された場合、その値はデータベースに保存されず、Zabbixサーバーはその値が受信されたことを認識しません。トリガー式は評価されないため、関連するトリガーに問題が発生/解決されることはありません。関数は、データベースに実際に保存されたデータに基づいてのみ動作します。トレンドはデータベース内のデータに基づいて構築されるため、1 時間にわたって値が保存されていない場合は、その時間のトレンドデータも存在しません。
  
• アイテムごとに指定できるスロットルオプションは 1 つだけです。

Prometheus パターン

以下のクエリを使用して、Prometheus メトリックから必要なデータを抽出します。

詳細については、Prometheus チェック を参照してください。

Prometheus から JSON へ変換

必要な Prometheus メトリクスを JSON に変換します。

詳細については、Prometheus チェック を参照してください。

マクロのサポート

ユーザーマクロ およびコンテキスト付きユーザーマクロは、以下の環境でサポートされています。

• JavaScript コードを含む、前処理ステップのパラメータ
• カスタムエラー処理パラメータ (値の設定先 および エラーの設定先 フィールド)

Testing

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