Sondas (API)
API DE REST da Sonda Genérica
As informações abaixo descrevem a maior parte da API conforme necessário para entender como usar a IBA para alguém já familiarizado com as convenções de API da Apstra. A documenação formal da API está reservada para a documentação da API em si.
Passaremos pela API como ela é usada para o exemplo de fluxo de trabalho descrito na introdução, demonstrando sua capacidade geral por exemplo específico.
Criar sonda
Para criar uma sonda, o operador POSTs para /api/blueprints/<blueprint_id>/probes com o seguinte formulário:
{
"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 visto acima, o endpoint recebe uma entrada de metadados de sonda, uma lista de instâncias de processador e lista de estágios de saída.
Os metadados de sonda são compostos dos seguintes campos:
| label | rótulo de sonda legível por humanos; Necessário |
| description | descrição opcional da sonda, |
| tags | lista de strings com as tags de sonda; Opcional |
| disabled | boolean opcional que diz se a sonda deve ser desabilitada. As sondas desativadas não fornecem dados e não consomem nenhum recurso. A sonda não é desabilitada por padrão. |
Cada instância do processador contém um nome de instância (definido pelo usuário), tipo de processador (uma seleção de um catálogo definido pela plataforma e pelo design de referência) e inputs /ou outputs. Todos os campos adicionais em cada processador são específicos para esse tipo de processador, são especificados no properties sub-campo e podem ser aprendidos por introspecção por meio de nossa API /api/blueprints/<blueprint_id>/telemetry/processorsde introspecção; passaremos por essa API mais tarde.
Combinando nosso exemplo de trabalho, passaremos por cada entrada que temos na lista de processadores no exemplo acima.
Na primeira entrada, temos uma instância de processador do tipo if_counter que nomeamos server_tx_bytes. Ele leva como entrada uma consulta chamada graph_query que é uma consulta de gráfico. Em seguida, tem outros dois campos nomeados interface e system_id. Juntos, esses três campos indicam que queremos coletar um contador (primeiro derivativo) para cada porta voltada para servidores do sistema. Para cada correspondência da consulta especificada por graph_query, extraimos uma system_id tomando o system_id campo do sys nó no caminho resultante (conforme especificado no campo do system_id processador) e um nome de interface, tomando o if_name campo do intf nó no caminho resultante (conforme especificado no campo do interface processador). A combinação de ID e interface do sistema é usada para identificar uma interface na rede, e seu contador de tx_bytes (conforme especificado por counter_type) é colocado na saída deste processador. A saída deste processador é do tipo "Conjunto de números" (NS); tipos de estágio são discutidos exaustivamente mais tarde. Este processador não tem entradas, por isso não fornecemos um input campo. Ele tem uma saída, rotulada out (conforme definido pelo tipo de processador if_counter); mapeamos essa saída para um estágio identificado server_tx_bytes_output.
O segundo processador é do tipo std_dev e toma como entrada o estágio que criamos antes chamado server_tx_bytes_output; veja a documentação específica do processador para o significado do ddof campo. Além disso, consulte a documentação específica do processador para o significado completo do group_by campo. Será suficiente dizer, por enquanto, que, neste caso group_by , nos diz para construir um único "Número" (N) de saída a partir do NS de entrada; ou seja, este processador gera um único número, o desvio padrão levado em cada um dos muitos números de entrada. Esta saída é chamada de "std_dev_output".
O terceiro processador é do tipo range_check e toma como entrada std_dev_output. Ele verifica se a entrada está fora da faixa esperada especificada por - neste caso, se a entrada for sempre superior a 100 (optamos por esse valor arbitrário para indicar quando o tráfego orientado pelo range servidor está desequilibrado). Este processador tem uma saída única que escolhemos etiquetar std_dev_output_in_range. Essa saída (conforme definido pelo tipo de processador range_check) é do tipo DS (Estado Discreto) e pode levar valores true ou false, indicando se um valor está ou não fora da faixa.
Nosso processador final é do tipo anomaly e toma como entrada std_dev_output_in_range. Ela aumenta uma anomalia do Apstra quando a entrada está no true estado. Este processador tem uma saída única que escolhemos etiquetar server_traffic_imbalanced. Essa saída (conforme definido pelo tipo de processador de anomalia) é do tipo DS (Estado Discreto) e pode levar valores true ou false, indicando se uma anomalia é levantada ou não. Não fazemos nenhum processamento adicional com esses dados de estado anômalos neste exemplo, mas isso não impede sua possibilidade geral.
Finalmente, temos um stages campo. Esta é uma lista de um subconjunto de estágios de saída, com cada estágio indicado pelo name campo que se refere ao rótulo de palco. Esta lista destina-se a adicionar metadados a cada estágio de saída que não podem ser inferidos do próprio DAG. Atualmente, os campos suportados são:
| description | string com uma descrição do palco, |
| tags | lista de strings que fazem um conjunto de tags para o palco, |
| units | string destinada a descrever as unidades dos dados do estágio. |
Todos esses campos são opcionais.
Esses metadados de estágio são devolvidos ao buscar dados desse estágio por meio da API REST e usados pela GUI na visualização.
HTTP POST pode ser enviado para /api/blueprints/<blueprint_id>/probes. Aqui, vemos a configuração da sonda POST, como exemplificado na figura "POST for Probe Creation" para criar uma nova sonda. O POSTing para este endpoint devolverá um UUID, como a maioria dos outros endpoints de criação no Apstra, que podem ser usados para operações posteriores.
Alterado na versão 2.3: para obter um id de sonda previsível em vez de um UUID descrito acima, pode-se especifique-o adicionando uma propriedade "identificação" ao órgão de solicitação.
{
"id": "my_tx_bytes_probe",
"label": "server_tx_bytes",
"processors": [],
"rest_of_the": "request_body"
}
Alterado na versão 2.3: anteriormente, as definições de estágio estavam insolentes em definições de processador como esta:
{
"label": "test probe",
"processors": [
{
"name": "testproc",
"outputs": {"out": "test_stage"},
"stages": [{"name": "out", "units": "pps"}]
}
]
}
Isso não funciona mais, e o nome do palco deve se referir ao rótulo de palco em vez do nome do palco interno. Portanto, o exemplo acima deve olhar dessa forma:
{
"stages": [{"name": "test_stage", "units": "pps"}]
}
Observação adicional: recomenda-se não colocar definições de estágio em linha nas definições do processador e colocá-las como um elemento autônomo como no exemplo post acima.
O HTTP DELETE pode ser enviado para /api/blueprints/<blueprint_id>/probes/<probe_id> onde excluir a sonda especificada por sua probe_id.
HTTP GET pode ser enviado para /api/blueprints/<blueprint_id>/probes/<probe_id> recuperar a configuração da sonda conforme ela foi POSTed. Ele conterá mais campos do que foi especificado na criação da sonda:
| id | com id da sonda (ou UUID, se não for especificado no momento da criação), |
| state | com o estado real da sonda; os valores possíveis são "criados" para que uma sonda seja configurada, "operacional" para uma sonda configurada com sucesso e "erro" se a configuração da sonda falhar. |
| last_error | contém uma descrição detalhada de erro para o erro mais recente para sondas no estado de "erro". Ele tem os seguintes sub-campos:
|
A lista completa de mensagens de sonda pode ser obtida através da emissão de solicitação HTTP GET para /api/blueprints/<blueprint_id>/probes/<probe_id>/messages.
As mensagens são classificadas pelo campo "timestamp", o mais antigo vem em primeiro lugar.
Além disso, o HTTP GET pode ser enviado para /api/blueprints/<blueprint_id>/probes recuperar todas as sondas para o blueprint <blueprint_id>.
2.3
Os métodos HTTP PATCH e PUT para sondas estão disponíveis desde a versão 2.3 do Apstra.
O PATCH HTTP pode ser enviado para /api/blueprints/<blueprint_id>/probes/<probe_id> atualizar os metadados da sonda ou desabilitar ou habilitar a sonda.
{
"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"
}
]
}
Este exemplo atualiza metadados de sonda para a sonda criada com a solicitação POST listada acima. Todos os campos aqui são opcionais, os valores que não foram especificados permanecem inalterados.
Cada instância de estágio também é opcional, ou seja, apenas estágios especificados serão atualizados e os estágios não especificados permanecem inalterados.
A coleta de tags é atualizada inteiramente, ou seja, se fosse tags: ["a", "b"] e a carga de pagamento PATCH especificada tags: ["c"], então a coleta resultante se parecerá tags: ["c"] (NÃO tags: ["a", "b", "c"]).
Com o PATCH, não é possível alterar o conjunto de processadores e estágios da sonda. Leia mais para a descrição do PUT que permite fazer isso.
HTTP PUT pode ser enviado para /api/blueprints/<blueprint_id>/probes/<probe_id> substituir uma sonda.
Isso é muito semelhante ao POST, com a diferença é que ele substitui a configuração antiga para sonda <probe_id> por a nova especificada no payload. O formato de payload para esta solicitação é o mesmo que para POST, mas id não é permitido.
Inspecione a sonda
Os estágios são criados implicitamente ao serem indicados na entrada e saída de vários processadores. Você pode inspecionar os vários estágios de uma sonda. A API para leitura de um estágio específico é /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/<stage_name>
Cada estágio tem um tipo. Essa é uma função do processador gerador e do(s) estágio(s) de entrada para esse processador. Os tipos são: Número (N); Série de tempo de número (NTS), conjunto de números (NS); Série de tempo definida por números (NSTS); Texto (T); Série de tempo de texto (TTS); Conjunto de texto (TS); Série de tempo definida por texto (TSTS); Estado discreto (DS); Série de tempo de estado discreta (DSTS); Conjunto de estado discreto (DSS); Série de tempo definida discreta (DSSTS)
Um NS é exatamente isso: um conjunto de números.
Da mesma forma, um DSS é um conjunto de variáveis de estado discreto. Parte da especificação de um estágio DSS (e DSSTS) é os valores possíveis que a variável de estado discreto pode levar.
Um conjunto de textos é um conjunto de strings.
Um NSTS é um conjunto de séries de tempo com números como valores. Por exemplo, um membro deste conjunto seria: (tempo=0 segundos, valor=3), (tempo=3 segundos, valor=5), (tempo=6 segundos, valor=23) e assim por diante.
Um DSTS é o mesmo que um NSTS, exceto que os valores são de estado discreto.
Um TSTS é o mesmo que um NSTS, exceto que os valores são strings.
Número (N), estado discreto (DS) e texto (T) são simplesmente conjuntos de números, conjuntos de estado discretos e conjuntos de texto garantidos para ter comprimento um.
NTS, DSTS e TS são os mesmos que acima, mas são séries de tempo em vez de valores únicos.
Vamos considerar o primeiro estágio: "server_tx_bytes". Este estágio contém o contador tx_bytes para todas as portas voltadas para servidores do sistema. Podemos obtê-lo do url /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/server_tx_bytes_output
A resposta que recebemos seria da mesma forma que a seguinte:
{
"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 pelo nosso exemplo de execução, o estágio "server_tx_bytes" contém o valor tx_bytes para cada interface voltada para servidores na rede. Olhando para o exemplo acima, podemos ver que esse estágio é do tipo "ns", indicando NS ou Number-Set. Como mencionado antes, os dados em estágios estão associados ao contexto. Isso significa que todos os elementos do conjunto de um estágio estão associados a um grupo de pares de valor-chave. Em cada estágio, as chaves são as mesmas para cada pedaço de dados (ou, equivalentemente, item no conjunto). Essas chaves estão listadas no campo "propriedades" de um determinado estágio e geralmente são uma função do processador gerador. Cada um dos itens em "valores" atribui um valor a cada uma das propriedades do estágio e fornece um valor (o "Número" no "Conjunto de Números"). O significado desses dados nesta fase é que tx_bytes no intf1 do spine1 é de 22, no intf2 do spine1 é de 23, e no intf1 do spine3 é de 24 bytes por segundo.
Observe que "unidades" estão definidas para este estágio conforme especificado no exemplo em execução.
Para consultar o segundo estágio em nossa sonda, envie um HTTP GET para o endpoint /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/std_dev_outputstd.
{
"type": "n",
"units": "",
"value": 1
}
Este estágio é um número. Não tem contexto, apenas um único valor. Em nosso exemplo, este é o desvio padrão em todos os spines.
A penúltima etapa de nossa sonda pode ser consultada no endpoint /api/blueprints/<blueprint_id>/probes/<probe_id>/stages/server_traffic_imbalanced.
{
"possible_values": [
"true",
"false"
],
"type": "ds",
"units": "",
"value": false
}
Como mostrado, este estágio indica se o tráfego do servidor está desequilibrado ("verdadeiro") ou não ("falso") indicando se o desvio padrão em toda a tx_bytes em todas as portas voltadas para servidores é superior a 100. Observe que o campo "possible_values" descreve todos os valores que o "valor" de estado discreto pode levar.
Todos os processadores de uma sonda também podem ser questionados por /api/blueprints/<blueprint_id>/probes/<probe_id>/processors/<processor_name>. Ao fazer essa consulta, você pode descobrir a configuração usada para a criação do referido processador.
Anomalias da sonda de consulta
O estágio final do nosso processador de exemplo eleva uma anomalia do Apstra (e define sua saída como "verdadeira"), quando o desvio padrão de tx_bytes em interfaces voltadas para servidor é superior a 100.
Você pode consultar anomalias da sonda por meio da API padrão de anomalias em /api/blueprints/<bluprint_id>/anomalies?type=probe.
A seguir está a forma JSON de uma anomalia que seria levantada por nossa sonda de exemplo (com elipses para dados que não nos importamos para este exemplo):
{
"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 visto no exemplo acima, a identidade contém a probe_id e o nome do palco no qual a anomalia foi levantada e que requer uma inspeção adicional pelo operador. Em um determinado estágio, se o tipo de estágio fosse um tipo baseado em conjunto, o campo "propriedades" da anomalia seria preenchido com as propriedades do item específico no conjunto que causou a anomalia. Isso traz o ponto importante de que várias anomalias podem ser levantadas em um único estágio, desde que cada uma esteja em um item diferente no conjunto. Em nosso exemplo, como o estágio em questão é do tipo NS, o campo "propriedades" não é definido.
Processadores introspect
O conjunto de processadores disponíveis para a operadora é uma função da plataforma e do design de referência. O Apstra fornece uma API para a operadora listar todos os processadores disponíveis, aprender quais parâmetros eles pegam e aprender quais entradas eles precisam e saídas que eles produzem.
A API em questão é encontrada em /api/blueprints/<blueprint_id>/telemetry/processors.
Ele produz uma lista de descrições do processador. No exemplo a seguir, mostramos a descrição do processador de 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 visto acima, existe uma descrição baseada em strings, o nome do tipo processador (conforme fornecido à API REST na configuração da sonda). O conjunto de parâmetros específicos de uma determinada sonda é descrito no "esquema".
O aviso especial deve ser pago a "entradas" e "saídas". Embora estejam na seção "schema", eles estão presentes em todos os tipos de processador. Cada processador pode ter estágios de entrada zero ou mais e deve realizar um ou mais estágios. Os estágios opcionais "exigiram" configuração falsa. Os nomes dos estágios (em relação a uma instância específica de um processador) que eles tomam são descritos nessas variáveis. Podemos ver que o processador "std_dev" leva uma única entrada nomeada "in" e uma única saída chamada "out". Isso se reflete em nosso uso dele no exemplo anterior.
Há um nome de entrada especial: *. Por exemplo:
"inputs": {
"*": {
"required": true,
"types": [
{
"keys": [],
"possible_values": null,
"type": "ns"
},
{
"keys": [],
"possible_values": [],
"type": "dss"
},
{
"keys": [],
"possible_values": null,
"type": "ts"
}
]
}
}
Isso significa que o processador aceita uma ou mais entradas dos tipos especificados com nomes arbitrários.
Alterado em 3.0: Anteriormente, a seção de entradas e saídas não especificava se eram necessárias entradas ou saídas específicas, de modo que o formato foi alterado a partir do seguinte:
Essa sintaxe é preterida e inválida.
"inputs": {
"in": [
{
"data_type": "ns",
"keys": [
"system_id"
],
"value_map": null,
"value_type": "int64"
}
...
]
}
Dados de fluxo
Qualquer instância de processador em qualquer sonda pode ser configurada para ter seus estágios de saída transmitidos no canal "perfmon" da saída de streaming Apstra. Se a propriedade "enable_streaming" for definida como "verdadeira" na configuração para qualquer processador, seus estágios de saída terão todos os seus dados transmitidos.
Para estágios baseados em séries sem tempo, cada um gerará uma mensagem sempre que seu valor mudar. Para estágios baseados na Série Time, cada um gerará uma mensagem sempre que uma nova entrada for feita na série temporal. Para estágios baseados em conjunto, cada item do conjunto gerará uma mensagem de acordo com as duas regras anteriores.
Cada mensagem gerada tem um valor, um tempotamp e um conjunto de pares de valor-chave. O valor é autoexplanatório. O ponto de tempo é o momento em que o valor mudou para estágios baseados na série Non Time e o tempo da nova entrada para estágios baseados na série Time. Os pares de valor-chave correspondem ao campo "propriedades" que observamos anteriormente na seção de "valores" dos estágios, fornecendo assim contexto.
Abaixo, temos o formato de mensagens do IBA que é encapsulado em uma mensagem PerfMon (e que, por sua vez, em um AosMessage). Os pares de contexto de valor-chave são colocados no campo repetido "propriedade" (com "nome" como a chave e "valor" como valor) enquanto o valor é colocado no campo de "valor". "probe_id" e "stage_name" são como parecem. A blueprint_id é colocada no "origin_name" do AosMessage encapsulado. Da mesma forma, o tempotamp é colocado no campo genérico de "timestamp".
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;
}