Rapporti di telemetria

Alfa

Questo prodotto o funzionalità sono soggetti ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Introduzione

Questa pagina descrive come utilizzare l'API Service Control v2 per i report di telemetria per i servizi gestiti integrati con Service Infrastructure. È destinata ai producer di servizi che vogliono integrare profondamente i propri servizi con Google Cloud.

Service Infrastructure è una piattaforma fondamentale per gli sviluppatori per produrre, gestire, proteggere e consumare API e servizi. Utilizza un modello di utilizzo dei servizi semplice e generico: un consumer utilizza un servizio gestito da un producer. Tutte le API di Google e le API di Google Cloud utilizzano questo modello, poiché sono anche basate su Service Infrastructure.

Quando un consumer accede a un servizio, il servizio segnala i dati di telemetria pertinenti alla piattaforma, in modo che sia il consumer sia il producer possano osservare l'accesso. Con Service Infrastructure, questo processo è chiamato report di telemetria e include analisi, controllo, fatturazione, logging e monitoraggio.

Nota: per la terminologia utilizzata in questa pagina, consulta Glossario delle API.

API Service Control v2

L'API Service Control v2 fornisce un semplice services.report metodo che fornisce report di telemetria a tutti i servizi integrati con Service Infrastructure. Questo metodo consente di eseguire le seguenti operazioni in una singola chiamata al metodo:

• Analytics
• Controllo
• Fatturazione
• Logging
• Monitoraggio

Quando un servizio segnala i dati di telemetria all'API Service Control, i dati vengono distribuiti al consumer, al producer o a entrambi, a seconda della configurazione del servizio. Per ulteriori informazioni sulla configurazione della telemetria, consulta le sezioni di logging e monitoraggio di google.api.Service.

Affinché un servizio possa chiamare l'API Service Control, il producer deve abilitare l'API Service Control nel progetto del producer e il chiamante deve disporre delle autorizzazioni appropriate per il servizio. Per ulteriori informazioni, consulta la sezione API Cloud Introduzione e Controllo degli accessi all'API Service Control.

Attributi della richiesta

Quando un client accede a un servizio, il servizio deve modellare l'accesso in termini di un insieme di richieste API e descrivere ogni richiesta utilizzando un AttributeContext.

Per segnalare le metriche API utilizzando l'API Service Control, il servizio deve chiamare il services.report metodo per ogni richiesta con i seguenti attributi. L'API Service Control genererà le metriche API e le invierà a Cloud Monitoring.

Attributo	Descrizione	Esempio
origin.ip	L'indirizzo IP del chiamante.	"1.2.3.4"
api.service	Il nome del servizio API.	"endpointsapis.appspot.com"
api.operation	Il nome del metodo API.	"google.example.hello.v1.HelloService.GetHello"
api.version	La stringa della versione dell'API.	"v1"
api.protocol	Il nome del protocollo API.	"https"
request.id	Un ID richiesta univoco.	"123e4567-e89b-12d3-a456-426655440000"
request.time	Il timestamp della richiesta.	"2019-07-31T05:20:00Z"
request.method	Il nome del metodo HTTP.	"POST"
request.scheme	Lo schema dell'URL.	"https"
request.host	L'intestazione host HTTP.	"endpointsapis.appspot.com"
request.path	Il percorso dell'URL.	"/v1/hello"
response.code	Il codice di stato della risposta.	200
response.size	Le dimensioni della risposta in byte.	100
response.time	Il timestamp della risposta.	"2019-07-31T05:20:02Z"
response.backend_latency	La latenza del backend.	"0.007s"

Eseguire report di telemetria

Dopo aver eseguito il deployment della configurazione del servizio nell'API Service Management e il servizio è pronto a gestire le richieste dei client, puoi iniziare a chiamare services.report per il servizio di cui hai eseguito il deployment. Devi chiamare services.report per eseguire i report di telemetria dopo che il servizio riceve una richiesta.

Per sperimentare rapidamente i report di telemetria, puoi utilizzare il comando gcurl per chiamare il metodo services.report. Per i passaggi di configurazione iniziali, consulta la sezione Introduzione all'API Service Control.

L'esempio seguente mostra come utilizzare il comando gcurl per chiamare services.report tramite 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

Se l'operazione ha esito positivo, la risposta del metodo services.report deve essere vuota. In caso di errore, l'errore API deve contenere informazioni dettagliate sull'errore. Per ulteriori informazioni sulla gestione degli errori, consulta la sezione Guida alla progettazione delle API > Errori.

Per i servizi di produzione, devi utilizzare una delle librerie client fornite da Google per chiamare l'API Service Control. Queste librerie offrono una grande usabilità e gestiscono automaticamente le funzionalità comuni, come l'autenticazione. Per ulteriori informazioni, consulta la sezione Spiegazione delle librerie client.