Menggunakan API metrik

Anda sedang melihat dokumentasi Apigee Edge.
Buka Dokumentasi Apigee X.
info

Apigee Edge merekam berbagai data operasional dan bisnis yang mengalir di seluruh API. Metrik yang berasal dari data ini adalah berguna untuk pemantauan operasional dan pemantauan bisnis. Menggunakan Analisis Edge API, Anda dapat, untuk menentukan API mana yang berperforma baik atau buruk, developer mana yang memberikan traffic bernilai tertinggi, dan aplikasi mana yang menyebabkan masalah terbanyak untuk layanan backend.

Untuk membantu mengakses data metrik ini dengan mudah, Edge mengekspos RESTful API. Anda dapat gunakan Metrics API saat Anda perlu mengotomatiskan fungsi Analytics tertentu, seperti mengambil metrik secara berkala menggunakan klien atau skrip otomatisasi. Anda juga dapat menggunakan API ini untuk membuat visualisasi dalam bentuk widget khusus yang dapat Anda sematkan di portal atau aplikasi khusus.

Untuk mempelajari cara menggunakan Analytics di API UI pengelolaan edge, lihat Ringkasan Analisis API.

Tentang API metrik

Edge menyediakan dua API metrik:

  • Mendapatkan metrik menampilkan metrik untuk organisasi dan lingkungan selama jangka waktu tertentu, misalnya satu jam, hari, atau minggu.

    Misalnya, untuk minggu sebelumnya, Anda ingin mendapatkan:

    • Jumlah error kebijakan
    • Waktu respons rata-rata
    • Total traffic
  • Membuat metrik diatur menurut dimensi menampilkan metrik selama jangka waktu tertentu untuk organisasi dan lingkungan yang dikelompokkan berdasarkan dimensi.

    Misalnya, untuk minggu sebelumnya, Anda menggunakan dimensi untuk mengelompokkan metrik menurut produk API, proxy API, dan email developer untuk mendapatkan:

    • Jumlah error kebijakan per produk API
    • Waktu respons rata-rata per proxy API
    • Total traffic per email developer

    Opsi Membuat metrik diatur menurut dimensi API mendukung fitur tambahan yang tidak didukung oleh metrik Get API, yang mencakup:

Tentang kuota API metrik

Edge menerapkan kuota berikut pada panggilan ini. Kuota didasarkan pada sistem backend yang menangani panggilan:

  • Postgres: 40 panggilan per menit
  • BigQuery: 12 panggilan per menit

Tentukan sistem backend yang menangani panggilan dengan memeriksa objek respons. Setiap objek respons berisi properti metaData yang mencantumkan layanan yang menangani panggilan di properti Source. Misalnya, untuk Postgres:

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

Untuk BigQuery, properti Source adalah:

"Source:Big Query"

Jika Anda melebihi kuota panggilan, API akan menampilkan respons HTTP 429.

Mendapatkan metrik dengan API pengelolaan

Perbedaan utama antara kedua API tersebut adalah Mendapatkan metrik menampilkan metrik mentah untuk seluruh organisasi dan lingkungan, sekaligus Membuat metrik diatur menurut dimensi memungkinkan Anda mengelompokkan metrik menurut jenis entity yang berbeda, seperti produk API, developer, dan aplikasi.

URL permintaan untuk Get metrics API adalah:

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

Untuk kolom Mendapatkan metrik yang diatur berdasarkan dimensi API, Anda harus menyertakan resource tambahan ke URL setelah /stats yang menentukan dimensi yang diinginkan:

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

Misalnya, untuk mendapatkan metrik yang dikelompokkan menurut proxy API, gunakan URL berikut untuk memanggil API pengelolaan:

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

Menentukan metrik yang akan ditampilkan

Untuk keduanya Mendapatkan metrik dan Membuat metrik diatur menurut dimensi API yang Anda gunakan dengan parameter kueri select untuk menentukan metrik untuk diambil, dan fungsi agregasi opsional, dalam bentuk:

?select=metric

atau:

?select=aggFunction(metric)

Dengan keterangan:

  • metric menentukan data yang ingin Anda tampilkan. Misalnya, jumlah permintaan API, cache ditemukan, atau error kebijakan. Lihat metrik untuk tabel yang menentukan nama metrik yang akan digunakan dengan parameter kueri select.
  • aggFunction menentukan fungsi agregasi opsional yang dijalankan terhadap metrik. Misalnya, Anda dapat menggunakan fungsi agregasi berikut dengan metrik latensi pemrosesan:

    • avg: Menampilkan latensi pemrosesan rata-rata.
    • min: Menampilkan latensi pemrosesan minimum.
    • max: Menampilkan latensi pemrosesan maksimum.
    • sum: Menampilkan jumlah semua latensi pemrosesan.

    Tidak semua metrik mendukung semua fungsi agregasi. Dokumentasi tentang metrics berisi tabel yang menentukan nama metrik dan fungsi (sum, avg, min, max) yang didukung oleh metrik.

Misalnya, untuk menampilkan jumlah rata-rata transaksi, artinya permintaan proxy API, per detik:

?select=tps

Perhatikan bahwa contoh ini tidak memerlukan fungsi agregasi. Contoh berikutnya menggunakan fungsi agregasi untuk menampilkan jumlah hit cache:

?select=sum(cache_hit)

Anda dapat menampilkan beberapa metrik untuk satu panggilan API. Untuk mendapatkan metrik jumlah error kebijakan dan ukuran permintaan rata-rata, setel parameter kueri select menggunakan parameter daftar metrik:

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

Menentukan jangka waktu

Metrik API menampilkan data selama jangka waktu tertentu. Menggunakan timeRange untuk menentukan periode waktu, dalam bentuk:

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

