Pruebas (API)
API de REST de sondeo genérico
La información a continuación describe tanto de la API como sea necesario para entender cómo usar IBA para alguien que ya conoce las convenciones de APstra API. La documenación formal de API está reservada para la propia documentación de la API.
Recorreremos la API a medida que se utiliza para el flujo de trabajo de ejemplo descrito en la introducción, y demostraremos su capacidad general con un ejemplo específico.
Crear sondeo
Para crear un sondeo, los TPV del operador a /api/blueprints/<blueprint_id>/probes con el siguiente formulario:
{
"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"
}
]
}
Como se vio anteriormente, al punto de conexión se le da una entrada de metadatos de la sonda, una lista de instancias de procesador y una lista de etapas de salida.
Los metadatos de la prueba se componen de los siguientes campos:
| label | etiqueta de sonda legible por el ser humano; Obligatorio |
| description | descripción opcional del sondeo, |
| tags | lista de cadenas con las etiquetas de prueba; Opcional |
| disabled | boolean opcional que indica si la sonda debe deshabilitarse. Las pruebas deshabilitadas no proporcionan datos y no consumen recursos. El sondeo no está deshabilitado de forma predeterminada. |
Cada instancia de procesador contiene un nombre de instancia (definido por el usuario), un tipo de procesador (una selección de un catálogo definido por la plataforma y el diseño de referencia) y inputs /o outputs. Todos los campos adicionales de cada procesador son específicos de ese tipo de procesador, se especifican en el properties subcampo, y se pueden aprender por introspección a través de nuestra API de introspección en /api/blueprints/<blueprint_id>/telemetry/processors; pasaremos sobre esta API más adelante.
Haciendo coincidir con nuestro ejemplo de trabajo, pasaremos por cada entrada que tengamos en la lista de procesadores en el ejemplo anterior.
En la primera entrada, tenemos una instancia de procesador del tipo if_counter que nombramos server_tx_bytes. Toma como entrada una consulta llamada graph_query que es una consulta de gráficos. Luego, tiene otros dos campos denominados interface y system_id. Estos tres campos juntos indican que queremos recopilar un contador (derivado de la primera vez de) para cada puerto orientado al servidor del sistema. Para cada coincidencia de la consulta especificada por graph_query, extraemos un system_id tomando el system_id campo del nodo en la sys ruta resultante (como se especifica en el campo del system_id procesador) y un nombre de interfaz tomando el if_name campo del intf nodo en la ruta resultante (como se especifica en el campo del interface procesador). La combinación del ID del sistema y la interfaz se utiliza para identificar una interfaz en la red, y su contador de tx_bytes (según lo especificado por counter_type) se coloca en la salida de este procesador. El resultado de este procesador es del tipo "Number Set" (NS); los tipos de etapas se analizan exhaustivamente más adelante. Este procesador no tiene entradas, por lo que no proporcionamos un input campo. Tiene una salida etiquetada out (tal como se define en el tipo de procesador if_counter); asignamos esa salida a una etapa etiquetada server_tx_bytes_outputcomo .
El segundo procesador es de tipo std_dev y toma como entrada la etapa que creamos antes llamada server_tx_bytes_output; consulte la documentación específica del procesador para ver el significado del ddof campo. Además, consulte la documentación específica del procesador para ver el significado completo del group_by campo. Bastará con decir por ahora que en este caso group_by nos dice que construyamos un único "Número" de salida (N) a partir del NS de entrada; es decir, este procesador produce un solo número, la desviación estándar tomada en cada uno de los muchos números de entrada. Este resultado se denomina "std_dev_output".
El tercer procesador es de tipo range_check y toma como entrada std_dev_output. Comprueba que la entrada está fuera del rango esperado especificado por - en este caso, si la entrada es alguna vez mayor que 100 (hemos elegido este valor arbitrario para indicar cuando el tráfico dirigido por range el servidor no está desequilibrado). Este procesador tiene una única salida que elegimos etiquetar std_dev_output_in_range. Esta salida (definida por el range_check tipo de procesador) es de tipo DS (estado discreto) y puede tomar valores o true false, que indican si un valor está o no fuera del rango.
Nuestro procesador final es de tipo anomaly y toma como entrada std_dev_output_in_range. Genera una anomalía de Apstra cuando la entrada está en true estado. Este procesador tiene una única salida que elegimos etiquetar server_traffic_imbalanced. Esta salida (definida por el tipo de procesador de anomalías) es del tipo DS (estado discreto) y puede tomar valores ya sea true o false, que indican si se produce o no una anomalía. En este ejemplo, no procesamos más con estos datos de estado anómalo, pero eso no excluye su posibilidad general.
Por último, tenemos un stages campo. Esta es una lista de un subconjunto de etapas de salida, con cada etapa indicada por el name campo que hace referencia a la etiqueta de etapa. Esta lista está pensada para agregar metadatos a cada etapa de salida que no se puede inferir del propio DAG. Actualmente, los campos compatibles son:
| description | cadena con una descripción de etapa, |
| tags | lista de cadenas que hacen un conjunto de etiquetas para el escenario, |
| units | cadena que está destinado a describir las unidades de los datos de etapa. |
Todos estos campos son opcionales.
Los metadatos de esta etapa se devuelven cuando se obtienen datos de esa etapa a través de la API de REST y la GUI los utiliza en la visualización.
HTTP POST se puede enviar a /api/blueprints/<blueprint_id>/probes. Aquí, publicamos la configuración del sondeo, como se ejemplifica en la figura "POST for Probe Creation" para crear un nuevo sondeo. POSTing a este punto de conexión devolverá un UUID, como la mayoría de los otros puntos de conexión de creación en Apstra, que se pueden usar para operaciones posteriores.
Cambiado en la versión 2.3: para obtener un id de sondeo predecible en lugar de un UUID descrito anteriormente, se podría especificar agregando una propiedad "id" al cuerpo de la solicitud.
{
"id": "my_tx_bytes_probe",
"label": "server_tx_bytes",
"processors": [],
"rest_of_the": "request_body"
}
Cambiado en la versión 2.3: Anteriormente, las definiciones de etapa se insinían en definiciones de procesador como esta:
{
"label": "test probe",
"processors": [
{
"name": "testproc",
"outputs": {"out": "test_stage"},
"stages": [{"name": "out", "units": "pps"}]
}
]
}
Esto ya no funciona, y el nombre de etapa debe hacer referencia a la etiqueta de etapa en lugar del nombre interno de la etapa. Así que el ejemplo anterior debería verse así:
{
"stages": [{"name": "test_stage", "units": "pps"}]
}
Nota adicional: se recomienda no integrar las definiciones de etapa en las definiciones del procesador y colocarla como un elemento independiente, como en el ejemplo de POST anterior.
HTTP DELETE se puede enviar a /api/blueprints/<blueprint_id>/probes/<probe_id> dónde eliminar el sondeo especificado por su probe_id.
HTTP GET se puede enviar a /api/blueprints/<blueprint_id>/probes/<probe_id> para recuperar la configuración del sondeo a medida que se posted. Contendrá más campos de los que se especificó al crear la sonda:
| id | con id del sondeo (o UUID si no se especificó en el momento de creación), |
| state | con el estado real de la sonda; los valores posibles son "creados" para una sonda que se está configurando, "operativo" para una prueba configurada correctamente y "error" si la configuración de la sonda ha fallado. |
| last_error | contiene una descripción de error detallada para el error más reciente de los sondeos en el estado "error". Tiene los siguientes sub-campos:
|
La lista completa de mensajes de sondeo se puede obtener mediante la emisión de http get solicitud a /api/blueprints/<blueprint_id>/probes/<probe_id>/messages.
Los mensajes se ordenan por el campo 'marca de hora', el más antiguo viene primero.
Además, se puede enviar HTTP GET a /api/blueprints/<blueprint_id>/probes para recuperar todos los sondeos para el plano <blueprint_id>.
2.3
Los métodos HTTP PATCH y PUT para las pruebas están disponibles desde Apstra versión 2.3.
El PARCHE HTTP se puede enviar a /api/blueprints/<blueprint_id>/probes/<probe_id> para actualizar los metadatos del sondeo o deshabilitar o habilitar el sondeo.
{
"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"
}
]
}
En este ejemplo, se actualizan los metadatos del sondeo que se creó con la solicitud POST enumerada anteriormente. Todos los campos aquí son opcionales, los valores que no se especificaron permanecen inalterados.
Cada instancia de etapa también es opcional, es decir, solo se actualizarán las etapas especificadas y las etapas no especificadas permanecen inalteradas.
La recopilación de etiquetas se actualiza por completo, es decir, si estaba tags: ["a", "b"] y la carga PATCH especificada tags: ["c"], la recopilación resultante se verá como tags: ["c"] (NO tags: ["a", "b", "c"]).
Con PATCH no es posible cambiar el conjunto de etapas y el procesador de la sonda. Lea más para ver la descripción de PUT que permite hacerlo.
HTTP PUT se puede enviar a /api/blueprints/<blueprint_id>/probes/<probe_id> para reemplazar un sondeo.
Esto es muy similar a POST, con la diferencia de que reemplaza la configuración antigua para la prueba <probe_id> por la nueva especificada en la carga. El formato de carga para esta solicitud es el mismo que para POST, pero id no está permitido.
Sondeo de inspección
Las etapas se crean implícitamente al ser nombradas en la entrada y salida de varios procesadores. Puede inspeccionar las distintas etapas de una sonda. La API para leer una etapa en particular es /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/<stage_name>
Cada etapa tiene un tipo. Esta es una función del procesador de generación y las etapas de entrada a ese procesador. Los tipos son: Número (N); Serie de tiempo numérico (NTS), conjunto de números (NS); Serie de tiempo establecido de números (NST); Texto (T); Serie de tiempo de texto (TTS); Conjunto de texto (TS); Series de tiempo de conjunto de texto (TST); Estado discreto (DS); Serie de tiempo de estado discreto (DSTS); Conjunto de estados discretos (DSS); Serie de tiempo de conjunto discreto (DSST)
Un NS es exactamente eso: un conjunto de números.
De manera similar, un DSS es un conjunto de variables de estado discreto. Parte de la especificación de una etapa DSS (y DSSTS) son los valores posibles que puede tomar la variable de estado discreto.
Un conjunto de texto es un conjunto de cadenas.
Un NSTS es un conjunto de series temporales con números como valores. Por ejemplo, un miembro de este conjunto sería: (tiempo= 0 segundos, valor = 3), (tiempo = 3 segundos, valor = 5), (tiempo = 6 segundos, valor = 23) y así sucesivamente.
Un DSTS es el mismo que un NSTS, excepto que los valores son de estado discreto.
Un TSTS es el mismo que un NSTS, excepto que los valores son cadenas.
Número (N), estado discreto (DS) y texto (T) son simplemente conjuntos de números, conjuntos de estados discretos y conjuntos de texto de longitud uno garantizados.
NTS, DSTS y TS son los mismos que los anteriores, pero son series temporales en lugar de valores únicos.
Consideremos la primera etapa: "server_tx_bytes". Esta etapa contiene el contador de tx_bytes para cada puerto orientado al servidor del sistema. Podemos obtenerlo desde la url /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/server_tx_bytes_output
La respuesta que obtendríamos sería de la misma forma que la siguiente:
{
"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
}
]
}
Como sabemos a partir de nuestro ejemplo en ejecución, la etapa "server_tx_bytes" contiene el valor tx_bytes para cada interfaz orientada al servidor de la red. Al ver el ejemplo anterior, podemos ver que esta etapa es del tipo "ns", que indica NS o Number-Set. Como se mencionó antes, los datos en etapas se asocian con el contexto. Esto significa que cada elemento del conjunto de una etapa está asociado con un grupo de pares clave-valor. Por cada etapa, las claves son las mismas para cada dato (o, equivalentemente, elemento del conjunto). Estas claves se enumeran en el campo "propiedades" de una etapa determinada y generalmente son una función del procesador de generación. Cada uno de los elementos en "valores" asigna un valor a cada una de las propiedades del escenario y proporciona un valor (el "Número" en el "Conjunto de números"). El significado de estos datos en esta etapa es que tx_bytes en intf1 de spine1 es 22, en intf2 de spine1 es 23 y en intf1 de spine3 es 24 bytes por segundo.
Observe que se establece "unidades" para esta etapa como se especifica en el ejemplo en ejecución.
Para consultar la segunda etapa de nuestro sondeo, envíe un GET HTTP al punto de conexión /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/std_dev_outputstd.
{
"type": "n",
"units": "",
"value": 1
}
Esta etapa es un número. No tiene contexto, solo un valor. En nuestro ejemplo, esta es la desviación estándar en todas las spines.
La penúltima etapa de nuestra sonda puede ser consultada en el punto de conexión /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/server_traffic_imbalanced.
{
"possible_values": [
"true",
"false"
],
"type": "ds",
"units": "",
"value": false
}
Como se muestra, esta etapa indica si el tráfico del servidor está desequilibrado ("verdadero") o no ("false") al indicar si la desviación estándar a través de tx_bytes en todos los puertos orientados al servidor es mayor que 100. Observe que el campo "possible_values" describe todos los valores que el "valor" de estado discreto puede tomar.
Todos los procesadores de una sonda también pueden ser consultados a través de /api/blueprints/<blueprint_id>/probes/<probe_id>/processors/<processor_name>. Al realizar dicha consulta, puede descubrir la configuración utilizada para la creación de dicho procesador.
Anomalías del sondeo de consulta
La etapa final de nuestro procesador de ejemplo plantea una anomalía de Apstra (y establece su resultado en "true"), cuando la desviación estándar de tx_bytes en las interfaces orientadas al servidor es mayor que 100.
Puede consultar anomalías de sondeo mediante la API de anomalías estándar en /api/blueprints/<bluprint_id>/anomalies?type=probe.
La siguiente es la forma JSON de una anomalía que plantearía nuestro sondeo de ejemplo (con puntos suspensivos para datos que no nos importan en este ejemplo):
{
"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"
}
Como se ve en el ejemplo anterior, la identidad contiene el probe_id y el nombre de la etapa en la que se planteó la anomalía y que requiere una inspección adicional por parte del operador. Dentro de una etapa determinada, si el tipo de etapa fuera un tipo basado en conjuntos, el campo "propiedades" de la anomalía se llenaría con las propiedades del elemento específico del conjunto que causó la anomalía. Esto trae al punto importante de que se pueden plantear varias anomalías en una sola etapa, siempre y cuando cada una se encuentra en un elemento diferente del conjunto. En nuestro ejemplo, dado que la etapa en cuestión es del tipo NS, el campo "propiedades" no se establece.
Procesadores de introducción
El conjunto de procesadores disponibles para el operador es una función de la plataforma y el diseño de referencia. Apstra proporciona una API para que el operador enumre todos los procesadores disponibles, aprenda qué parámetros toman y qué entradas requieren y los resultados que producen.
La API en cuestión se encuentra en /api/blueprints/<blueprint_id>/telemetry/processors.
Ofrece una lista de descripciones del procesador. En el siguiente ejemplo, mostramos la descripción del procesador 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"
}
}
Como se vio anteriormente, hay una descripción basada en cadenas, el nombre del tipo de procesador (tal como se proporciona a la API de REST en la configuración del sondeo). El conjunto de parámetros específicos de un sondeo determinado se describe en el "esquema".
Se debe pagar una notificación especial a "entradas" y "salidas". Aunque se encuentran en la sección "esquema", están presentes en todos los tipos de procesador. Cada procesador puede tomar cero o más etapas de entrada y debe emitir una o más etapas. Las etapas opcionales tienen "obligatorio" establecido en false. Los nombres de las etapas (en relación con una instancia determinada de un procesador) que toman se describen en estas variables. Podemos ver que el procesador "std_dev" toma una sola entrada denominada "in" y una sola salida denominada "out". Esto se refleja en nuestro uso en el ejemplo anterior.
Hay un nombre de entrada especial: *. Por ejemplo:
"inputs": {
"*": {
"required": true,
"types": [
{
"keys": [],
"possible_values": null,
"type": "ns"
},
{
"keys": [],
"possible_values": [],
"type": "dss"
},
{
"keys": [],
"possible_values": null,
"type": "ts"
}
]
}
}
Significa que el procesador acepta una o más entradas de los tipos especificados con nombres arbitrarios.
Cambiado en la 3.0: Anteriormente, la sección entradas y salidas no especificaba si se requerían entradas o salidas específicas, por lo que el formato se cambió de lo siguiente:
Esta sintaxis está en desuso e no es válida.
"inputs": {
"in": [
{
"data_type": "ns",
"keys": [
"system_id"
],
"value_map": null,
"value_type": "int64"
}
...
]
}
Datos de transmisión
Cualquier instancia de procesador en cualquier sonda se puede configurar para que sus etapas de salida se transmitan en el canal "perfmon" de la salida de transmisión de apstra. Si la propiedad "enable_streaming" está establecida en "true" en la configuración de cualquier procesador, sus etapas de salida tendrán todos sus datos transmitidos.
Para las etapas no basadas en series de tiempo, cada una generará un mensaje cada vez que cambie su valor. Para las etapas basadas en series temporales, cada una generará un mensaje cada vez que se realice una nueva entrada en la serie temporal. Para las etapas basadas en conjuntos, cada elemento del conjunto generará un mensaje de acuerdo con las dos reglas anteriores.
Cada mensaje que se genera tiene un valor, una marca de hora y un conjunto de pares clave-valor. El valor se explica por sí mismo. La marca de hora es el momento en el que cambió el valor de las etapas basadas en series no temporales y la marca de hora de la nueva entrada para las etapas basadas en series temporales. Los pares clave-valor corresponden al campo "propiedades" que observamos anteriormente en la sección "valores" de las etapas, proporcionando así contexto.
A continuación tenemos el formato de los mensajes de IBA que se encapsula en un mensaje PerfMon (y que a su vez en un AosMessage). Los pares clave-valor de contexto se colocan en el campo repetido "propiedad" (con "nombre" como clave y "valor" como valor) mientras que el valor se coloca en el campo "valor". "probe_id" y "stage_name" son como aparecen. El blueprint_id se pone en el "origin_name" del AosMessage encapsulado. De manera similar, la marca de hora se coloca en el campo genérico "marca de hora".
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;
}