Informes de telemetría

Introducción

En esta página, se describe cómo usar la API de Control de servicios v2 para informes de telemetría de servicios administrados que están integrados con Service Infrastructure. Está dirigido a los productores de servicios que desean integrar sus servicios por completo a Google Cloud.

Service Infrastructure es una plataforma fundamental para que los desarrolladores produzcan, administren, protejan y consuman las API y los servicios. Utiliza un modelo de uso de servicio simple y genérico: un consumidor consume un servicio que administra un productor. Todas las API de Google y las API de Google Cloud usan este modelo, ya que también se compilan en Service Infrastructure.

Cuando un consumidor accede a un servicio, el servicio informa los datos de telemetría relevantes a la plataforma, por lo que el consumidor y el productor pueden observar el acceso. Con Service Infrastructure, este proceso se denomina informes de telemetría, que incluye estadísticas, auditoría, facturación, registro y supervisión.

API de Control de servicios v2

La API de Control de servicios v2 proporciona un método services.report sencillo que proporciona informes de telemetría a todos los servicios integrados con Service Infrastructure. Este método le permite hacer las siguientes tareas en una sola llamada al método:

  • Análisis
  • En auditoría
  • Facturación
  • Logging
  • Supervisión

Cuando un servicio informa datos de telemetría a la API de Control de servicios, estos se distribuyen al consumidor, al productor o a ambos, según la configuración del servicio. Para obtener más información sobre la configuración de la telemetría, consulta las secciones de registro y supervisión de google.api.Service.

Para que un servicio llame a la API de Control de servicios, el productor debe habilitar esta API en el proyecto del productor y el emisor debe tener los permisos correspondientes en el servicio. Para obtener más información, consulta Introducción y Control de acceso a la API de Control de servicios de las API de Cloud.

Atributos de solicitud

Cuando un cliente accede a un servicio, este debe modelar el acceso en términos de un conjunto de solicitudes a la API y describir cada solicitud con un AttributeContext.

Para informar las métricas de la API con la API de Control de servicios, el servicio debe llamar al método services.report para cada solicitud con lo siguiente atributos. La API de Control de servicios generará las métricas de API y las enviará a Cloud Monitoring.

Atributo Descripción Ejemplo
origin.ip La dirección IP del emisor de la llamada. “1.2.3.4”
api.service El nombre del servicio de API. "endpointsapis.appspot.com"
api.operation El nombre del método de la API. "google.example.hello.v1.HelloService.GetHello"
api.version La string de versión de la API. "v1"
api.protocol El nombre del protocolo de la API. "https"
request.id Un ID de solicitud único. "123e4567-e89b-12d3-a456-426655440000"
request.time La marca de tiempo de la solicitud. "2019-07-31T05:20:00Z"
request.method El nombre del método HTTP. "POST"
request.scheme El esquema de URL. "https"
request.host El encabezado del host HTTP. "endpointsapis.appspot.com"
request.path La ruta de URL. "/v1/hello"
response.code El código de estado de la respuesta. 200
response.size El tamaño de la respuesta en bytes. 100
response.time La marca de tiempo de la respuesta. "2019-07-31T05:20:02Z"
response.headers["x-backend-latency"] La latencia del backend en segundos. "0.007"

Realiza informes de telemetría

Una vez que hayas implementado la configuración de servicio en la API de Administración de servicios y tu servicio esté listo a fin de entregar solicitudes de clientes, puedes comenzar a llamar a services.report para tu servicio implementado. Debes llamar a services.report para realizar informes de telemetría después de que el servicio reciba una solicitud.

Para experimentar rápidamente con los informes de telemetría, puedes usar el comando gcurl a fin de llamar al método services.report. Consulta Comienza a usar la API de Control de servicios para conocer los pasos de configuración iniciales.

En el siguiente ejemplo, se muestra cómo usar el comando gcurl para llamar a services.report a través de 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",
      "headers": {
        "x-backend-latency": "0.007"
      }
    },
    "destination": {
      "region_code": "us-central1"
    }
    "resource": {
      "name": "projects/123/locations/us-central1/workspaces/default"
    }
  }]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:report

Si se ejecuta de forma correcta, la respuesta del método services.report debe estar vacía. Si se produce un error, el error de API contiene información detallada del error. Para obtener más información sobre el manejo de errores, consulta la Guía de diseño de API > Errores.

Para los servicios de producción, debe usar una de las bibliotecas cliente proporcionadas por Google para llamar a la API de Control de servicios. Dichas bibliotecas proporcionan una gran usabilidad y manejan funciones comunes automáticamente, como la autenticación. Para obtener más información, consulte Explicación de las bibliotecas cliente.