Como usar a API Metrics

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

A Apigee registra uma ampla variedade de dados operacionais e de negócios que são transmitidos pelas APIs. As métricas derivadas desses dados são úteis para monitoramento operacional e de negócios. Com o Apigee Analytics, é possível, por exemplo, determinar as APIs que têm um bom ou um mau desempenho, os desenvolvedores que enviam o tráfego de maior valor e os apps que causam mais problemas aos serviços de back-end.

Para acessar esses dados de métricas com facilidade, use a API Metrics quando precisar automatizar determinadas funções de análise, 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 IU da Apigee, consulte Visão geral do Apigee Analytics.

Sobre a API Metrics

Há duas maneiras de usar a API Metrics:

  • Conseguir as métricas de uma organização e ambiente durante um período, como uma hora, um dia ou uma semana. Esse método retorna métricas brutas para toda a organização e o ambiente.

    Por exemplo, você quer saber o seguinte em relação à semana anterior:

    • Número de erros de política
    • Tempo médio de resposta
    • Tráfego total

  • Recuperar as métricas organizadas por dimensão durante um período para uma organização e um ambiente.

    Por exemplo, em relação à semana anterior, é possível usar dimensões para agrupar as métricas por produto de API, proxy de API e e-mail do desenvolvedor para saber o seguinte:

    • Número de erros de política por produto de API
    • Tempo médio de resposta por proxy de API
    • Tráfego total por e-mail do desenvolvedor

    Para gerenciar o resultado retornado, a API Metrics é compatível com os seguintes recursos:

    Para mais informações, consulte a referência da API Metrics.

    Primeiros passos para usar a API Metrics

    O URL da solicitação da API Metrics é:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats[dimension]

    Por exemplo, para receber métricas agrupadas por proxy de API, use o seguinte URL para chamar a API da Apigee:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?timeRange=07/21/2018+00:00:00~08/23/2018+00:00:00

    Omita a dimensão para retornar as métricas brutas de toda a organização e o ambiente para o período especificado:

    https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats?timeRange=07/21/2019+00:00:00~08/23/2018+00:00:00

    Como especificar as métricas que serão retornadas

    Use o parâmetro de consulta select para especificar as métricas que serão recuperadas e uma função de agregação opcional no formato:

    ?select=metric

    Ou:

    ?select=aggFunction(metric)

    Em que:

    • metric 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 métricas 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.
      • p50: retorna o 50º percentil para latências de processamento.
      • p95: retorna o 95º percentil para latências de processamento.
      • p99: retorna o 99º percentil para latências de processamento.

      Algumas métricas não aceitam todas as funções de agregação. A documentação sobre métricas 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, as 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 (máximo de seis meses) para especificar o período, no seguinte 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.

    Por 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.

    Exemplos de como chamar a API Metrics

    Nesta seção, apresentamos exemplos que usam a API Metrics. Consulte Exemplos da API Metrics para mais exemplos.

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

    Para retornar o número total de chamadas feitas a todas as APIs da organização e do ambiente por um mês, use uma chamada semelhante à seguinte:

    curl -v "https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/?select=sum(message_count)&timeRange=03/01/2018%2000:00~03/31/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

    Veja a seguir um 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 de mensagens de solicitação de todas as APIs para o tráfego recebido entre o início de 20/06/2018 e o fim de 21/06/2018, no fuso horário UTC:

    curl  https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59" \
  -H "Authorization: Bearer $TOKEN"

    Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

    Veja a seguir um 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 1.100 a mensagens foram recebidas por um proxy de API chamado "target-reroute" executado no ambiente de teste entre o início de 20/06/2018 e o fim 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 app no período especificado:

    curl  https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/developer_app?"select=sum(message_count)&timeRange=06/20/2018%2000:00~06/21/2018%2023:59&timeUnit=day" \
  -H "Authorization: Bearer $TOKEN"

    Veja a seguir um 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 posiçã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, avaliados por capacidade, ou quais são as APIs de destino com pior desempenho (ou seja, "mais lentas") por latência.

    Com o topk (entidades "k melhores"), você gera relatórios sobre as entidades associadas ao valor mais alto de uma determinada métrica. Isso permite filtrar as métricas em 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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

    Veja a seguir um exemplo de resposta:

    {
  "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. No exemplo a seguir, são recuperadas as métricas da API com a melhor posição, definida pela capacidade mais alta na última semana:

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    Veja a seguir um 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, digamos 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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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')" \
  -H "Authorization: Bearer $TOKEN"

    Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

    Veja a seguir um 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 Analytics da Apigee 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 ela recupera as métricas de todos os erros em todas as APIs no ambiente do produto na última semana.

    curl https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats/apiproxy?"select=sum(is_error)&timeRange=05/08/2018%2000:00~05/15/2018%2000:00&timeUnit=week&sortby=sum(is_error)" \
  -H "Authorization: Bearer $TOKEN"

    Em que $TOKEN está definido como seu token de acesso OAuth 2.0, conforme descrito em Como receber um token de acesso OAuth 2.0. Para informações sobre as opções de curl usadas neste exemplo, consulte Como usar curl. Para uma descrição das variáveis de ambiente usadas, consulte Como definir variáveis de ambiente para solicitações de API da Apigee.

    Se seu aplicativo baseado em IU tiver capacidade para 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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"

    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://apigee.googleapis.com/v1/organizations/$ORG/environments/$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" \
  -H "Authorization: Bearer $TOKEN"