Pelaporan Telemetri

Pengantar

Halaman ini menjelaskan cara menggunakan Service Control API v2 untuk pelaporan telemetri untuk layanan terkelola yang terintegrasi dengan Service Infrastructure. Tujuan penggunaan ini adalah untuk produsen layanan yang ingin mengintegrasikan layanannya secara mendalam dengan Google Cloud.

Service Infrastructure adalah platform dasar bagi developer untuk membuat, mengelola, mengamankan, dan menggunakan API serta layanan. API ini menggunakan model penggunaan layanan generik yang sederhana: konsumen menggunakan layanan yang dikelola oleh produsen. Semua Google API dan Google Cloud API menggunakan model ini, karena juga dibangun di atas Service Infrastructure.

Saat konsumen mengakses layanan, layanan 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.

Service Control API v2

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

  • Analytics
  • Pengauditan
  • Penagihan
  • Logging
  • Pemantauan

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

Agar layanan dapat memanggil Service Control API, produsen harus mengaktifkan Service Control API di project produsen, dan pemanggil harus memiliki izin yang tepat pada layanan. Untuk mengetahui informasi selengkapnya, lihat Mulai Menggunakan Cloud API dan Kontrol Akses Service Control API.

Atribut permintaan

Saat klien mengakses layanan, layanan perlu memodelkan akses dalam hal serangkaian permintaan API, dan mendeskripsikan setiap permintaan menggunakan AttributeContext.

Untuk melaporkan metrik API menggunakan Service Control API, layanan harus memanggil metode services.report untuk setiap permintaan dengan atribut berikut. Service Control API akan membuat 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/hello"
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 men-deploy konfigurasi layanan ke Service Management API dan layanan 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 cepat dalam pelaporan telemetri, 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 akan kosong. Jika gagal, error API akan berisi informasi error mendetail. Untuk mengetahui 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 fungsionalitas umum secara otomatis, seperti autentikasi. Untuk mengetahui informasi selengkapnya, lihat Penjelasan Library Klien.