Usar as APIs de métricas

Você está vendo a documentação do Apigee Edge.
Acesse a documentação da Apigee X.
informações

O Apigee Edge registra uma ampla variedade de dados operacionais e de negócios que fluem pelas APIs. As métricas derivadas desses dados são úteis para monitoramento operacional e de negócios. Usando a análise da API Edge, é possível, por exemplo, determinar quais APIs têm bom ou mau desempenho, quais desenvolvedores estão fornecendo o tráfego de maior valor e quais apps estão causando mais problemas para seus serviços de back-end.

Para facilitar o acesso a esses dados de métricas, o Edge expõe uma API RESTful. Use-a quando precisar automatizar certas funções do Google Analytics, como recuperar métricas periodicamente usando um script ou cliente de automação. Também é possível usar a API para criar as próprias visualizações na forma de widgets personalizados, que podem ser incorporados a portais ou apps personalizados.

Para saber como usar o Analytics na interface de gerenciamento do Edge de API, consulte Visão geral da Análise de API.

Sobre as APIs de métricas

O Edge fornece duas APIs de métricas:

  • O recurso Receber métricas retorna métricas para uma organização e o ambiente durante um período, como uma hora, um dia ou uma semana.

    Por exemplo, para a semana anterior que você quer obter:

    • O número de erros de política
    • Tempo médio de resposta
    • O tráfego total
  • O recurso de organizar as métricas por dimensões retorna métricas durante um período para uma organização e um ambiente agrupados por dimensão.

    Por exemplo, para a semana anterior, você usa dimensões para agrupar métricas por produto de API, proxy de API e e-mail do desenvolvedor para obter:

    • O número de erros de política por produto de API
    • O tempo médio de resposta por proxy de API
    • O tráfego total por e-mail do desenvolvedor

    A API Organizar as métricas por dimensões é compatível com outros recursos que não são compatíveis com a API Ver métricas, incluindo:

Sobre as cotas da API Metrics

O Edge aplica as cotas a seguir nessas chamadas. A cota é baseada no sistema de back-end que processa a chamada:

  • Postgres: 40 chamadas por minuto
  • BigQuery 12 chamadas por minuto

Determine o sistema de back-end que processa a chamada examinando o objeto de resposta. Cada objeto de resposta contém uma propriedade metaData, que lista o serviço que processou a chamada na propriedade Source. Por exemplo, para Postgres:

{
  ...
  "metaData": {
    "errors": [],
    "notices": [
      "Source:Postgres",
      "Table used: xxxxxx.yyyyy",
      "query served by:111-222-333"
    ]
  }
}

Para o BigQuery, a propriedade Source é:

"Source:Big Query"

Se você exceder a cota de chamada, a API retornará uma resposta HTTP 429.

Acessar métricas com a API Management

A principal diferença entre as duas APIs é que Receber métricas retorna métricas brutas para toda a organização e o ambiente, enquanto que Receber métricas organizadas por dimensões permite agrupar métricas por diferentes tipos de entidade, como produto, desenvolvedor e aplicativo de API.

O URL da solicitação para a API Get metrics é:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats

Para a API Receber métricas organizadas por dimensões, inclua um recurso adicional no URL depois de /stats que especifique a dimensão desejada:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/dimension

Por exemplo, se quiser ver métricas agrupadas por proxy de API, use o seguinte URL para chamar a API de gerenciamento:

https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/stats/apiproxy

Como especificar as métricas que serão retornadas

Para as APIs Receber métricas e Receber métricas organizadas por dimensões, você usa o parâmetro de consulta select para especificar o parâmetro metrics a ser recuperado e uma função de agregação opcional, no formato:

?select=metric

ou

?select=aggFunction(metric)

Em que:

  • métrica especifica os dados que você quer retornar. Por exemplo, o número de solicitações de API, ocorrências em cache ou erros de política. Consulte as metrics na tabela que especifica o nome da métrica que será usada com o parâmetro de consulta select;
  • aggFunction especifica a função de agregação opcional executada com base na métrica. Por exemplo, é possível usar as seguintes funções de agregação com a métrica de latência de processamento:

    • avg: retorna a latência média de processamento.
    • min: retorna a latência mínima de processamento.
    • max: retorna a latência máxima de processamento.
    • sum: retorna a soma de todas as latências de processamento.

    Algumas métricas não aceitam todas as funções de agregação. A documentação sobre metrics inclui uma tabela que especifica o nome da métrica e a função (sum, avg, min, max) que ela aceita.

