Usa las APIs de métricas

Estás consultando la documentación de Apigee Edge.
Consulta la documentación de Apigee X.
Información

Apigee Edge registra una amplia variedad de datos operativos y empresariales que fluyen a través de las APIs. Las métricas derivadas de estos datos son útiles para la supervisión operativa y de la empresa. Con las estadísticas de la API de Edge, puedes, por ejemplo, determinar qué APIs tienen un rendimiento bueno o deficiente, qué desarrolladores entregan el tráfico de mayor valor y qué apps causan la mayor cantidad de problemas para tus servicios de backend.

Para facilitar el acceso a estos datos de métricas, Edge expone una API de RESTful. Puedes usar la API de Metrics cuando necesites automatizar ciertas funciones de Analytics, como la recuperación de métricas periódicamente con un cliente de automatización o una secuencia de comandos. También puedes usar la API para compilar tus propias visualizaciones en forma de widgets personalizados que puedes incorporar en portales o apps personalizadas.

Si deseas obtener información para usar Analytics en la IU de administración de la API perimetral, consulta la Descripción general de las estadísticas de la API.

Acerca de las APIs de métricas

Edge proporciona dos APIs de métricas:

  • Get metrics muestra métricas para una organización y un entorno durante un período, como una hora, un día o una semana.

    Por ejemplo, de la semana anterior, quieres obtener lo siguiente:

    • La cantidad de errores de política
    • El tiempo de respuesta promedio
    • El tráfico total
  • Get metrics organized by dimensions muestra las métricas durante un período para una organización y un entorno agrupadas por dimensiones.

    Por ejemplo, en la última semana, usas dimensiones para agrupar métricas por producto de API, proxy de API y correo electrónico del desarrollador a fin de obtener lo siguiente:

    • La cantidad de errores relacionados con las políticas por producto de API
    • El tiempo de respuesta promedio por proxy de API
    • El tráfico total por correo electrónico del desarrollador

    La API de Obtener métricas organizadas por dimensiones admite funciones adicionales que no admite la API de Obtener métricas, como las siguientes:

Acerca de las cuotas de la API de Metrics

Edge aplica las siguientes cuotas en estas llamadas. La cuota se basa en el sistema de backend que controla la llamada:

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

Determina el sistema de backend que controla la llamada mediante el análisis del objeto de respuesta. Cada objeto de respuesta contiene una propiedad metaData que enumera el servicio que controló la llamada en la propiedad Source. Por ejemplo, para Postgres:

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

Para BigQuery, la propiedad Source es:

"Source:Big Query"

Si excedes la cuota de llamada, la API muestra una respuesta HTTP 429.

Obtén métricas con la API de Management

La principal diferencia entre las dos API es que la función Get metrics muestra métricas sin procesar para toda la organización y el entorno, mientras que Get metrics organized by dimensions te permite agrupar métricas por diferentes tipos de entidades, como productos de API, desarrolladores y aplicaciones.

La URL de solicitud para la API de Get metrics es la siguiente:

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

Para la API Get metrics organized by dimensions, debes incluir un recurso adicional en la URL después de /stats que especifica la dimensión deseada:

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

Por ejemplo, para obtener métricas agrupadas por proxy de API, debes usar la siguiente URL para llamar a la API de administración:

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

Especifica las métricas que se mostrarán

Para las API Get metrics y Get metrics organized by dimensions, se usa el parámetro de consulta select a fin de especificar metrics para recuperar y una función de agregación opcional, con el siguiente formato:

?select=metric

o:

?select=aggFunction(metric)

Aquí:

  • metric especifica los datos que deseas mostrar. Por ejemplo, la cantidad de solicitudes a la API, los aciertos de caché o los errores de políticas. Consulta metrics para ver una tabla que especifica el nombre de la métrica que se usará con el parámetro de búsqueda select.
  • aggFunction especifica la función de agregación opcional que se ejecuta en la métrica. Por ejemplo, puedes usar las siguientes funciones de agregación con la métrica de latencia de procesamiento:

    • avg: Muestra la latencia de procesamiento promedio.
    • min: Muestra la latencia de procesamiento mínima.
    • max: Muestra la latencia de procesamiento máxima.
    • sum: Muestra la suma de todas las latencias de procesamiento.

    No todas las métricas admiten todas las funciones de agregación. La documentación sobre metrics contiene una tabla que especifica el nombre de la métrica y la función (sum, avg, min y max) compatible con la métrica.

Por ejemplo, para mostrar la cantidad promedio de transacciones, es decir, solicitudes de proxy de la API, por segundo:

?select=tps

Ten en cuenta que este ejemplo no requiere una función de agregación. En el siguiente ejemplo, se usa una función de agregación para mostrar la suma de aciertos de caché:

?select=sum(cache_hit)

Puedes mostrar varias métricas para una sola llamada a la API. Para obtener las métricas de la suma de errores de política y el tamaño promedio de la solicitud, configura el parámetro de búsqueda select mediante una lista de métricas separadas por comas:

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

Especifica el período

La API de Metrics muestra datos durante un período especificado. Usa el parámetro de consulta timeRange para especificar el período en el siguiente formato:

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

Observa el %20 antes de HH:MM. El parámetro timeRange requiere un carácter de espacio con codificación URL antes de HH:MM o un carácter +, como en MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM.

