プローブ(API)
汎用プローブ REST API
以下の情報は、Apstra APIの規約にすでに精通している人のためにIBAを使用する方法を理解するために必要なAPIの量を示しています。正式なAPIドキュメントは、APIドキュメント自体のために予約されています。
はじめに説明したワークフローの例で使用されているAPIについて説明し、その一般的な機能を具体的な例で示します。
プローブを作成
プローブを作成するには、次のフォームを使用してオペレータの POS を /api/blueprints/<blueprint_id>/probes 入力します。
{
"label": "server_tx_bytes",
"description": "Server traffic imbalance",
"tags": ["server", "imbalance"],
"disabled": false,
"processors": [
{
"name": "server_tx_bytes",
"outputs": {
"out": "server_tx_bytes_output"
},
"properties": {
"counter_type": "tx_bytes",
"graph_query": "node('system', name='sys').out('hosted_interfaces').node('interface', name='intf').out('link').node('link', link_type='ethernet', speed=not_none()).in_('link').node('interface', name='dst_intf').in_('hosted_interfaces').node('system', name='dst_node', role='server').ensure_different('intf', 'dst_intf')",
"interface": "intf.if_name",
"system_id": "sys.system_id"
},
"type": "if_counter"
},
{
"inputs": {
"in": "server_tx_bytes_output"
},
"name": "std",
"outputs": {
"out": "std_dev_output"
},
"properties": {
"ddof": 0,
"group_by": []
},
"type": "std_dev"
},
{
"inputs": {
"in": "std_dev_output"
},
"name": "server_imbalance",
"outputs": {
"out": "std_dev_output_in_range"
},
"properties": {
"range": {
"max": 100
}
},
"type": "range_check"
},
{
"inputs": {
"in": "std_dev_output_in_range"
},
"name": "server_imbalance_anomaly",
"outputs": {
"out": "server_traffic_imbalanced"
},
"type": "anomaly"
}
],
"stages": [
{
"name": "server_tx_bytes_output",
"description": "Collect server tx_bytes",
"tags": ["traffic counter"],
"units": "Bps"
}
]
}
上記のように、エンドポイントにはプローブメタデータ、プロセッサインスタンスリスト、出力ステージリストの入力が与えられました。
プローブメタデータは、以下のフィールドで構成されています。
| label | 人間が読み取り可能なプローブラベル;必須 |
| description | プローブのオプションの説明、 |
| tags | プローブタグを持つ文字列のリスト。オプション |
| disabled | プローブを無効にすべきかどうかを示すオプションのブール値。無効にされたプローブはデータを提供し、リソースを消費しません。プローブはデフォルトでは無効ではありません。 |
各プロセッサー・インスタンスには、インスタンス名 (ユーザーによって定義されます)、プロセッサー・タイプ (プラットフォームとリファレンス・デザインで定義されたカタログからの選択)、および inputs /または outputsが含まれています。各プロセッサの追加フィールドはすべて、そのタイプのプロセッサに固有で、サブフィールドで properties 指定されており、当社のイントロスペクションAPI /api/blueprints/<blueprint_id>/telemetry/processorsを介してイントロスペクションによって学習できます。このAPIは後で確認します。
私たちの実際の例に一致すると、上記の例のプロセッサリストにある各エントリを見ていきます。
最初のエントリには、名前server_tx_bytesを付けるタイプif_counterのプロセッサ インスタンスがあります。グラフクエリと呼ばれるgraph_queryクエリを入力として取得します。次に、 と という名前interfacesystem_idの他の2つのフィールドがあります。これらの 3 つのフィールドは、システム内のすべてのサーバー側ポートに対して (の最初の派生版) カウンターを収集することを示しています。でgraph_query指定されたクエリの一致ごとに、(プロセッサ フィールドで指定されたsystem_id)結果のパス内のノードのsysフィールドを取得system_idして、system_idを抽出し、結果のパス内のノードのintfフィールドを取得if_nameしてインターフェイス名を取得します(プロセッサ フィールドでinterface指定)。システムIDとインターフェイスの組み合わせは、ネットワーク内のインターフェイスを識別するために使用され、そのtx_bytesカウンター(で指定)counter_typeがこのプロセッサの出力に配置されます。このプロセッサの出力は、タイプ"Number Set"(NS)です。ステージタイプについては後で徹底的に説明します。このプロセッサには入力がないため、フィールドはinput提供されません。それには、(if_counterプロセッサータイプで定義されています)とラベル付けされたout出力が1つあります。その出力は、 にラベル付けされたステージにマッピングされますserver_tx_bytes_output。
2番目のプロセッサはタイプ std_dev で、以前に作成 server_tx_bytes_outputしたステージを入力として受け取ります。フィールドの意味についてはプロセッサ固有のドキュメントを ddof 参照してください。また、フィールドの完全な意味については、プロセッサ固有のドキュメントを group_by 参照してください。今のところ、この場合 group_by 、入力NSから単一の出力「数値」(N)を構築するように指示すれば十分です。つまり、このプロセッサは、多くの入力番号のそれぞれで取得された単一の数の標準偏差を出力します。この出力は「std_dev_output」という名前です。
3番目のプロセッサは、タイプrange_checkのであり、入力std_dev_outputとしてを取ります.この場合、入力が 100 より大きい場合(サーバー向けトラフィックが偏っている場合に示すためにこの任意の値を選択しました)で指定されたrange想定範囲外の入力があることを確認します。このプロセッサは、我々はラベルstd_dev_output_in_rangeを付けるために選択した単一の出力を持っています.この出力(range_check プロセッサー・タイプで定義される)はDSタイプ(離散状態)であり、値が範囲外であるかどうかを示すまたは false、いずれかのtrue値を受け取ることができます。
私たちの最後のプロセッサは、タイプ anomaly のものであり、入力 std_dev_output_in_rangeとしてを取ります.入力が状態の場合、Apstra異常が発生します true 。このプロセッサは、我々はラベル server_traffic_imbalancedを付けるために選択した単一の出力を持っています.この出力(異常プロセッサ タイプで定義された)は DS タイプ(離散状態)であり、異常が発生するかどうかを示す値 true または falseまたは を取得できます。この例では、この異常な状態データをこれ以上処理しませんが、一般的な可能性を排除することはできません。
最後に、現場があります stages 。これは、出力ステージのサブセットのリストであり、各ステージはステージ・ラベルを name 参照するフィールドで示されます。このリストは、AGG自体から推測できないメタデータを各出力ステージに追加するためのものです。現在、サポートされているフィールドは次のとおりです。
| description | ステージ記述を含む文字列、 |
| tags | ステージのタグのセットを作成する文字列のリスト、 |
| units | ステージデータの単位を記述する文字列です。 |
これらのフィールドはすべてオプションです。
このステージメタデータは、REST APIを介してそのステージからデータを取得する際に返され、GUIによって可視化に使用されます。
HTTP POST を. に /api/blueprints/<blueprint_id>/probes送信できます。ここでは、「POST for Probe Creation」図に例示した POST プローブ構成を使用して新しいプローブを作成します。このエンドポイントへの POS を実行すると、Apstra の他の作成エンドポイントの大半として UUID が返されます。このエンドポイントは、追加の操作に使用できます。
バージョン 2.3 で変更: 前述の UUID ではなく予測可能なプローブ ID を取得するには、要求本文に「id」プロパティを追加して指定できます。
{
"id": "my_tx_bytes_probe",
"label": "server_tx_bytes",
"processors": [],
"rest_of_the": "request_body"
}
バージョン 2.3 で変更: 以前は、ステージ定義は次のようなプロセッサー定義にインライン化されていました。
{
"label": "test probe",
"processors": [
{
"name": "testproc",
"outputs": {"out": "test_stage"},
"stages": [{"name": "out", "units": "pps"}]
}
]
}
これでは機能しなくなり、stage name は内部ステージ名ではなくステージ ラベルを参照する必要があります。したがって、上記の例はこのように見えるはずです。
{
"stages": [{"name": "test_stage", "units": "pps"}]
}
追加の注意:プロセッサ定義にインラインステージ定義を使用せず、上記のPOSTの例のようにスタンドアロン要素として配置することをお勧めします。
HTTP DELETE は、 でprobe_id指定されたプローブを削除する場所に送信/api/blueprints/<blueprint_id>/probes/<probe_id>できます。
HTTP GETを送信して /api/blueprints/<blueprint_id>/probes/<probe_id> 、POSされたプローブの構成を取得できます。プローブ作成時に指定したフィールドよりも多くのフィールドが含まれます。
| id | プローブのID(作成時に指定されていない場合は UUID)を使用します。 |
| state | プローブの実際の状態。可能な値は、構成中のプローブに対して「作成」、正常に構成されたプローブの「運用」、プローブ設定に失敗した場合の「エラー」です。 |
| last_error | には、「エラー」状態のプローブの最新エラーに関する詳細なエラー説明が含まれています。以下のサブフィールドがあります。
|
プローブメッセージの完全なリストは、 に /api/blueprints/<blueprint_id>/probes/<probe_id>/messagesHTTP GETリクエストを発行することで取得できます。
メッセージは「タイムスタンプ」フィールドでソートされ、最も古いフィールドが最初に表示されます。
さらに、HTTP GETを送信して /api/blueprints/<blueprint_id>/probes 、ブループリント <blueprint_id>のすべてのプローブを取得できます。
2.3
プローブ用のHTTP PATCHおよび PUTメソッドは、Apstraバージョン2.3以降で利用できます。
HTTP PATCHを送信してプローブメタデータを /api/blueprints/<blueprint_id>/probes/<probe_id> 更新するか、プローブを無効または有効にすることができます。
{
"label": "new server_tx_bytes",
"description": "some better probe description",
"tags": ["production"],
"stages": [
{
"name": "server_tx_bytes",
"description": "updated stage description",
"tags": ["server traffic"],
"units": "bps"
}
]
}
この例では、上記の POST リクエストで作成されたプローブのプローブ メタデータを更新します。ここでのすべてのフィールドはオプションで、指定されなかった値は変更されません。
各ステージ・インスタンスもオプションで、つまり、指定されたステージのみが更新され、指定されたステージには変更されません。
タグコレクションは完全に更新され、PATCHペイロードがtags: ["a", "b"]指定されているtags: ["c"]場合、結果のコレクションは(NOTtags: ["a", "b", "c"])のようになりますtags: ["c"]。
PATCHを使用すると、プローブのプロセッサとステージのセットを変更することはできません。これを可能にする PUT の説明については、さらに読んでください。
HTTP PUTはプローブを置き換えるために /api/blueprints/<blueprint_id>/probes/<probe_id> 送信できます。
これは POST と非常に似ています。違いは、プローブ <probe_id> の古い設定をペイロードで指定された新しい設定に置き換えることです。このリクエストのペイロード形式は POST の場合と同じですが id 、許可されていません。
プローブの検査
ステージは、さまざまなプロセッサーの入出力に名前を付けることで暗黙的に作成されます。プローブのさまざまな段階を検査できます。特定のステージを読み取るためのAPIは、 /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/<stage_name>
各ステージにはタイプがあります。これは、生成プロセッサーとそのプロセッサーへの入力ステージの機能です。タイプは次のとおりです。数値(N);番号タイム シリーズ(NTS)、数値セット(NS)、Number Set Time Series(NSTS);テキスト(T);Text Time Series(TTS)、テキスト セット(TS);テキストセット時系列(TSTS);個別の状態(DS);個別の状態時系列(DSTS);個別の状態セット(DSS);個別設定時系列(DSSTS)
NSはまさにその数字です。
同様に、DSS は離散状態変数のセットです。DSS(およびDSSTS)ステージの仕様の一部は、離散状態変数が取ることができる値です。
テキスト セットは、文字列のセットです。
NSTS は、数値を値として持つ一連の時系列です。例えば、このセットのメンバーは、以下のようになります。(時間=0 秒、値=3)、(時間=3 秒、値=5)、(time=6 秒、値=23)、およびなどに指定します。
DSTS は NSTS と同じですが、値が不連続な状態である点が例外です。
TSTS は NSTS と同じですが、値が文字列以外の場合は同じです。
数値(N)、DS(不連続状態)、およびテキスト(T)は、単純な数値セット、不連続な状態セット、およびテキスト セットの長さが 1 であることが保証されます。
NTS、DSTS、TS は上記と同じですが、単一値ではなく時系列です。
最初の段階である「server_tx_bytes」について考えてみましょう。このステージには、システム内のすべてのサーバー側ポートのtx_bytesカウンターが含まれています。URLから取得できます /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/server_tx_bytes_output
得られる応答は、次のように同じ形式になります。
{
"properties": [
"interface",
"system_id"
],
"type": "ns",
"units": "bytes_per_second",
"values": [
{
"properties": {
"interface": "intf1",
"system_id": "spine1"
},
"value": 22
},
{
"properties": {
"interface": "intf2",
"system_id": "spine1"
},
"value": 23
},
{
"properties": {
"interface": "intf1",
"system_id": "spine3"
},
"value": 24
}
]
}
実行中の例のように、「server_tx_bytes」ステージには、ネットワーク内のすべてのサーバーに接続するインターフェイスのtx_bytes値が含まれています。上記の例を見ると、このステージは NS または Number-Set を示すタイプ「ns」であることが分かります。前述したように、ステージ内のデータはコンテキストに関連付けられます。これは、ステージのセット内のすべての要素が、キーと値のペアのグループに関連付けられていることを意味します。各ステージごとに、キーはデータ (または同等にセット内のアイテム) ごとに同じです。これらのキーは、特定のステージの「プロパティー」フィールドにリストされ、通常は生成プロセッサーの機能です。「value」内の各項目は、ステージの各プロパティに値を割り当て、値(「数値セット」の「数値」)を提供します。この段階におけるこのデータの意味は、スパイン1のintf1のtx_bytesが22で、スパイン1のintf2が23であり、スパイン3のintf1が24バイト/秒であるということです。
実行中の例で指定されたとおりに、このステージに対して「ユニット」が設定されていることに注意してください。
プローブの2番目のステージにクエリーを実行するには、HTTP GETをstdエンドポイントに送信します /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/std_dev_output。
{
"type": "n",
"units": "",
"value": 1
}
この段階は数字です。コンテキストはなく、1つの値しかありません。この例では、これはすべてのスパインにおける標準偏差です。
プローブの最後から 2 つ目のステージは、エンドポイント /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/server_traffic_imbalancedでクエリーを実行できます。
{
"possible_values": [
"true",
"false"
],
"type": "ds",
"units": "",
"value": false
}
この段階では、サーバー側のすべてのポートにおけるtx_bytes全体の標準偏差が 100 を超えるかどうかを示すことで、サーバー トラフィックの不均衡(「true」)か(「偽」)かを示します。「possible_values」フィールドには、不連続状態の「値」が取ることができるすべての値が記述されていることに注意してください。
プローブのすべてのプロセッサを介してクエリーを実行 /api/blueprints/<blueprint_id>/probes/<probe_id>/processors/<processor_name>することもできます。このようなクエリを行うことで、当該プロセッサの作成に使用される構成を発見することができます。
クエリ プローブの異常
このサンプルプロセッサの最終段階では、サーバーに面するインターフェイス全体のtx_bytesの標準偏差が100を超えると、Apstra異常が発生し、出力が「true」に設定されます。
標準の異常 API を使用して、プローブの異常を照会 /api/blueprints/<bluprint_id>/anomalies?type=probeできます。
以下は、サンプルプローブによって提起される異常のJSON形式です(この例では気にしないデータの省略記号)。
{
"actual": {
"value_int": 101
},
"anomaly_type": "probe",
"expected": {
"value_int": 100
},
"id": "...",
"identity": {
"anomaly_type": "probe",
"probe_id": "efb2bf7f-d8cc-4a55-8e9b-9381e4dba61f",
"properties": {},
"stage_id": "server_traffic_imbalanced"
},
"last_modified_at": "...",
"severity": "critical"
}
上記の例で見たように、ID にはprobe_idと、異常が発生したステージの名前が含まれており、オペレーターによるさらなる検査が必要です。特定のステージ内で、ステージのタイプがセットベースのタイプである場合、異常の「プロパティ」フィールドには、異常の原因となったセット内の特定のアイテムのプロパティが埋められます。これは、それぞれがセット内の異なるアイテムにある限り、1つのステージで複数の異常を発生させる重要なポイントをもたらします。この例では、問題のステージはNSタイプであるため、「プロパティ」フィールドは設定されていません。
イントロスペクション プロセッサー
オペレーターが使用可能なプロセッサー・セットは、プラットフォームとリファレンス・デザインの機能です。Apstraは、オペレーターが利用可能なすべてのプロセッサをリストし、どのようなパラメータを使用しているのか、必要な入力と出力が得られるかを学習するためのAPIを提供します。
問題のAPIは /api/blueprints/<blueprint_id>/telemetry/processors.
プロセッサの説明のリストが生成されます。次の例では、std_dev プロセッサの説明を表示します。
{
"description": "Standard Deviation Processor.\n\n Groups as described by group_by, then calculates std deviation and\n outputs one standard deviation for each group. Output is NS.\n Input is an NS or NSTS.\n ",
"inputs": {
"in": {
"required": true,
"types": [
{
"keys": [],
"possible_values": null,
"type": "ns"
},
{
"keys": [],
"possible_values": null,
"type": "nsts"
}
]
}
},
"outputs": {
"out": {
"required": true,
"types": [
{
"keys": [],
"possible_values": null,
"type": "ns"
}
]
}
},
"label": "Standard Deviation",
"name": "std_dev",
"schema": {
"additionalProperties": false,
"properties": {
"ddof": {
"default": 0,
"description": "Standard deviation correction value, is used to correct divisor (N - ddof) in calculations, e.g. ddof=0 - uncorrected sample standard deviation, ddof=1 - corrected sample standard deviation.",
"title": "ddof",
"type": "integer"
},
"enable_streaming": {
"default": false,
"type": "boolean"
},
"group_by": {
"default": [
"system_id"
],
"items": {
"type": "string"
},
"type": "array"
}
},
"type": "object"
}
}
前述のように、文字列ベースの説明、タイプ プロセッサー タイプの名前(プローブ構成の REST API に提供される)があります。特定のプローブに固有のパラメーターのセットは、「スキーマ」で説明されています。
特別な通知は、「入力」と「出力」に支払う必要があります。これらは「スキーマ」セクションにありますが、すべての種類のプロセッサに存在します。各プロセッサーはゼロまたはそれ以上の入力ステージを取ることができ、1 つ以上のステージを出力する必要があります。オプションのステージでは、「必須」を false に設定します。取るステージの名前 (プロセッサーの特定のインスタンスを基準として) は、これらの変数で記述されます。「std_dev」プロセッサは、「in」という名前の単一の入力と「out」という名前の単一の出力を受け取ることがわかります。これは、前の例での使用に反映されています。
1つの特別な入力名があります: *.例えば：
"inputs": {
"*": {
"required": true,
"types": [
{
"keys": [],
"possible_values": null,
"type": "ns"
},
{
"keys": [],
"possible_values": [],
"type": "dss"
},
{
"keys": [],
"possible_values": null,
"type": "ts"
}
]
}
}
これは、任意の名前で指定された型の 1 つ以上の入力を受け入れることをプロセッサを意味します。
3.0 で変更: 以前は、入力と出力のセクションに特定の入力または出力が必要かどうかを指定していなかったため、次の形式に変更しました。
この構文は非推奨であり、無効です。
"inputs": {
"in": [
{
"data_type": "ns",
"keys": [
"system_id"
],
"value_map": null,
"value_type": "int64"
}
...
]
}
データのストリーミング
任意のプローブのプロセッサインスタンスは、出力ステージをApstraストリーミング出力の「パーフモン」チャネルでストリーミングするように設定できます。任意のプロセッサーの構成でプロパティー「enable_streaming」が「true」に設定されている場合、その出力ステージはすべてのデータをストリーミングします。
非時系列のステージでは、値が変化するたびにメッセージが生成されます。時系列ベースのステージでは、時系列に新しいエントリーが作成されるたびにメッセージが生成されます。セットベースのステージでは、セット内の各項目が前の 2 つのルールに従ってメッセージを生成します。
生成される各メッセージには、値、タイムスタンプ、およびキーと値のペアのセットがあります。この値は自明です。タイムスタンプは、非時系列ベースのステージで値が変更された時刻、および時系列ベースのステージの新しいエントリーのタイムスタンプです。キーと値のペアは、ステージの「値」セクションで前述した「プロパティ」フィールドに対応するため、コンテキストを提供します。
以下に、PerfMonメッセージ(およびAosMessage内で順番にカプセル化される)からのIBAからのメッセージの形式があります。コンテキストのキーと値のペアは、値が「値」フィールドに置かれる間、(キーとして「名前」、値として「値」を持つ)「プロパティ」の繰り返しフィールドに入れます。「probe_id」「stage_name」は登場するとおりです。blueprint_idは、カプセル化された AosMessage の「origin_name」に配置されます。同様に、タイムスタンプは汎用の「タイムスタンプ」フィールドに入力されます。
message ProbeProperty {
required string name = 5;
required string value = 6;
}
message ProbeMessage {
repeated ProbeProperty property = 1;
oneof value {
int64 int64_value = 2;
float float_value = 3;
string string_value = 4;
}
required string probe_id = 5;
required string stage_name = 6;
}