Por exemplo, para retornar o número médio de transações, ou seja, solicitações de proxy de API, por segundo:

?select=tps

Para este exemplo, não é necessária uma função de agregação. No próximo exemplo, usamos uma função de agregação para retornar a soma das ocorrências em cache:

?select=sum(cache_hit)

É possível retornar várias métricas para uma única chamada de API. Para ver as métricas da soma dos erros de política e do tamanho médio da solicitação, defina o parâmetro de consulta select usando uma lista de métricas separadas por vírgulas:

?select=sum(policy_error),avg(request_size)

Como especificar o período

A API Metrics retorna dados referentes a um período especificado. Use o parâmetro de consulta timeRange para especificar o período, no formato:

?timeRange=MM/DD/YYYY%20HH:MM~MM/DD/YYYY%20HH:MM

Observe o %20 antes de HH:MM. O parâmetro timeRange requer um caractere de espaço codificado por URL antes de HH:MM, ou um caractere +, como em: MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM.

Exemplo:

?timeRange=03/01/2018%2000:00~03/30/2018%2023:59

Não use 24:00 como horário, porque ele volta para 00:00. Use 23:59 no lugar dele.

Como usar um delimitador

Para separar várias dimensões em uma chamada de API, use uma vírgula (,) como delimitador. Por exemplo, na chamada de API,

curl https://api.enterprise.apigee.com/v1/o/myorg/e/prod/stats/apis,apps?select=sum(message_count)&timeRange=9/24/2018%2000:00~10/25/2018%2000:00&timeUnit=day

as dimensões apis e apps são separadas por ,.

Exemplos de chamadas de API

Esta seção contém exemplos usando as APIs Receber métricas e Receber métricas organizadas por dimensões . Consulte exemplos da API Metrics para mais exemplos.

Retornar o número total de chamadas feitas às APIs por um mês

Para ver o número total de chamadas feitas para todas as APIs em sua organização e o ambiente para um mês, use a API Receber métricas:

curl -v "https://api.enterprise.apigee.com/v1/o/{org}/e/{env}/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
-u email:password

Exemplo de resposta:

{
  "environments": [
    {
      "metrics": [
        {
          "name": "sum(message_count)",
          "values": [
            "7.44944088E8"
          ]
        }
      ],
      "name": "prod"
    }
  ],
...
}

Retornar a contagem total de mensagens por proxy de API por dois dias

Neste exemplo, são retornadas as métricas para o número de solicitações recebidas por todos os proxies de API em um período de dois dias. O parâmetro de consulta select define a função agregada sum para a métrica message_count na dimensão apiproxy. O relatório retorna a capacidade das mensagens de solicitação para todas as APIs para tráfego recebido entre o início de 20/06/2018 e o final de 21/06/2018, no fuso UTC:

curl  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
-u email:password

Exemplo de resposta:

{
  "environments" : [ {
    "dimensions" : [ {
      "metrics" : [ {
        "name" : "sum(message_count)",
        "values" : [ {
          "timestamp" : 1498003200000,
          "value" : "1100.0"
        } ]
      } ],
      "name" : "target-reroute"
    } ],
    "name" : "test"
  } ]...
}

Essa resposta indica que 1100 a mensagem foi recebida por um proxy de API chamado "target-reroute" em execução no ambiente de teste entre o início de 20/06/2018 e o final de 21/06/2018.

Para ver as métricas de outras dimensões, especifique uma dimensão diferente como o parâmetro do URI. Por exemplo, é possível especificar a dimensão developer_app para recuperar métricas de apps de desenvolvedores. A seguinte chamada de API retorna a capacidade total (mensagens recebidas) de qualquer aplicativo no intervalo de tempo especificado:

curl  https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
-u email:password

Exemplo de resposta:

{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "886.0"
                }
              ]
            }
          ],
          "name": "Test-App"
        },
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "6645.0"
                }
              ]
            }
          ],
          "name": "johndoe_app"
        },
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1498003200000,
                  "value": "1109.0"
                }
              ]
            }
          ],
          "name": "marys_app"
        }
  ]...
}

Como classificar os resultados por classificação relativa

Muitas vezes, ao gerar métricas, você quer ver apenas os resultados de um subconjunto do total de dados. Normalmente, você precisa dos resultados com os "10 melhores", por exemplo, as "10 APIs mais lentas" ou os "10 apps mais ativos". Para isso, use o parâmetro de consulta topk como parte da solicitação.