Por ejemplo:

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

No uses 24:00 como hora, porque se ajusta a las 12:00 a.m. Utiliza 23:59 en su lugar.

Usa un delimitador

Para separar varias dimensiones en una llamada a la API, utiliza una coma (,) como delimitador. Por ejemplo, en la llamada a la 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

las dimensiones apis y apps están separadas por ,.

Llamadas a la API de muestra

En esta sección, se incluyen ejemplos de las API de Get metrics y Get metrics organized by dimensions. Consulta Ejemplos de API de métricas para obtener ejemplos adicionales.

Muestra la cantidad total de llamadas realizadas a tus API durante un mes

Para ver la cantidad total de llamadas realizadas a todas las API en tu organización y entorno durante un mes, usa la API Get metrics:

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

Respuesta de muestra:

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

Mostrar el recuento total de mensajes por proxy de API durante dos días

En este ejemplo, se muestran métricas sobre la cantidad de solicitudes recibidas por todos los proxies de API en un período de dos días. El parámetro de búsqueda select define la función agregada sum para la métrica message_count en la dimensión apiproxy. El informe muestra la capacidad de procesamiento del mensaje de solicitud para todas las API para el tráfico recibido entre el 20/6/2018 y el final del 21/6/2018, en hora 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

Respuesta de muestra:

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

Esta respuesta indica que se recibieron 1100 mensajes del proxy de la API "target-reroute" en el entorno de prueba entre el comienzo del 20/6/2018 y el final del 21/6/2018.

Si quieres obtener métricas para otras dimensiones, especifica una dimensión diferente como parámetro URI. Por ejemplo, puedes especificar la dimensión developer_app a fin de recuperar métricas de apps para desarrolladores. La siguiente llamada a la API muestra la capacidad de procesamiento total (mensajes recibidos) de cualquier app durante el intervalo de tiempo 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

Respuesta de muestra:

{
  "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"
        }
  ]...
}

Ordena los resultados según la clasificación relativa

Muchas veces, cuando obtienes métricas, solo deseas obtener resultados para un subconjunto del conjunto total de datos. Por lo general, debes obtener los resultados de las “10 apps principales”, por ejemplo, las “10 API más lentas” y las “10 apps más activas”. Puedes hacerlo mediante el parámetro de búsqueda topk como parte de la solicitud.

Por ejemplo, puedes conocer quiénes son tus mejores desarrolladores, según la capacidad de procesamiento, o cuáles son las peores API de destino (es decir, las "más lentas") según la latencia.

El topk (que significa las entidades “k superiores”) permite habilitar los informes en las entidades asociadas con el valor más alto para una métrica determinada. Esto te permite filtrar las métricas para obtener una lista de entidades que ejemplifican una condición en particular. Por ejemplo, para encontrar qué URL de destino fue la más propensa a errores durante la última semana, el parámetro topk se agrega a la solicitud con un valor de 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"
        }
      ]...
}

El resultado de esta solicitud es un conjunto de métricas que muestra que la URL de destino con más errores es http://api.company.com.

También puedes usar el parámetro topk a fin de ordenar las API que experimentan la capacidad de procesamiento más alta. En el ejemplo siguiente, se recuperan las métricas en la API de mayor clasificación, que se definió por la capacidad de procesamiento más alta de la ú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

Respuesta de muestra:

{
  "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"
    }
  ]...
}

Filtra resultados

Si deseas obtener un mayor nivel de detalle, puedes filtrar los resultados para limitar los datos que se muestran. Cuando usas filtros, debes usar dimensiones como propiedades del filtro.

Por ejemplo, supongamos que necesitas recuperar un recuento de errores de servicios de backend filtrados por el verbo HTTP de la solicitud. Tu objetivo es saber cuántas solicitudes POST y PUT generan errores por servicio de backend. Para hacerlo, usa la dimensión target_url junto con el 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

Respuesta de muestra:

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

Pagina los resultados

En los entornos de producción, algunas solicitudes a la API de Edge Analytics muestran conjuntos de datos muy grandes. Para facilitar la visualización de grandes conjuntos de datos en el contexto de una aplicación basada en IU, la API admite de forma nativa la paginación.

Para paginar los resultados, usa los parámetros de consulta offset y limit, junto con el parámetro de clasificación sortby a fin de garantizar un orden coherente de los elementos.

Por ejemplo, la siguiente solicitud es probable que muestre un conjunto de datos grande, ya que recupera las métricas de todos los errores de todas las API en el entorno del producto durante la ú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

Si tu aplicación basada en la IU puede mostrar de forma razonable 50 resultados por página, puedes establecer el límite en 50. Como 0 cuenta como el primer elemento, la siguiente llamada muestra de 0 a 49 elementos en orden descendente (sort=DESC es el valor predeterminado).

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 la segunda “página” de resultados, usa el parámetros de búsqueda de desplazamiento de la siguiente manera. Ten en cuenta que el límite y el desplazamiento son idénticos. Esto se debe a que 0 cuenta como el primer elemento. Con un límite de 50 y un desplazamiento de 0, se muestran los elementos del 0 al 49. Con un desplazamiento de 50, se muestran los elementos del 50 al 99.

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