Используйте API метрик

Вы просматриваете документацию Apigee Edge .
Перейдите к документации Apigee X. информация

Apigee Edge записывает широкий спектр операционных и бизнес-данных, передаваемых через API. Метрики, полученные на основе этих данных, полезны для оперативного мониторинга и мониторинга бизнеса. Используя Edge API Analytics, вы можете, например, определить, какие API работают хорошо или плохо, какие разработчики предоставляют наиболее ценный трафик и какие приложения вызывают больше всего проблем для ваших серверных служб.

Чтобы облегчить доступ к этим данным метрик, Edge предоставляет RESTful API. Вы можете использовать API метрик, когда вам нужно автоматизировать определенные функции Analytics, например периодическое получение метрик с помощью клиента автоматизации или скрипта. Вы также можете использовать API для создания собственных визуализаций в виде пользовательских виджетов, которые можно встраивать в порталы или пользовательские приложения.

Чтобы узнать, как использовать Analytics в пользовательском интерфейсе управления API Edge, см. обзор API Analytics .

Об API метрик

Edge предоставляет два API метрик:

• Функция Get metrics возвращает метрики для организации и среды за определенный период времени, например за час, день или неделю.

  Например, за предыдущую неделю вы хотите получить:

  • Количество ошибок политики
  • Среднее время ответа
  • Общий трафик

• Получить метрики, организованные по измерениям, возвращает метрики за период времени для организации и среды , сгруппированные по измерениям .

  Например, за предыдущую неделю вы используете измерения для группировки показателей по продукту API, прокси-серверу API и адресу электронной почты разработчика, чтобы получить:

  • Количество ошибок политики на продукт API
  • Среднее время ответа на прокси-сервер API
  • Общий трафик на одно письмо разработчика

  API получения метрик, организованных по измерениям, поддерживает дополнительные функции, не поддерживаемые API получения метрик , в том числе:

  • Сортировка
  • Фильтрация
  • Пагинация

О квотах API метрик

Edge применяет следующие квоты для этих вызовов. Квота зависит от серверной системы, которая обрабатывает вызов:

• Postgres : 40 вызовов в минуту.
• BigQuery : 12 вызовов в минуту.

Определите серверную систему, которая обрабатывает вызов, исследуя объект ответа. Каждый объект ответа содержит свойство metaData , в котором в свойстве Source указана служба, которая обработала вызов. Например, для Postgres:

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

Для BigQuery свойство Source имеет следующий вид:

"Source:Big Query"

Если вы превысите квоту вызовов, API вернет ответ HTTP 429.

Получение метрик с помощью API управления

Основное различие между двумя API заключается в том, что Get metrics возвращает необработанные метрики для всей организации и среды, а Get metrics, организованные по измерениям , позволяет группировать метрики по различным типам объектов, например продукту API, разработчику и приложению.

URL-адрес запроса для API получения метрик :

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

Для API получения показателей, организованных по измерениям , вы включаете дополнительный ресурс в URL-адрес после /stats , который указывает желаемое измерение :

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

Например, чтобы получить метрики, сгруппированные по прокси-серверу API, вы должны использовать следующий URL-адрес для вызова API управления:

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

Указание возвращаемых показателей

Как для получения метрик , так и для Get метрик, организованных по измерениям API, вы используете параметр запроса select , чтобы указать извлекаемые метрики , а также дополнительную функцию агрегирования в форме:

?select=metric

или:

?select=aggFunction(metric)

Где:

• Метрика указывает данные, которые вы хотите вернуть. Например, количество запросов API, попаданий в кэш или ошибок политики. См. метрики для таблицы, в которой указано имя метрики, которое будет использоваться с параметром запроса select .

• aggFunction указывает дополнительную функцию агрегирования, выполняемую для метрики. Например, вы можете использовать следующие функции агрегирования с метрикой задержки обработки:

  • avg : Возвращает среднюю задержку обработки.
  • min : Возвращает минимальную задержку обработки.
  • max : Возвращает максимальную задержку обработки.
  • sum : Возвращает сумму всех задержек обработки.

  Не все метрики поддерживают все функции агрегирования. Документация по метрикам содержит таблицу, в которой указано имя метрики и функция ( sum , avg , min , max ), поддерживаемая метрикой.

Например, чтобы вернуть среднее количество транзакций, то есть запросов прокси-сервера API, в секунду:

?select=tps

Обратите внимание, что в этом примере не требуется функция агрегирования. В следующем примере используется функция агрегирования для возврата суммы попаданий в кэш:

?select=sum(cache_hit)

Вы можете вернуть несколько метрик для одного вызова API. Чтобы получить метрики для суммы ошибок политики и среднего размера запроса, задайте параметр запроса select , используя список метрик, разделенных запятыми:

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

Указание периода времени

API метрик возвращает данные за указанный период времени. Используйте параметр запроса timeRange , чтобы указать период времени в форме:

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

