Compatibilidad con OTLP en Google Cloud Observability

Puedes transferir datos de registros, métricas y seguimientos con formato OTLP a Google Cloud Observability con la API de Telemetry (OTLP), que implementa el protocolo de OpenTelemetry. Esta API te permite recopilar telemetría independiente del proveedor de los SDKs y recopiladores de OpenTelemetry sin usar exportadores de Google Cloud personalizados.

Cuando envías telemetría a tu proyecto con la API de Telemetry, Google Cloud Observability procesa cada indicador de la siguiente manera:

  • Datos de registro: Convierte los registros de OTLP en entradas de registro y los enruta para su almacenamiento.
  • Datos de métricas: Asigna datos de métricas a series temporales de Prometheus en Cloud Monitoring.
  • Datos de seguimiento: Almacena seguimientos distribuidos en un formato que, por lo general, es coherente con OTLP.

Si ejecutas cargas de trabajo en Google Kubernetes Engine, puedes usar OpenTelemetry administrado para GKE en lugar de implementar y administrar de forma manual un recopilador de OpenTelemetry.

Compatibilidad con protocolos

El extremo de OTLP admite todos los protocolos de transporte y serialización de OTLP, incluidos http/protobuf, http/json y grpc. Cuando exportes directamente desde aplicaciones que usan SDKs, te recomendamos que uses el exportador de OTLP de gRPC en lugar de los exportadores de HTTP, ya que la mayoría de los exportadores de SDK no admiten la actualización dinámica de tokens.

Autenticación

Debes configurar tus exportadores con las credenciales necesarias para enviar datos a tu proyecto de Google Cloud . Por ejemplo, cuando usas recopiladores, por lo general, usas la extensión googleclientauth para autenticarte con las credenciales de Google.

Para ver un ejemplo de autenticación cuando se usa la exportación directa de datos de seguimiento, consulta Configura la autenticación. En este ejemplo, se ilustra cómo configurar el exportador con tus Google Cloud credenciales predeterminadas de la aplicación (ADC) y agregar una biblioteca de Google Auth específica del lenguaje a tu aplicación.

Para enviar datos de telemetría a tu proyecto de Google Cloud con la API de Telemetry, también debes hacer lo siguiente:

  • Configura un proyecto de cuota. Para obtener más información, consulta Configura el proyecto de cuota.

  • Otorga los siguientes roles de Identity and Access Management (IAM) al usuario o a la cuenta de servicio que usa la aplicación:

Transferencia de OTLP

En esta sección, se describe cómo se convierten tus datos de registros, métricas y seguimientos de OTLP en estructuras de datos de Google Cloud Observability.

Transferencia de datos de registro

Cuando usas la API de Telemetry para transferir registros con formato OTLP, tus datos de registro se convierten en entradas de registro de Cloud Logging. Una solicitud de registro entrante con formato OTLP en JSON tiene la siguiente estructura general:

"resourceLogs": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeLogs": [
        {
          "scope": { ...}
          "logRecords": [...]
        }
      ]
    }
]

Cada elemento de cada array logRecords se convierte en una sola entrada de registro de Cloud Logging. Los atributos resource determinan el recurso supervisado en el LogEntry resultante. Para obtener más información sobre qué atributos se requieren para la transferencia de registros con formato OTLP, consulta Asignación de atributos de OTLP al tipo de recurso.

Para admitir la transferencia de registros con formato OTLP, la estructura LogEntry de Cloud Logging contiene un campo adicional, otel. Debido a que los modelos de datos de OTLP y Cloud Logging difieren en la estructura, el campo otel conserva una copia de los metadatos de recursos, permisos y entidades de la solicitud de OTLP entrante.

Por ejemplo, si envías una carga útil de OTLP resourceLogs como la siguiente a la API de Telemetry, cada entrada de registro resultante contendrá un campo resource (para el recurso supervisado) y un campo otel, como se muestra en las otras pestañas:

resourceLogs 

