Compatibilidad con OTLP en Google Cloud Observability

Puedes transferir datos de registros, métricas y seguimientos con formato de OTLP a Google Cloud Observability con la API de Telemetría (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 Google Cloud exportadores 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: Almacenan seguimientos distribuidos en un formato que suele ser coherente con OTLP.

Si ejecutas cargas de trabajo en Google Kubernetes Engine, puedes usar OpenTelemetry administrado para GKE en lugar de implementar y administrar manualmente 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 idioma 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 al usuario o a la cuenta de servicio que usa la aplicación los siguientes roles de Identity and Access Management (IAM):

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 registros

Cuando usas la API de Telemetry para transferir registros con formato de 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 son necesarios para la transferencia de registros con formato de OTLP, consulta Asignación de atributos de OTLP a tipos de recursos.

Para admitir la transferencia de registros con formato de OTLP, la estructura LogEntry de Cloud Logging contiene un campo adicional, otel. Dado que los modelos de datos de OTLP y Cloud Logging difieren en estructura, el campo otel conserva una copia de los metadatos de recursos, alcance 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, alcance 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 se transfieren métricas a Cloud Monitoring con un recopilador de OpenTelemetry y el exportador otlphttp, o bien 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 al formato de series temporales de Prometheus. Los nombres de las métricas no deben tener ningún 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 del recurso, excepto service.name, service.instance.id y service.namespace.

Dado que los nombres de las métricas y las claves de etiquetas 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 cumplen con la expresión regular [a-zA-Z][a-zA-Z0-9_:./-]*. Los únicos caracteres especiales permitidos en los nombres de las métricas son los del conjunto _:./-.
  • Se rechazan los puntos de datos que contienen atributos (es decir, claves de etiquetas) que no cumplen con la expresión regular [a-zA-Z_][a-zA-Z0-9_.]*. Los únicos caracteres especiales permitidos en las claves de etiquetas son los del 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 seguimiento que se transfieren a través de la API de Telemetry depende del indicador de telemetría. Para obtener información completa, consulta la página de 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 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 objeto 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.

Dado que los metadatos de recursos y alcances se copian en cada entrada de registro individual, es posible que aumente el volumen de registros almacenados.

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

  • Usa un procesador de OpenTelemetry Collector, como un procesador transform, para descartar los atributos innecesarios de recursos o alcance 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 contabiliza 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.

Cómo consultar 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 de Observability Analytics para analizar tus datos de registros y seguimientos con SQL.

Las siguientes sugerencias pueden ser útiles cuando consultes 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 incluirlos 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 funcionen las búsquedas más típicas de histogram_quantile(.99, sum by (le) (metric)).

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

Límites y cuotas

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

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

  • 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 que se transfieren a través de 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?