Обратите внимание на %20 перед HH:MM . Параметр timeRange требует, чтобы перед HH:MM был указан пробел в кодировке URL-адреса или символ + , например: MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM .

Например:

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

Не используйте в качестве времени 24:00, поскольку оно приближается к 00:00. Вместо этого используйте 23:59.

Использование разделителя

Чтобы разделить несколько измерений в вызове API, используйте запятую ( , ) в качестве разделителя. Например, в вызове 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

размеры apis и apps разделяются , .

Примеры вызовов API

В этом разделе приведены примеры использования метрик Get и метрик Get, организованных по API-интерфейсам измерений . Дополнительные примеры см. в разделе Примеры API метрик .

Возвращает общее количество вызовов ваших API за один месяц.

Чтобы просмотреть общее количество вызовов всех API-интерфейсов в вашей организации и среде за один месяц, используйте 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

Пример ответа:

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

Возвращает общее количество сообщений на каждый прокси-сервер API за два дня.

В этом примере вы возвращаете показатели количества запросов, полученных всеми прокси-серверами API за двухдневный период. Параметр запроса select определяет sum агрегатной функции для метрики message_count в измерении apiproxy . Отчет возвращает пропускную способность сообщений запросов для всех API для трафика, полученного в период с начала 20.06.2018 по конец 21.06.2018 по времени 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

Пример ответа:

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

Этот ответ указывает на то, что 1100 сообщений были получены одним прокси-сервером API под названием «target-reroute», работающим в тестовой среде в период с начала 20.06.2018 по конец 21.06.2018.

Чтобы получить метрики для других измерений, укажите другое измерение в качестве параметра URI. Например, вы можете указать измерение developer_app для получения показателей для приложений разработчика. Следующий вызов API возвращает общую пропускную способность (полученные сообщения) от любых приложений за указанный интервал времени:

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

Пример ответа:

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

Сортировка результатов по относительному рейтингу

Часто при получении метрик вы хотите получить результаты только для подмножества общего набора данных. Обычно вам нужно получить результаты по «топ-10», например, «топ-10 самых медленных API», «топ-10 самых активных приложений». Вы можете сделать это, используя параметр запроса topk как часть запроса.

Например, вам может быть интересно узнать, кто ваши лучшие разработчики, измеряемые по пропускной способности, или каковы ваши целевые API с наихудшими показателями (т. е. «самые медленные») по задержке.

topk (что означает «top k» объектов) позволяет создавать отчеты об объектах, связанных с самым высоким значением для данной метрики. Это позволяет фильтровать метрики для списка сущностей, которые иллюстрируют определенное условие. Например, чтобы определить, какой целевой URL-адрес был наиболее подвержен ошибкам за последнюю неделю, к запросу добавляется параметр topk со значением 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"
        }
      ]...
}

Результатом этого запроса является набор показателей, которые показывают, что целевой URL-адрес с наибольшей ошибкой — http://api.company.com .

Вы также можете использовать параметр topk для сортировки API с наибольшей пропускной способностью. В следующем примере извлекаются метрики API с самым высоким рейтингом, определяемого самой высокой пропускной способностью за последнюю неделю:

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

Пример ответа

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

Фильтрация результатов

Для большей детализации вы можете фильтровать результаты, чтобы ограничить возвращаемые данные. При использовании фильтров необходимо использовать размеры в качестве свойств фильтра.

Например, предположим, что вам нужно получить количество ошибок от серверных служб, отфильтрованных по HTTP-команде запроса. Ваша цель — выяснить, сколько запросов POST и PUT генерируют ошибки для каждой внутренней службы. Для этого вы используете измерение target_url вместе с фильтром 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

Пример ответа:

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

Разбивка на страницы результатов

В производственных средах некоторые запросы к API аналитики Edge возвращают очень большие наборы данных. Чтобы упростить отображение больших наборов данных в контексте приложения на основе пользовательского интерфейса, API изначально поддерживает нумерацию страниц.

Для разбивки результатов на страницы используйте параметры запроса offset и limit , а также параметр сортировки sortby , чтобы обеспечить согласованный порядок элементов.

Например, следующий запрос, скорее всего, вернет большой набор данных, поскольку он получает метрики для всех ошибок во всех API в среде продукта за последнюю неделю.

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

Если ваше приложение на основе пользовательского интерфейса может отображать 50 результатов на странице, вы можете установить ограничение на 50. Поскольку 0 считается первым элементом, следующий вызов возвращает элементы 0–49 в порядке убывания (по умолчанию используется sort=DESC ).

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

Для второй «страницы» результатов используйте параметр запроса смещения следующим образом. Обратите внимание, что предел и смещение идентичны. Это потому, что 0 считается первым элементом. При пределе 50 и смещении 0 возвращаются элементы 0–49. При смещении 50 возвращаются элементы 50–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