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

概要

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

この機能は、以下のようなさまざまなユースケースをサポートします。

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

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

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

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

参考: 前処理の例

設定

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

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

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

サポートされている変換

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

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

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

正規表現

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

パラメータ:

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

コメント:

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

{#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 to JSON

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

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

XML to JSON

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

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

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

SNMP walk値

指定された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 value

SNMP get値に書式設定オプションを適用します:

• UTF-8 from Hex-STRING - 16進文字列をUTF-8文字列に変換します;
  
• MAC from Hex-STRING - 16進文字列をMACアドレスとして検証し、適切なMACアドレス文字列を返します（' 'は':'に置換されます）;
  
• Integer from BITS - 16進文字列で表現されたビット文字列の最初の8バイト（例: "1A 2B 3C 4D"）を64ビットの符号なし整数に変換します。 8バイトを超えるビット文字列の場合、以降のバイトは無視されます。

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

カスタム乗数

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

コメント:

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

単純な変化

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

コメント:

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

秒あたりの変化量

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

コメント:

• このステップは、常に増加する値の秒あたりの速度を計算するのに便利です。
  
• この計算は浮動小数点数を生成する場合があるため、受信する生の値が整数であっても「情報の型」を数値（浮動小数点）に設定することを推奨します。 特に小さな数値で小数点以下の値が重要な場合に該当します。 浮動小数点値が大きくなり、「float」フィールドの長さを超える可能性がある場合（この場合、値全体が失われる可能性があります）、数値（整数）を使用して小数点以下のみを切り捨てることを推奨します。
  
• (value-prev_value)/(time-prev_time)として評価されます。ここで、valueは現在値、prev_valueは前回受信値、timeは現在のタイムスタンプ、prev_timeは前回値のタイムスタンプです。
  
• アイテムごとに許可される変化演算は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 です。 さらに、ゼロ以外の数値はTRUEと見なされ、ゼロはFALSEと見なされます。
  
• 失敗時にカスタム値を使用 チェックボックスをマークすると、値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定するなど、カスタムのエラー処理オプションを指定できます。 前処理ステップが失敗した場合でも、値を破棄するか指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

8進数から10進数

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

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

16進数から10進数

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

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

JavaScript

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

コメント:

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

範囲内

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

コメント:

• 数値が受け入れられます（任意の桁数、小数部の有無、指数部の有無、負の値を含む）；
  
• 最小値は最大値より小さくなければなりません；
  
• 少なくとも1つの値が必要です；
  
• ユーザーマクロおよびローレベルディスカバリーマクロが使用できます；
  
• 失敗時にカスタム チェックボックスをマークすると、値を破棄する、指定した値を設定する、または指定したエラーメッセージを設定するなど、カスタムのエラー処理オプションを指定できます。 前処理ステップが失敗した場合、値を破棄するか指定した値を設定するオプションが選択されていれば、アイテムは未サポートにはなりません。

正規表現 {#matchesregexp} に一致

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

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

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

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

失敗時にカスタム チェックボックスをマークすると、カスタムエラー処理オプション（値の破棄、指定値の設定、指定エラーメッセージの設定）が可能です。 前処理ステップが失敗した場合、値の破棄または指定値の設定オプションが選択されていれば、アイテムは「利用不可」にはなりません。

JSONのエラーをチェック

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

コメント:

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

XMLのエラーをチェック

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

コメント:

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

正規表現 {#errorbyregexp} を使用したエラーのチェック

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

パラメータ:

• 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チェックボックスをマークすると（この前処理ステップでは常にマークされグレーアウトされています）、カスタムのエラー処理オプション（値を破棄する、指定した値を設定する、指定したエラーメッセージを設定する）を指定できます。 前処理ステップが失敗した場合でも、値を破棄するか指定した値を設定するオプションが選択されていれば、アイテムはサポートされていない状態にはなりません。
• この前処理ステップは、アイテム値が取得できない場合のみをチェックします。 例えば、取得した値の型（例: 文字列）がアイテムの情報の型（例: 数値）と一致するかどうかはチェックしません。詳細は前処理の例を参照してください。 型が一致しない場合、すべての前処理ステップが実行された後でもアイテムがサポートされていない状態になることがあります。 型の不一致をチェックするには、例えばCustom multiplier前処理ステップを使用できます。前処理の例を参照してください。
• Set value toまたはSet error toフィールドでは、正規表現グループのキャプチャがサポートされています。 \N（N=1…9）を使用してN番目の一致グループを取得できます。\0を使用して一致したテキストを取得できます。
• これらのステップは常に最初の前処理ステップとして実行され、アイテムへの変更を保存した後、他のすべての前処理ステップの上に配置されます。
• 複数のサポートされていない値のチェックステップが、指定した順序でサポートされています。 any errorのステップは、このグループの最後のステップとして自動的に配置されます。

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

値が変更されていない場合は破棄します。

コメント:

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

ハートビートで変更されていない値を破棄

定義された期間（秒単位）内に値が変更されていない場合、その値を破棄します。

コメント:

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

Prometheusパターン

Prometheusメトリクスから必要なデータを抽出するには、次のクエリを使用します。

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

Prometheus to JSON

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

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

マクロのサポート

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

• 前処理ステップのパラメータ（JavaScriptコードを含む）
• カスタムエラーハンドリングパラメータ（値を設定およびエラーを設定フィールド）

テスト

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