Relatório de telemetria

Alfa

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Introdução

Nesta página, veja como usar a API Service Control v2 para relatórios de telemetria de serviços gerenciados integrados à infraestrutura de serviços. Ela é destinada a produtores de serviços que querem integrar profundamente os próprios serviços ao Google Cloud.

A infraestrutura de serviços é uma plataforma fundamental para os desenvolvedores produzirem, gerenciarem, protegerem e consumirem APIs e serviços. Ela usa um modelo de uso de serviço simples e genérico: um consumidor consome um serviço gerenciado por um produtor. Todas as APIs do Google e as APIs do Google Cloud usam esse modelo, pois também são construídas sobre a Service Control.

Quando um consumidor acessa um serviço, o serviço informa os dados de telemetria relevantes para a plataforma. Assim, o consumidor e o produtor podem observar o acesso. Com a infraestrutura de serviços, esse processo é chamado de relatório de telemetria, que inclui análise, auditoria, faturamento, geração de registros e monitoramento.

Observação :para ver a terminologia usada nesta página, consulte o Glossário da API.

API Service Control v2

A API Service Control v2 inclui um método services.report simples que fornece relatórios de telemetria a todos os serviços integrados à infraestrutura de serviços. Este método permite fazer o seguinte em uma única chamada de método:

• Análise
• Auditoria
• Faturamento
• Geração de registros
• Monitoramento

Quando um serviço informa dados de telemetria para a API Service Control, os dados são distribuídos para o consumidor, o produtor ou ambos, dependendo da configuração do serviço. Para ver mais informações sobre como configurar a telemetria, consulte as seções de geração de registros e monitoramento de google.api.Service.

Para que um serviço chame a API Service Control, o produtor precisa ativá-la no projeto do produtor e o autor da chamada precisa ter as permissões adequadas no serviço. Para mais informações, consulte Primeiros passos com APIs do Cloud e Controle de acesso à API Service Control.

Atributos de solicitação

Quando um cliente acessa um serviço, o serviço precisa modelar o acesso em termos de um conjunto de solicitações de API e descrever cada solicitação usando um AttributeContext.

Para relatar métricas da API usando a API Service Control, o serviço precisa chamar o método services.report para cada solicitação com os atributos abaixo. A API Service Control gera as métricas da API e as envia para o Cloud Monitoring.

Atributo	Descrição	Exemplo
origin.ip	O endereço IP do autor da chamada.	"1.2.3.4"
api.service	O nome do serviço da API.	"endpointsapis.appspot.com"
api.operation	O nome do método da API.	"google.example.hello.v1.HelloService.GetHello"
api.version	A string da versão da API.	"v1"
api.protocol	O nome do protocolo da API.	"https"
request.id	Um ID de solicitação exclusivo.	"123e4567-e89b-12d3-a456-426655440000"
request.time	O carimbo de data/hora da solicitação.	"2019-07-31T05:20:00Z"
request.method	O nome do método HTTP.	"POST"
request.scheme	O esquema de URL.	"https"
request.host	O cabeçalho do host HTTP.	"endpointsapis.appspot.com"
request.path	O caminho da URL.	"/v1/hello"
response.code	O código de status da resposta.	200
response.size	O tamanho da resposta em bytes.	100
response.time	O carimbo de data/hora da resposta.	"2019-07-31T05:20:02Z"
response.backend_latency	A latência do back-end.	"0,007s"

Como gerar relatórios de telemetria

Depois de implantar a configuração de serviço na API Service Infrastructure e o serviço estiver pronto para atender solicitações de clientes, você poderá começar a chamar services.report para o serviço implantado. Você precisa chamar services.report para gerar relatórios de telemetria depois que o serviço receber uma solicitação.

Para testar rapidamente o relatório de telemetria, use o comando gcurl para chamar o método services.report. Consulte Primeiros passos com a API Service Control para conhecer as etapas de configuração inicial.

O exemplo a seguir mostra como usar o comando gcurl para chamar services.report sobre 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 for bem-sucedida, a resposta do método services.report deverá estar vazia. Se falhar, o erro da API deverá conter informações detalhadas. Para mais informações sobre como lidar com erros, consulte o Guia de desenvolvimento da API > Erros.

Para serviços de produção, use uma das bibliotecas de clientes fornecidas pelo Google para chamar a API Service Control. Essas bibliotecas oferecem excelente usabilidade e lidam com funcionalidades comuns automaticamente, como autenticação. Para mais informações, veja as Explicações sobre bibliotecas de clientes.