Pelaporan Telemetri

Pengantar

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

Infrastruktur Layanan adalah platform dasar bagi developer untuk membuat, mengelola, mengamankan, dan menggunakan API dan 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 API tersebut juga di-build di atas Infrastruktur Layanan.

Saat konsumen mengakses layanan, layanan akan melaporkan data telemetri yang relevan ke platform, sehingga konsumen dan produsen dapat mengamati akses tersebut. Dengan Infrastruktur Layanan, 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 memberikan pelaporan telemetri ke semua layanan yang terintegrasi dengan Infrastruktur Layanan. 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 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 di layanan. Untuk mengetahui informasi selengkapnya, lihat Memulai Cloud API dan Kontrol Akses Service Control API.

Atribut permintaan

Saat klien mengakses layanan, layanan tersebut perlu membuat model akses dalam hal kumpulan 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 pelaporan telemetri dengan cepat, Anda dapat menggunakan perintah gcurl untuk memanggil metode services.report. Lihat Mulai Menggunakan Service Control API untuk mengetahui 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 luar biasa dan menangani fungsi umum secara otomatis, seperti autentikasi. Untuk informasi selengkapnya, lihat Penjelasan Library Klien.