Usar la API de Metrics

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

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

Para facilitar el acceso a estos datos de métricas, usa la API de métricas cuando necesites automatizar ciertas funciones de estadísticas, como recuperar métricas de forma periódica mediante un cliente o una secuencia de comandos de automatización. 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 Apigee, consulta Descripción general de Apigee Analytics.

Acerca de la API de Metrics

Existen dos formas de usar la API de Metrics:

Obtén métricas para una organización y un entorno durante un período, como una hora, un día o una semana. Este método muestra métricas sin procesar para toda la organización y el entorno.
Por ejemplo, de la semana anterior, quieres obtener lo siguiente:
- Cantidad de errores de políticas
- Tiempo de respuesta promedio
- Tráfico total
Obtener métricas organizadas por dimensión durante un período para una organización y un entorno.

Por ejemplo, para la semana anterior, puedes usar las dimensiones para agrupar las métricas por producto de API, proxy de API y correo electrónico de desarrollador (que también puede ser un ID de AppGroup) y obtener lo siguiente:
- Cantidad de errores de políticas por producto de API
- Tiempo de respuesta promedio por proxy de API
- Tráfico total por correo electrónico del desarrollador
La API de Metrics admite las siguientes funciones para administrar el resultado que se muestra:
Para obtener más información, consulta la referencia de la API de métricas.

Comienza a usar la API de Metrics

Esta es la URL de la solicitud para la API de Metrics:
```
https://apigee.googleapis.com/v1/organizations/$ORG/environments/$ENV/stats[dimension]
```
Por ejemplo, si quieres obtener métricas agrupadas por proxy de API, usa la siguiente URL para llamar a la API de 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
```
Omite la dimensión a fin de que se muestren métricas sin procesar para toda la organización y el entorno durante el 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
```
Especifica las métricas que se mostrarán

Usa el parámetro de consulta select a fin de especificar las métricas que se recuperarán y una función de agregación opcional en la forma siguiente:
```
?select=metric
```
o:
```
?select=aggFunction(metric)
```
Donde:
- 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 métricas 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.
  - p50: Muestra el percentil 50 para procesar latencias.
  - p95: Muestra el percentil 95 para procesar latencias.
  - p99: Muestra el percentil 99 para procesar latencias.
  No todas las métricas admiten todas las funciones de agregación. La documentación sobre métricas 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, que son las solicitudes de proxy de API, por segundo, ejecuta lo siguiente:
```
?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 (6 meses como máximo) 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.

Nota: Para obtener información sobre la duración de la retención de datos, consulta la página de planes de Apigee.

Ejemplos de cómo llamar a la API de Metrics

En esta sección, se proporcionan ejemplos con la API de Metrics. Consulta Ejemplos de API de Metrics para obtener ejemplos adicionales.
Muestra la cantidad total de llamadas realizadas a tus API durante un mes

Para mostrar la cantidad total de llamadas realizadas a todas las API en tu organización y entorno durante un mes, usa una llamada similar a la siguiente:
```
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"
```
En el ejemplo anterior, $TOKEN está configurado como tu token de acceso de OAuth 2.0, como se describe en Obtén un token de acceso de OAuth 2.0. Para obtener información sobre las opciones de curl que se usan en este ejemplo, consulta Usa curl. Para obtener una descripción de las variables de entorno utilizadas, consulta Configura variables de entorno para solicitudes a la API de Apigee.

A continuación, se proporciona un ejemplo de la respuesta.
```
{
  "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://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"
```
En el ejemplo anterior, $TOKEN está configurado como tu token de acceso de OAuth 2.0, como se describe en Obtén un token de acceso de OAuth 2.0. Para obtener información sobre las opciones de curl que se usan en este ejemplo, consulta Usa curl. Para obtener una descripción de las variables de entorno utilizadas, consulta Configura variables de entorno para solicitudes a la API de Apigee.

A continuación, se proporciona un ejemplo de la respuesta.
```
{
  "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.

Sugerencia: Ten en cuenta que la marca de tiempo, 1498003200000, está en formato de marca de tiempo Unix. Hay muchas herramientas de conversión de marca de tiempo Unix disponibles en Internet que puedes usar para decodificar estas marcas de tiempo.

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://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"
```
A continuación, se proporciona un ejemplo de la respuesta.
```
{
  "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://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"
```
En el ejemplo anterior, $TOKEN está configurado como tu token de acceso de OAuth 2.0, como se describe en Obtén un token de acceso de OAuth 2.0. Para obtener información sobre las opciones de curl que se usan en este ejemplo, consulta Usa curl. Para obtener una descripción de las variables de entorno utilizadas, consulta Configura variables de entorno para solicitudes a la API de Apigee.

A continuación, se proporciona un ejemplo de la respuesta.
```
{
  "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://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"
```
A continuación, se proporciona un ejemplo de la respuesta.
```
{
  "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 los servicios de backend que el verbo HTTP de la solicitud filtró. 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://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"
```
En el ejemplo anterior, $TOKEN está configurado como tu token de acceso de OAuth 2.0, como se describe en Obtén un token de acceso de OAuth 2.0. Para obtener información sobre las opciones de curl que se usan en este ejemplo, consulta Usa curl. Para obtener una descripción de las variables de entorno utilizadas, consulta Configura variables de entorno para solicitudes a la API de Apigee.

Nota: Debes ingresar el texto del filtro entre comillas simples, por ejemplo, 'POST'. No uses comillas dobles.

A continuación, se proporciona un ejemplo de la respuesta.
```
{
  "environments" : [
    {
      "dimensions" : [
        {
          "metrics" : [
            {
              "name" : "sum(is_error)",
              "values" : [
                {
                  "timestamp" : 1519516800000,
                  "value" : "1.0"
                }
              ]
          }
        ],
        "name" : "testCache"
        }
      ],
      "name" : "test"
    }
  ]...
}
```
Pagina los resultados

En entornos de producción, algunas solicitudes a la API de Analytics de Apigee 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.

Nota: Cuando paginas resultados, es importante ordenar los resultados de una manera predecible con el parámetro de búsqueda sortby. Si no se ordenan, los resultados se muestran en un orden impredecible, lo que vuelve inútil la paginación.
El valor sortby debe ser el mismo que se usa en el parámetro de búsqueda select. Por ejemplo, si select=sum(message_count), entonces sortby=sum(message_count).

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://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"
```
En el ejemplo anterior, $TOKEN está configurado como tu token de acceso de OAuth 2.0, como se describe en Obtén un token de acceso de OAuth 2.0. Para obtener información sobre las opciones de curl que se usan en este ejemplo, consulta Usa curl. Para obtener una descripción de las variables de entorno utilizadas, consulta Configura variables de entorno para solicitudes a la API de Apigee.

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://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 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://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"
```

Usar la API de Metrics

Acerca de la API de Metrics

Comienza a usar la API de Metrics

Especifica las métricas que se mostrarán

Especifica el período

Ejemplos de cómo llamar a la API de Metrics

Ordena los resultados según la clasificación relativa

Filtra resultados

Pagina los resultados