Pelaporan Telemetri

Pengantar

Halaman ini menjelaskan cara menggunakan Service Control API v2 untuk pelaporan telemetri bagi layanan terkelola yang terintegrasi dengan Infrastruktur Layanan. Fitur ini ditujukan bagi produsen layanan yang ingin mengintegrasikan layanan mereka secara mendalam dengan Google Cloud.

Infrastruktur Layanan adalah platform dasar bagi developer untuk memproduksi, mengelola, mengamankan, dan menggunakan API dan layanan. Model ini menggunakan model penggunaan layanan umum yang sederhana: konsumen menggunakan layanan yang dikelola oleh produsen. Semua Google API dan Google Cloud API menggunakan model ini, karena juga dibuat di atas Infrastruktur Layanan.

Saat konsumen mengakses layanan, layanan tersebut akan melaporkan data telemetri yang relevan ke platform, sehingga konsumen dan produsen dapat mengamati akses tersebut. Dengan Service Infrastructure, proses ini disebut pelaporan telemetri, yang mencakup analisis, audit, penagihan, logging, dan pemantauan.

API Kontrol Layanan v2

Service Control API v2 menyediakan metode services.report sederhana yang menyediakan pelaporan telemetri ke semua layanan yang terintegrasi dengan Infrastruktur Layanan. Metode ini memungkinkan Anda melakukan hal berikut dalam satu panggilan metode:

  • Analisis
  • Pengauditan
  • Penagihan
  • Logging
  • Monitoring

Saat layanan melaporkan data telemetri ke Service Control API, data tersebut akan didistribusikan ke konsumen, atau produsen, atau keduanya, bergantung pada konfigurasi layanan. Untuk mengetahui informasi selengkapnya tentang cara mengonfigurasi telemetri, lihat bagian logging dan pemantauan google.api.Service.

Agar layanan dapat memanggil Service Control API, produser harus mengaktifkan Service Control API di project pembuat, dan pemanggil harus memiliki izin yang sesuai pada layanan. Untuk mengetahui informasi selengkapnya, lihat bagian Memulai Cloud API dan Kontrol Akses Service Control API.

Atribut permintaan

Saat klien mengakses layanan, layanan tersebut perlu membuat model akses tersebut dalam kaitannya dengan kumpulan permintaan API, dan mendeskripsikan setiap permintaan menggunakan AttributeContext.

Untuk melaporkan metrik API menggunakan Service Control API, layanan perlu memanggil metode services.report untuk setiap permintaan dengan atribut berikut. Service Control API akan menghasilkan metrik API dan mengirimkannya ke Cloud Monitoring.

Atribut Deskripsi Contoh
origin.ip Alamat IP pemanggil. "1.2.3.4"
api.service Nama layanan API. "endpointsapis.appspot.com"
api.operation Nama metode API. "google.example.hello.v1.HelloService.GetHello"
api.version String versi API. "v1"
api.protocol Nama protokol API. "https"
request.id ID permintaan unik. "123e4567-e89b-12d3-a456-426655440000"
request.time Stempel waktu permintaan. "2019-07-31T05:20:00Z"
request.method Nama metode HTTP. "POST"
request.scheme Skema URL. "https"
request.host Header host HTTP. "endpointsapis.appspot.com"
request.path Jalur URL. "/v1/halo"
response.code Kode status respons. 200
response.size Ukuran respons dalam byte. 100
response.time Stempel waktu respons. "2019-07-31T05:20:02Z"
response.backend_latency Latensi backend. "0,007 dtk"

Melakukan pelaporan telemetri

Setelah Anda men-deploy konfigurasi layanan ke Service Management API dan layanan Anda siap melayani permintaan dari klien, Anda dapat mulai memanggil services.report untuk layanan yang di-deploy. Anda harus memanggil services.report untuk melakukan pelaporan telemetri setelah layanan Anda menerima permintaan.

Untuk bereksperimen dengan pelaporan telemetri dengan cepat, Anda dapat menggunakan perintah gcurl untuk memanggil metode services.report. Lihat Mulai Menggunakan Service Control API untuk langkah-langkah penyiapan awal.

Contoh berikut menunjukkan cara menggunakan perintah gcurl untuk memanggil services.report melalui HTTP.

gcurl -d '{
  "service_config_id": "latest",
  "operations": [{
    "origin": {
      "ip": "1.2.3.4"
    },
    "api": {
      "service": "endpointsapis.appspot.com",
      "operation", "google.example.endpointsapis.v1.Workspaces.GetWorkspace",
      "version": "v1",
      "protocol": "https"
    },
    "request": {
      "id": "123e4567-e89b-12d3-a456-426655440000",
      "size": 50,
      "time": "2019-07-31T05:20:00Z",
    },
    "response": {
      "size": 100,
      "code": 200,
      "time": "2019-07-31T05:20:02Z",
      "backend_latency": "0.007s"
    },
    "destination": {
      "region_code": "us-central1"
    }
    "resource": {
      "name": "projects/123/locations/us-central1/workspaces/default"
    }
  }]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:report

Jika berhasil, respons dari metode services.report harus kosong. Jika gagal, error API akan berisi informasi error mendetail. Untuk informasi selengkapnya tentang penanganan error, lihat Panduan Desain API > Error.

Untuk layanan produksi, Anda harus menggunakan salah satu library klien yang disediakan Google untuk memanggil Service Control API. Library tersebut memberikan kegunaan yang sangat baik dan menangani fungsi umum secara otomatis, seperti autentikasi. Untuk informasi selengkapnya, lihat Penjelasan Library Klien.