Perhatikan %20 sebelum HH:MM. Parameter timeRange memerlukan karakter spasi yang dienkode URL sebelum HH:MM, atau karakter +, seperti dalam: MM/DD/YYYY+HH:MM~MM/DD/YYYY+HH:MM.

Contoh:

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

Jangan gunakan pukul 24.00 sebagai waktu karena akan membungkus pukul 00.00. Sebagai gantinya, gunakan 23:59.

Menggunakan {i>delimiter<i}

Untuk memisahkan beberapa dimensi dalam panggilan API, gunakan koma (,) sebagai pembatas. Misalnya, dalam panggilan 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

dimensi apis dan apps dipisahkan oleh ,.

Contoh panggilan API

Bagian ini berisi contoh penggunaan metrik Get dan Membuat metrik diatur menurut dimensi Google Cloud Platform. Lihat Contoh Metrics API untuk contoh tambahan.

Mengembalikan total jumlah panggilan yang dilakukan ke API Anda selama satu bulan

Untuk melihat jumlah total panggilan yang dilakukan ke semua API di organisasi dan lingkungan Anda selama satu bulan, gunakan 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

Contoh Respons:

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

Menampilkan total jumlah pesan per proxy API selama dua hari

Dalam contoh ini, Anda menampilkan metrik untuk jumlah permintaan yang diterima oleh semua proxy API selama periode dua hari. Parameter kueri select menentukan fungsi agregat sum untuk metrik message_count pada dimensi apiproxy. Laporan ini menampilkan throughput pesan permintaan untuk semua API untuk traffic yang diterima antara awal 20/6/2018 dan akhir 21/6/2018, di Waktu 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

Contoh Respons:

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

Respons ini menunjukkan bahwa 1100 pesan diterima oleh satu proxy API yang disebut 'target-ubah rute' berjalan di lingkungan pengujian antara awal 6/20/2018 dan akhir 21/6/2018.

Agar mendapatkan metrik untuk dimensi lain, tentukan dimensi yang berbeda sebagai parameter URI. Sebagai misalnya, Anda dapat menentukan dimensi developer_app untuk mengambil metrik untuk aplikasi developer lainnya. Panggilan API berikut menampilkan total throughput (pesan yang diterima) dari setiap aplikasi untuk interval waktu yang ditentukan:

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

Contoh Respons:

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

Mengurutkan hasil menurut peringkat relatif

Sering kali saat mendapatkan metrik, Anda hanya ingin mendapatkan hasil untuk sebagian dari kumpulan total layanan otomatis dan data skalabel. Biasanya, Anda perlu mendapatkan hasil untuk "10 teratas", misalnya, "10 teratas paling lambat API", "10 aplikasi paling aktif". Anda dapat melakukannya menggunakan parameter kueri topk sebagai bagian dari permintaan.

Misalnya, Anda mungkin tertarik untuk mengetahui siapa developer teratas Anda, yang diukur berdasarkan throughput, atau performa terburuk Anda (yaitu, API target 'paling lambat') didasarkan pada latensi.

topk (artinya entitas 'top k') memungkinkan pelaporan entitas yang terkait dengan nilai tertinggi untuk metrik tertentu. Hal ini memungkinkan Anda memfilter metrik untuk daftar entity yang menunjukkan kondisi tertentu. Misalnya, untuk menemukan URL target yang sebagian besar rentan error selama seminggu terakhir, parameter topk ditambahkan ke permintaan, dengan nilai 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"
        }
      ]...
}

Hasil permintaan ini adalah kumpulan metrik yang menunjukkan bahwa URL target yang paling bermasalah http://api.company.com.

Anda juga dapat menggunakan parameter topk untuk mengurutkan API yang mengalami yang konsisten. Contoh berikut mengambil metrik di API peringkat teratas, yang ditentukan oleh API throughput di minggu lalu:

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

Contoh Respons

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

Memfilter hasil

Untuk tingkat perincian yang lebih besar, Anda dapat memfilter hasil untuk membatasi data yang ditampilkan. Saat menggunakan filter, Anda harus menggunakan dimensi sebagai properti filter.

Misalnya, anggaplah Anda perlu mengambil jumlah error dari layanan backend. difilter oleh kata kerja HTTP permintaan. Sasaran Anda adalah mencari tahu berapa banyak permintaan POST dan PUT menghasilkan error per layanan backend. Untuk melakukannya, gunakan dimensi target_url bersama dengan filter 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

Contoh respons:

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

Memberi nomor halaman pada hasil

Dalam lingkungan produksi, beberapa permintaan ke API analisis Edge menampilkan data yang sangat besar yang sudah ditetapkan. Untuk memudahkan tampilan {i>dataset<i} besar dalam konteks aplikasi berbasis UI, API secara native mendukung penomoran halaman.

Untuk memberi nomor halaman pada hasil, gunakan parameter kueri offset dan limit, bersama dengan parameter pengurutan sortby untuk memastikan pengurutan yang konsisten item.

Misalnya, permintaan berikut cenderung mengembalikan set data yang besar, karena mengambil metrik untuk semua error pada semua API di lingkungan produk selama seminggu terakhir.

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

Jika aplikasi berbasis UI dapat menampilkan 50 hasil per halaman secara wajar, Anda dapat menetapkan batas menjadi 50. Karena 0 dihitung sebagai item pertama, panggilan berikut mengembalikan item 0-49 dalam urutan menurun (sort=DESC adalah default).

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

Untuk 'halaman' kedua hasil, gunakan parameter kueri offset, sebagai berikut. Perhatikan bahwa {i> limit <i}dan {i>offset <i}adalah identik. Itu karena 0 dihitung sebagai item pertama. Dengan batas maksimal 50 karakter, offset 0, item 0-49 dikembalikan. Dengan offset 50, item 50-99 akan dikembalikan.

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