{
  "resourceLogs": [
    {
      "resource": {
        "attributes": [
          {
            "key": "gcp.project_id",
            "value": { "stringValue": "PROJECT_ID" }
          },
          {
            "key": "gcp.resource_type",
            "value": { "stringValue": "global" }
          }
        ]
      },
      "scopeLogs": [
        {
          "scope": {
            "name": "my.library",
            "version": "1.0.0",
            "attributes": [
              {
                "key": "my.scope.attribute",
                "value": { "stringValue": "some scope attribute" }
              }
            ]
          },
          "logRecords": [ ... ]
         }
       ]
     }
   ]
}

resource 

  {
    ...
    "resource": {
      "labels": {
        "project_id": "PROJECT_ID"
      },
      "type": "global"
    },
    ...
}

otel 

  {
    ...
    "otel": {
      "resource": {
        "attributes": {
          "gcp.project_id": "PROJECT_ID",
          "gcp.resource_type": "global"
        }
      },
      "scope": {
        "attributes": {
          "my.scope.attribute": "some scope attribute"
        },
        "name": "my.library",
        "version": "1.0.0"
      }
    },
   ...
  }

Debido a que las entradas de registro de Cloud Logging son independientes y no se vinculan a esquemas de recursos externos, todos los metadatos de recursos, permisos y entidades de OTLP se copian en cada entrada de registro.

Transferencia de datos de métricas

OTLP para las métricas de Prometheus solo funciona cuando se usa la versión 0.140.0 o posterior del recopilador de OpenTelemetry.

Cuando las métricas se transfieren a Cloud Monitoring con un recopilador de OpenTelemetry y el exportador de otlphttp o se envían directamente con un SDK de OpenTelemetry, las métricas de OTLP se asignan a las estructuras de métricas de Cloud Monitoring. Para obtener información sobre esas asignaciones, consulta lo siguiente:

Google Cloud Observability convierte las métricas en el formato de serie temporal de Prometheus. Los nombres de las métricas no deben tener dominio o deben tener el dominio prometheus.googleapis.com. Después de la conversión, el nombre de la métrica incluye el prefijo prometheus.googleapis.com y un sufijo adicional, según el tipo de punto de OTLP. La métrica de Cloud Monitoring resultante tiene la siguiente estructura:

prometheus.googleapis.com/{metric_name}/{suffix}

Además, para cada recurso único de OpenTelemetry, la conversión agrega una métrica target_info que contiene todos los atributos de recursos, excepto service.name, service.instance.id y service.namespace.

Debido a que los nombres de las métricas y las claves de etiqueta en Cloud Monitoring no admiten UTF-8 completo, se pueden rechazar los datos de las métricas:

  • Se rechazan los nombres de métricas que no se ajustan a la expresión regular [a-zA-Z][a-zA-Z0-9_:./-]*. Los únicos caracteres especiales permitidos en los nombres de las métricas están en el conjunto _:./-.
  • Se rechazan los datos que contienen atributos (es decir, claves de etiqueta) que no se ajustan a la expresión regular [a-zA-Z_][a-zA-Z0-9_.]*. Los únicos caracteres especiales permitidos en las claves de etiqueta están en el conjunto _.. Se permiten todos los caracteres especiales en los valores de las etiquetas.

Para evitar que se rechacen tus métricas por estos motivos, usa la función replace_pattern para transformar los nombres y atributos de tus métricas.

Transferencia de datos de seguimiento

Independientemente de si usas la API de Telemetry o la API de Cloud Trace, los datos de seguimiento entrantes se almacenan en un formato coherente con OTLP. Sin embargo, te recomendamos que uses la API de Telemetry, ya que proporciona cuotas de transferencia más altas que la API de Cloud Trace.

A continuación, se muestra un ejemplo de datos de seguimiento que se podrían enviar desde una aplicación a tu proyecto de Google Cloud :

{
  "resourceSpans": [
    {
      "resource": {
        "attributes": [...]
      },
      "scopeSpans": [
        {
          "scope": { ...},
          "spans": [...]
        }
      ]
    }
  ]
}

