スパン・エンリッチメント
スパン・エンリッチメントについて
- ユーザーにカスタム属性でスパンをエンリッチしたり、既存の属性でデータを結合または削除する機能を提供します。
- エンリッチメント操作は、特定のスパンで特定の順序で適用される1つ以上のアクションを含むスパン・ルールによって定義されます。
- スパン・ルールには、カスタムとOracle提供の2つのタイプがあります。
- スパン・エンリッチメントはAPMドメイン・レベルで構成されます。
- 個人識別可能情報(PII)のスパンからの削除。
- 複数の属性のデータを1つの属性に結合します。
- 属性からデータを抽出します。たとえば、長いURLからの部分パスなどです。
- データに数学関数を適用します。たとえば、単位を秒からミリ秒に変換します。
- 属性値を新しい値にマップします。たとえば、値'1'を色'blue'、値'2'を色'red'にマップします。
- 数値をバケットに配分します。たとえば、コールド・バケット、ウォーム・バケットおよびホット・バケットにマップされる温度値の範囲です。
スパン・エンリッチメント使用
スパン・エンリッチメントは、スパンで動作し、スパンの属性を変更するために使用するスパン・ルールを介して構成されます。スパン・ルール・ツールボックスには、ルールの一部として実行できる様々な処理が用意されています。
スパン・ルールはグループ内で管理されます。グループは、指定された順序で適用されるルールの集合です。各ルールはスパンに1つ以上のアクションを適用でき、各ルールの出力をフォローアップ・ルールの入力として使用できます。ルール・グループには、ルールを適用するスパンを選択するために使用されるスパン・フィルタが必要です。
複数のグループを定義できます。これは、特定の目的のために設計された機能を備えた論理エンティティを作成するため、様々なタイプのスパンに対して様々なタイプのルールを保守する必要がある場合に役立ちます。これにより、ルール・セットの全体的な複雑さが軽減されます。
複数のグループに同じスパンと一致するスパン・フィルタが設定されている場合、それらのすべてのグループがルールをそのスパンに適用します。これを実行する順序は、グループ名のアルファベット順によって決まります。グループに名前を付けるか、名前を変更する場合は、この点に注意してください。Oracleでは、グループ名がアルファベット順にソートされないように、名前の先頭に数字を付けることをお薦めします。たとえば、「1」です。事業所データの削除、2。長さの単位を変換します。
複数のグループが同じスパンで動作している場合、これは、各グループがチェーン内の前のグループによって変更された可能性のあるスパンのバージョンで動作することを意味します。これは、前のグループによって作成された変更に依存するルールをフォローアップ・グループに記述できるため便利です。一方、ルールが依存する属性、以前のグループによって削除または変更された場合も、フォローアップ・ルールが失敗することがあります。
上記は、スパンが複数のグループに一致する場合にのみ重要です。
グループに明らかに重複しないフィルタがある場合、スパンは常に単一のグループによって変更され、前述の考慮事項は無関係になります。
スパン・イベントの属性
スパンには、ログ・メッセージとも呼ばれるイベントのリストを含めることができます。これらは通常、スパンの実行中に重要な瞬間に関する情報を格納するために使用されます。たとえば、スパンがデータベース問合せを記述する場合、接続がオープンされた時点、問合せリクエストが実際に発行された時点およびレスポンスが受信された時点を示すイベントを生成できます。
イベントは、name、timestampおよび記録された情報の詳細なコンテキストを提供する一連のattributes (キーと値のペア)によって識別されます。
event reference構文を使用して適切なイベント属性を識別する必要があります。event['NameOfEvent']:'NameOfAttribute'.イベント属性はスパン・フィルタとして使用できません。
スパン・ルールの作成および管理
レポートのニーズに応じて、スパン・ルールを作成および管理できます。
-
「APMドメイン」ページに移動し、目的のAPMドメインをクリックします。
ドメインの詳細ページが表示されます。
-
左下にある「リソース」に移動し、「スパン・エンリッチメント」をクリックします。
「スパン・エンリッチメント」ペインが表示されます。
-
新しいスパン・ルール・グループを作成するには、「グループの作成」をクリックします。
「スパン・ルール・グループの作成」ペインが表示されます。- 新しいグループの名前を入力します。
- このグループで使用するスパン・フィルタを選択します。
- オプションで、新しいグループの「説明」を指定します。
- 「次」をクリックして「ルール・アクション」ペインに進み、スパン・ルール・タイプ(「カスタム・スパン・ルール」またはOracle提供のスパン・ルール)に応じてスパン・ルールを新しいグループに追加します。
- 「ルール名」を入力します。
- オプションで、「ルール・スパン・フィルタ」を選択して、ルールの操作のスコープをさらに絞り込みます。
- オプションで、ルールの説明を入力します。
- スパン・ルール・タイプを選択します。
-
「Oracle提供のスパン・ルール」を選択すると、選択するルールのリストが表示されます。
ユーザーを支援するために、ルールはOracleによってすでに作成されています。リストには次のものが含まれます。
- スパンにクライアントIPアドレスを追加します。
クライアントIPアドレスを
ClientIPという属性としてスパンに追加します。 - EBSスイート。
E-Business Suiteテンプレートを提供します。
- OpenTelemetryからAPMへのネーミング変換。
スパン属性名をOpenTelemetryネーミング規則からAPMネーミング規則に変換します。APMでのOpenTelemetryの使用の詳細は、OpenTelemetryデータ・ソースの構成を参照してください。
リストからルールをクリックして、グループに追加します。
ノート
アクションはルール自体で内部的に管理されるため、構成できません。また、Oracle提供のルールに対するアクションは表示できません。 - スパンにクライアントIPアドレスを追加します。
- 「カスタム・スパン・ルール」の作成を選択した場合は、それに対して1つ以上のアクションを定義する必要があります。(ルールには常に少なくとも1つのアクションが含まれます)。
「アクション」を選択する前に、「アクション・ターゲット」および「アクション・タイプ」を選択する必要があります。
- アクション・ターゲットは、アクションが動作するスパンの一部を指定します。次の2つのターゲットを使用できます。
- エンティティ: スパン全体をターゲットにします。
- 属性: 単一の属性をターゲット指定します。
- 「処理タイプ」でタイプを指定します。これは主に、アクションを論理的にグループ化するために使用されます。たとえば、文字列または数値です。
- 次に、「使用可能なアクション」ドロップダウンから適切なアクションを選択します。
アクションには様々なコンテキストがあるため、ウィンドウはアクション・タイプごとに適宜変更されます。アクションの詳細については、Working with Actionsを参照してください。
アクション・ターゲットおよびアクション・タイプで使用可能なアクションの詳細は、使用可能なアクションを参照してください。
-
「アクションの追加」ボタンを使用して、ルールにアクションを追加します。
-
各「アクション」の右上にあるアクション・アイテム・メニューを使用して、ルール順序で上下に移動するか、アクションを削除します。
- アクション・ターゲットは、アクションが動作するスパンの一部を指定します。次の2つのターゲットを使用できます。
-
アクションの使用
ターゲットが「属性」であるアクションでは、常に、値がアクションへの入力として使用される属性の名前を指定する必要があります。各アクションの構成ウィンドウは、Input Attributeと呼ばれます。
一部のアクションでは、操作の結果を格納する属性の名前を指定する必要もあります。これは、Output Attributeと呼ばれます。属性がスパンに存在する場合、その時点の値はすべて処理の結果によって上書きされます。まだ存在しない場合は、新しい値でスパンに追加されます。このメカニズムを使用すると、スパン(入力属性も含む)の属性の値をアクションの操作の結果で置き換えることができます。
これを使用して、アクションの結果をフォローアップ・アクション(または同じルール・グループ内のルール)に挿入できます。
また、これを使用して、フォローアップのルールやアクションで使用できるが、最終結果の一部として保持する必要のない一時的な属性に値を格納することもできます。「属性の削除」アクションを使用して、最後のステップとして一時属性を削除してください。
ブロック・アクションはスパンを拒否し、別のルール・グループからも後で使用できません。
使用可能なアクション
| 処理ターゲット | 処理タイプ | 使用可能なアクション |
|---|---|---|
| エンティティ |
パススルー スパン全体を渡すかブロックするかを制御する処理。 ブロックされたスパンが処理パイプラインから拒否されます。却下されたスパンはAPMによって処理されなくなり、どこにも格納されず、後で他のAPMツールやダッシュボードで表示できなくなります。 |
ブロック: これを無条件にブロックします。フォローアップ・アクションおよびルールは適用されず、スパンはAPM OCIツールおよび製品で使用できなくなります。 サンプル: サンプル・パーセントに基づくサンプル(受入)スパン。たとえば、25%のサンプル・パーセントは(ランダムに)すべてのスパンの25%を受け入れ、残りをブロックします。ここでブロックされたスパンは、ブロック・アクションによってブロックされたスパンと同様に処理されます。 |
| 属性 |
文字列 文字列である属性の値に対する様々な操作を許可するアクション。たとえば、大/小文字の変更、値の置換、文字列の一部の抽出などです。 |
追加: オプションのセパレータ文字列を使用して、属性の値に静的文字列を追加します。 連結: 2つの属性値を連結します。値を結合するオプションのセパレータ文字列を指定できます。結果は新しい属性として返されます。 抽出: 正規表現に基づいて属性値の一部を抽出します。結果は新しい属性として返されます。 正規表現には、取得する文字列の部分を識別する取得グループ演算子が含まれている必要があります。正規表現が一致しない場合、または取得グループがない場合、アクションによって出力は生成されません。オプションでフォールバック値を指定できます。これは、抽出自体が結果を生成しなかった場合にアクションの出力として使用されます。 小文字: 属性の値を小文字に変換します。 検索および置換: 正規表現を使用して、属性値の1つ以上の部分を置換します。修正された文字列が新しい属性として返されます。 正規表現には1つの取得グループを含めることができます。取得グループがない場合は、式の一致内容がすべて置換されます。取得グループが存在する場合、グループに取得されたコンテンツのみが置換されます。オプションの一致発生は、特定の一致の発生のみを置換する必要がある場合に使用できます。これが設定されていないか、0に設定されている場合、一致したすべてのオカレンスが置換されます。これはデフォルトの動作です。 切捨て: 属性の値から前後の空白を切捨てます。 大文字: 属性の値を大文字に変換します。 |
| 属性 |
数値 属性値に対して様々な数学演算を許可する処理(数値の場合)。数値処理では、属性値の文字列として表される実際の数値と数値の両方がサポートされます。次の2つは同等です。
数値アクションは、操作で使用する値を持つ属性の名前を表す文字列、または計算で直接使用される数値を入力として実行できます。
すべての数値処理には、出力値に端数処理を適用できるオプションがあります。端数処理は次のいずれかです。
|
絶対: 入力パラメータの絶対値を返します。 追加: 2つの値を合計します。 バケット化: 数値属性値をバケット名にマップします。属性値がバケットの範囲内にある場合、バケット名が返されます。一致するバケットがない場合は、フォールバック値が返されます。 除算: 最初の値を2番目の値で除算します。2番目の値が0の場合、結果は0になります。 最大: 2つの最大値を返します。 最小: 2つの値の最小を返します。 乗算: 2つの値を乗算します。 否定: 値の否定(符号の変更)を行います。 減算: 最初の属性から2番目の属性を減算します。 |
| 属性 |
汎用 汎用アクションは、スパンの属性の削除など、属性レベルの操作を提供します。 |
マップ属性値: 属性の値を取得し、新しい値にマップします。 属性の削除: スパンから属性を削除します。属性がイベント名参照 属性の名前変更: 属性の名前を変更します。 属性の設定: 属性を静的値に設定します。属性が存在しない場合は追加され、存在しない場合は新しい値が割り当てられ、既存の値が上書きされます。 |
アクション構成の例
この項では、個々のアクションに必要な構成ステップの例を示します。- バケット化の例:
このアクションでは、ミニエディタを使用して、バケット数とそのしきい値を設定します。右側のコントロールを使用して、バケットを作成、更新および削除できます。
バケットは、しきい値に基づいて自動的に順序付けされます。値が最後のバケットに対して大きすぎる場合、フォールバック値が使用されます。次の図は、5つのバケットとフォールバック値を持つ例を示しています。
- マップの例:
このアクションは、ミニエディタを使用して、入力/出力値のペアのマップを設定します。どちらの値も数値または文字列です。右側のコントロールを使用して、マッピングを作成、更新または削除します。
「エクスポート」ボタンを使用すると、ファイルへのマッピング(CSV形式)をコンピュータにダウンロードできます。「インポート」ボタンを使用すると、コンピュータのCSVファイルからマッピングを移入できます。これは、マッピングが多数ある場合に特に便利です。
スパン・エンリッチメント・ルール検証
スパン・エンリッチメント構成は、記述が複雑になる可能性があり、ルールまたはルール・グループが予想どおりに機能するかどうかを事前に把握することが困難な場合があります。これを支援するために、スパン・エンリッチメント構成エディタには、保存する前にサンプル・スパンでルールまたはルール・グループをテストするオプションが用意されています。
- グループを選択し、「編集」をクリックして「スパン・ルール・グループの編集」パネルを開きます。別の方法として、新しいグループを作成し、「編集」パネルが表示されます。
- 「ルール・アクションの構成」ステップをクリックします。
- 「テスト」をクリックして、ルール・グループ全体をテストします。または、個々のルールをテストするには、ルールを選択して「テスト・ルール」をクリックします。
ノート
テスト・ルールは、ルール・グループにルールが1つのみ含まれている場合は使用できません。 - 「テスト・スパン・ルール・グループ」パネルが表示されます。
テストするルールが横にチェックボックス付きで表示されます。必要に応じて切り替えることができます。
- 「スパン・サンプル」テキスト・ボックスにサンプル・スパンを入力します。
- 「テスト・スパン」をクリックして、指定したスパンで選択したルールのテストを実行します。
図9-1スパン・エンリッチメント・ルールの検証
テスト実行では、スパンが構成済スパン・フィルタと一致するかどうかがレポートされます。
フィルタが一致する場合は、ルールがスパンに適用され、結果の差異(ある場合)が次の表に表示されます。ルールの結果として追加された属性は、緑色で強調表示されます。削除された属性は赤で強調表示されます。変更された属性は黄色で強調表示されます。
トレース・エクスプローラ: トラフィックからスパンの正確なサンプルを取得するには、右上にある「トレース・エクスプローラ」をクリックしてトレース・エクスプローラを開き、処理された実際のスパンを確認します。スパンを選択し、右側のコンテキスト・メニュー(縦に並んだ3つのドット)を開き、「ルート・スパン・データのコピー」をクリックします。
スパンの内容を含むポップアップが表示されます。スパン・データをコピーし、テスト中に使用できます。
もう1つのオプションは、トレース・エクスプローラでレポートされたスパン形式に準拠しているかぎり、独自のスパンを貼り付けるか、手動で入力することです。
スパン・プロパティ・エイリアス
スパン・エンリッチメントまたはスパン・フィルタ機能で使用すると、実際のスパン・プロパティが別の名前で参照されることはほとんどありません。視覚的な違い以外は、ルールとフィルタの設定方法には影響しません。たとえば、指定したプロパティを参照するときは、常に別名を使用する必要があります。
現在別名を持つプロパティは次のとおりです。
| スパン・プロパティ | スパン・エンリッチメント別名 | 備考 |
|---|---|---|
td-micros |
SpanDuration |
td-microsはマイクロ秒、SpanDurationはミリ秒です。時間単位の変換は、スパン・エンリッチメントおよびスパン・フィルタによって自動的に適用されます。
|
name |
OperationName |
スパンの名前は、実行された操作を表します。 |
ts-micros |
StartTime |
ts-microsはマイクロ秒、StartTimeはミリ秒です。時間単位の変換は、スパン・エンリッチメントおよびスパン・フィルタによって自動的に適用されます。
|
id |
SpanId |
|
parent-id |
ParentId |
|
trace-id |
TraceId |