Por exemplo, talvez você queira saber quem são seus principais desenvolvedores, medidos por capacidade ou quais são as APIs de destino com pior desempenho (ou seja, (ou seja, "mais lentas") por latência.

Com o topk (entidades "top k"), você pode gerar relatórios sobre as entidades associadas ao valor mais alto de uma determinada métrica. Isso permite filtrar métricas para uma lista de entidades que exemplificam uma condição específica. Por exemplo, para descobrir qual URL de destino teve a maior probabilidade de erro na última semana, o parâmetro topk é anexado à solicitação, com um valor 1:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&topk=1" \
  -u email:password
{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(is_error)",
              "values": [
                {
                  "timestamp": 1494201600000,
                  "value": "12077.0"
                }
              ]
            }
          ],
          "name": "http://api.company.com"
        }
      ]...
}

O resultado dessa solicitação é um conjunto de métricas que mostra que o URL de destino mais problemático é http://api.company.com.

Também é possível usar o parâmetro topk para classificar as APIs com a maior capacidade. O exemplo a seguir recupera métricas na API com melhor classificação, definidas pela capacidade mais alta na última semana:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(message_count)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=day&sortby=sum(message_count)&sort=DESC&topk=1" \
-u email:password

Exemplo de resposta

{
  "environments": [
    {
      "dimensions": [
        {
          "metrics": [
            {
              "name": "sum(message_count)",
              "values": [
                {
                  "timestamp": 1494720000000,
                  "value": "5750.0"
                },
                {
                  "timestamp": 1494633600000,
                  "value": "5752.0"
                },
                {
                  "timestamp": 1494547200000,
                  "value": "5747.0"
                },
                {
                  "timestamp": 1494460800000,
                  "value": "5751.0"
                },
                {
                  "timestamp": 1494374400000,
                  "value": "5753.0"
                },
                {
                  "timestamp": 1494288000000,
                  "value": "5751.0"
                },
                {
                  "timestamp": 1494201600000,
                  "value": "5752.0"
                }
              ]
            }
          ],
          "name": "testCache"
        }
      ],
      "name": "test"
    }
  ]...
}

Como filtrar resultados

Para maior granularidade, filtre os resultados para limitar os dados retornados. Ao usar filtros, é preciso usar dimensões como propriedades de filtro.

Por exemplo, suponha que você precise recuperar uma contagem de erros de serviços de back-end filtrados pelo verbo HTTP da solicitação. Sua meta é descobrir quantas solicitações POST e PUT estão gerando erros por serviço de back-end. Para fazer isso, use a dimensão target_url com o filtro request_verb:

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/target_url?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&filter=(request_verb%20in%20'POST','PUT')" \
-u email:password

Exemplo de resposta:

{
  "environments" : [
    {
      "dimensions" : [
        {
          "metrics" : [
            {
              "name" : "sum(is_error)",
              "values" : [
                {
                  "timestamp" : 1519516800000,
                  "value" : "1.0"
                }
              ]
          }
        ],
        "name" : "testCache"
        }
      ],
      "name" : "test"
    }
  ]...
}

Paginação de resultados

Em ambientes de produção, algumas solicitações à API Edge Analytics retornam conjuntos de dados muito grandes. Para facilitar a exibição de conjuntos de dados grandes no contexto de um aplicativo baseado em IU, a API oferece suporte nativo à paginação.

Para paginar os resultados, use os parâmetros de consulta offset e limit e o parâmetro de classificação sortby para garantir uma ordem consistente dos itens.

Por exemplo, a seguinte solicitação provavelmente retornará um grande conjunto de dados, porque recupera métricas de todos os erros em todas as APIs no ambiente do produto na última semana.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
-u email:password

Se seu aplicativo baseado em IU puder exibir 50 resultados por página, defina o limite como 50. Como 0 conta como o primeiro item, a chamada a seguir retorna itens de 0 a 49 em ordem decrescente (sort=DESC é o padrão).

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=0" \
-u email:password

Para a segunda "página" de resultados, use o parâmetro de consulta de deslocamento da seguinte maneira. Observe que o limite e o deslocamento são idênticos. Isso porque 0 conta como o primeiro item. Com um limite de 50 e um deslocamento de 0, os itens de 0 a 49 são retornados. Com um deslocamento de 50, os itens de 50 a 99 são retornados.

curl https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env}/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)&limit=50&offset=50" \
-u email:password