Cada elemento de cada array scopeSpans.spans se convierte en un solo intervalo almacenado:

  • El campo resource de cada intervalo contiene una copia de los datos de resourceSpans.resource.attributes.
  • El campo instrumentation_scope de cada intervalo contiene una copia de los datos de scopeSpans.scope.
  • Cada intervalo corresponde a una entrada en el array scopeSpans.spans. Los campos, como traceId, spanId y kind, se asignan a campos con nombres similares en el esquema de seguimiento.

Para obtener más información, consulta los siguientes documentos:

Facturación

La facturación de los datos de registro, métricas y seguimientos que se transfieren con la API de Telemetry depende del indicador de telemetría. Para obtener información completa, consulta la página Facturación.

Facturación de datos de registro

Es posible que veas un cambio en los valores de almacenamiento y facturación de Cloud Logging cuando uses la API de Telemetry para transferir registros debido a un cambio en el volumen de registros.

Los cambios más importantes en el almacenamiento y la facturación de tu proyecto de Google Cloud se producen cuando se cumplen las siguientes condiciones:

  • El campo resource contiene atributos de alta cardinalidad o una gran cantidad de atributos. Estos atributos de recursos determinan el recurso supervisado en el LogEntry resultante.
  • El campo scopeLogs contiene una gran cantidad de elementos en los arrays logRecords. Los campos scopeLogs.scope se copian en el campo otel para cada entrada de registro individual.

Debido a que estos metadatos de recursos y permisos se copian en cada entrada de registro individual, el volumen de registros almacenados puede aumentar.

Para minimizar el volumen de almacenamiento, te recomendamos lo siguiente:

  • Usa un procesador de OpenTelemetry Collector, como un procesador transform, para descartar los atributos de recursos o permisos innecesarios antes de exportar los datos.
  • Si no necesitas que se conserven los metadatos adicionales en el campo otel, usa la opción de asignación heredada, gcp.use_legacy_mapping, que evita que se complete el campo otel.

Facturación de datos de métricas

La facturación de las métricas de OTLP se registra en el SKU "Muestras de Prometheus transferidas", el mismo que se usa para las métricas de Google Cloud Managed Service para Prometheus.

Facturación de datos de seguimiento

La API que usas para enviar datos de seguimiento a tu proyecto no afecta la forma en que se calculan los cargos por esos datos.

Consulta tus datos de registros, métricas y seguimientos

Puedes usar las páginas del explorador (Explorador de registros, Explorador de métricas y Explorador de seguimiento) para consultar tus datos de registros, métricas y seguimientos. También puedes usar la página Estadísticas de observabilidad para analizar tus datos de registros y seguimientos con SQL.

Las siguientes sugerencias pueden ser útiles cuando consultas tus datos de métricas con el Explorador de métricas:

  • Importante: Para consultar nombres de métricas y claves de etiquetas con caracteres especiales que no sean los dos puntos (:) y el guion bajo (_), debes unirlos entre llaves ({}) y comillas ("), según la especificación UTF-8 de PromQL. Por ejemplo, las siguientes son consultas válidas:

    • {"my.metric.name"}
    • {"my.metric.name", "label.key.KEY"="value"}

  • Conservar la etiqueta le cuando se consultan histogramas exponenciales puede devolver resultados inesperados. Se espera que las consultas histogram_quantile(.99, sum by (le) (metric)) más típicas funcionen.

  • Es posible que las métricas delta no se consulten correctamente en ciertas circunstancias, como las deltas muy dispersas.

Límites y cuotas

Los límites de la API de Telemetry se aplican a todos los tipos de indicadores.

También se aplican las siguientes cuotas y límites:

  • Datos de registro: Se aplican las cuotas y los límites de la API de Cloud Logging.

  • Datos de métricas: Se aplican las cuotas y los límites de la API de Cloud Monitoring. Por ejemplo, las métricas no pueden tener más de 200 etiquetas.

    La cuota predeterminada para las métricas transferidas por la API de Telemetry es de 60,000 solicitudes por minuto. Con un tamaño de lote máximo de 200 puntos por solicitud, esta cuota es una cuota predeterminada efectiva de 200,000 muestras por segundo. Puedes solicitar un aumento de la cuota.

  • Datos de seguimiento: No se aplican cuotas ni límites adicionales.

¿Qué sigue?