Descripción general de la transferencia de OTLP

En este documento, se presenta el uso de la API de Telemetry (OTLP), telemetry.googleapis.com, que implementa el protocolo OpenTelemetry. La API de Telemetry te permite transferir datos de registro, métricas y seguimientos con formato OTLP a Google Cloud Observability:

Puedes enviar datos de telemetría a la API de Telemetry desde aplicaciones que usan SDKs o exportando desde un recopilador de OpenTelemetry.

Si usas Google Kubernetes Engine, puedes usar OpenTelemetry administrado para GKE en lugar de implementar y configurar de forma manual un recopilador de OpenTelemetry que use la API de Telemetry.

Compatibilidad con protocolos

El extremo OTLP admite todos los protocolos de transporte y serialización de OTLP, incluidos http/protobuf, http/json y grpc. Cuando exportas 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 Google Cloud proyecto. Por ejemplo, cuando usas recopiladores, por lo general, usas la extensión googleclientauth para autenticarte con las credenciales de Google.

Para obtener 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 muestra cómo configurar el exportador con tus Google Cloud Credenciales predeterminadas de la aplicación (ADC) y agregar una biblioteca de autenticación de Google específica del lenguaje a tu aplicación.

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

Transferencia de OTLP

En esta sección, se describe cómo se convierten tus datos de registro, 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, los datos de registro se convierten en entradas de registro de Cloud Logging log entries. 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 OTLP, consulta Asignación de atributos de OTLP a tipos de recursos.

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, 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 contiene 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 métricas de Prometheus solo funciona cuando se usa el recopilador de OpenTelemetry versión 0.140.0 o posterior.

Cuando las métricas se transfieren a Cloud Monitoring con un recopilador de OpenTelemetry y el exportador 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 al formato de series temporales 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 target_info métrica 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 etiquetas en Cloud Monitoring no admiten UTF-8 completo, los datos de métricas se pueden rechazar:

  • 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 métricas están en el 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_.]* se rechazan. Los únicos caracteres especiales permitidos en las claves de etiquetas están en el conjunto _.. Se permiten todos los caracteres especiales en los valores de etiquetas.

Para evitar el rechazo de tus métricas por estos motivos, usa la replace_pattern función 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.

El siguiente es un ejemplo de datos de seguimiento que se pueden enviar desde una aplicación a tu Google Cloud proyecto:

{
  "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 resourceSpans.resource.attributes.
  • El campo instrumentation_scope de cada intervalo contiene una copia de los datos 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 usas la API de Telemetry para transferir registros debido a un cambio en el volumen de registros.

Los cambios más grandes en el almacenamiento y la facturación de tu Google Cloud proyecto se producen cuando se cumple lo siguiente:

  • 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 alcance 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 recopilador de OpenTelemetry, como un procesador transform, para descartar los atributos de recursos o alcance innecesarios antes de exportar los datos.
  • Si no necesitas que los metadatos adicionales se conserven en el campo otel, usa la opción de asignación heredada, gcp.use_legacy_mapping, que evita que se propague el campo otel.

Facturación de datos de métricas

La facturación de las métricas de OTLP se contabiliza en la SKU "Muestras de Prometheus transferidas", la misma 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 registro, 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 registro, métricas y seguimientos. También puedes usar la página Observability Analytics para analizar tus datos de registro y seguimiento 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 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"}

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

  • Es posible que las métricas delta no se consulten correctamente en ciertas circunstancias, como deltas 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 los límites y las cuotas de la API de Cloud Logging.

  • Datos de métricas: Se aplican los límites y las cuotas 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 máximo de lote 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?