Supervisa el rendimiento con registros del cliente

Vista previa

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para supervisar y depurar las solicitudes de Firestore en modo Datastore (Datastore) de extremo a extremo, puedes habilitar los registros en la biblioteca cliente de Java. El seguimiento del cliente puede proporcionar indicadores sobre el rendimiento que experimenta tu aplicación, así como estadísticas que pueden ayudar con los problemas de depuración.

Los seguimientos del cliente, que se recopilan mediante la ejecución de RPC desde el cliente proporciona la siguiente información:

• Se extiende con marcas de tiempo del momento en que el cliente envió la solicitud de RPC y cuando el cliente recibió la respuesta RPC, incluida la latencia introducida por el red y del sistema cliente
• Atributos (pares clave-valor) que muestran información sobre el cliente y su configuración.
• Registros asociados con eventos clave en los intervalos.
• Seguimientos de pila si se produce una falla en el cliente

OpenTelemetry

Los seguimientos de la biblioteca cliente de Java se instrumentan con las APIs de OpenTelemetry. OpenTelemetry es un framework de observabilidad de código abierto estándar de la industria. OpenTelemetry ofrece un amplio rango de herramientas, como las APIs de instrumentación y SDK, recopiladores, exportadores específicos de backend y opciones de configuración flexible como controles de muestreo, límites de intervalo y mucho más.

Cómo exportar registros con exportadores y recopiladores

Como parte de tus configuraciones, puedes exportar tus seguimientos a un backend de observabilidad. La mayoría de los proveedores de servicios de observabilidad ofrecen exportadores para que los uses, como Cloud Trace.

Además de un exportador, OpenTelemetry recomienda configurar Colector. Un recopilador permite que tus servicio de descarga de datos rápidamente y permite que el recopilador se encargue de las como los reintentos, el procesamiento por lotes y la encriptación. Un recopilador se ejecuta junto con tu aplicación. El recopilador recibe mensajes del protocolo OpenTelemetry (OTLP), procesa los mensajes y los exporta a tu backend de observabilidad.

Limitaciones

Los intervalos de seguimiento están disponibles solo para la biblioteca cliente de Java.

Facturación

Además del uso de Datastore, el seguimiento del cliente puede generar cargos.

No se aplican cargos por la recopilación de registros ni el uso de OpenTelemetry en un framework de nube.

Es posible que la transferencia de intervalos de seguimiento a tu backend de observabilidad sea facturable. Por ejemplo, si usas Cloud Trace como backend, se factura según los precios de Cloud Trace. Si usas otro proveedor de servicios de observabilidad, averigua su modelo de facturación y los costos asociados.

Para comprender mejor la facturación, comienza con una proporción de muestreo de seguimiento pequeña (traza un pequeño porcentaje de tus RPC) según en tu tráfico.

Antes de comenzar

Antes de comenzar:

• Asegúrate de configurar la cuenta de servicio con la que tu app escribe registros en tu backend de observabilidad con los roles de administración de identidades y accesos necesarios:

  Operación de seguimiento	Función de IAM
  Cómo leer seguimientos	roles/cloudtrace.user
  Cómo escribir seguimientos	roles/cloudtrace.agent
  Seguimientos de lectura o escritura	roles/cloudtrace.admin

• Verifica que la API de Trace esté habilitada en este proyecto.

Configura los seguimientos del cliente

En esta sección, se proporcionan ejemplos de configuraciones para los seguimientos del cliente. Puedes exportar a un recopilador o directamente a un backend de observabilidad. También tienes las siguientes opciones para configurar los seguimientos del cliente:

• Puedes configurar los seguimientos con las APIs de OpenTelemetry. Esto requiere cambios de código en tu aplicación. Consulta los siguientes ejemplos:
  • Exporta a un recopilador con las APIs de OpenTelemetry
  • Exporta directamente a un backend de observabilidad con las APIs de OpenTelemetry
• Puedes configurar registros sin cambios en el código con agentes automáticos. Debes configurar la variable de entorno DATASTORE_ENABLE_TRACING=ON. También debes establecer otros parámetros de configuración como se describe en Configuración del agente. Consulta los siguientes ejemplos:
  • Cómo exportar a un recopilador con agentes automáticos
  • Exporta directamente a un backend de observabilidad con agentes automáticos

Exporta seguimientos a un recopilador con las APIs de OpenTelemetry

El siguiente código configura la biblioteca cliente de Datastore para Java para exportar intervalos con una proporción de muestreo del 10% a OpenTelemetry Collector.

Java

Resource resource = Resource
  .getDefault().merge(Resource.builder().put(SERVICE_NAME, "My App").build());

OtlpGrpcSpanExporter otlpGrpcSpanExporter =
  OtlpGrpcSpanExporter
  .builder()
  .setEndpoint("http://localhost:4317") // Replace with your OTLP endpoint
  .build();

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
  BatchSpanProcessor.builder(otlpGrpcSpanExporter).build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(otlpGrpcSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
        .build();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

    

Exporta directamente a un backend de observabilidad con las APIs de OpenTelemetry

El siguiente código configura la biblioteca cliente de Java para exportar directamente los intervalos de seguimiento a Cloud Trace con una proporción de muestreo de seguimiento del 10%. Puedes usar los exportadores de otros proveedores de servicios de observabilidad para exportar directamente a su backend. Si tu backend de observabilidad admite la transferencia de OTLP, puedes usar OpenTelemetry OtlpGrpcSpanExporter para exportar a tu backend en lugar de usar un exportador personalizado.

Java

// TraceExporter needed for this use case
import com.google.cloud.opentelemetry.trace.TraceExporter;

Resource resource = Resource
  .getDefault().merge(Resource.builder().put(SERVICE_NAME, "My App").build());
SpanExporter gcpTraceExporter = TraceExporter.createWithDefaultConfiguration();

// Using a batch span processor
// You can use `.setScheduleDelay()`, `.setExporterTimeout()`,
// `.setMaxQueueSize`(), and `.setMaxExportBatchSize()` to further customize.
SpanProcessor gcpBatchSpanProcessor =
  BatchSpanProcessor.builder(gcpTraceExporter).build();

// Export directly to Cloud Trace with 10% trace sampling ratio
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(gcpBatchSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build())
        .build();


DatastoreOptions datastoreOptions = DatastoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    DatastoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build();

Datastore datastore = datastoreOptions.getService();

    

Exportar a un recopilador con agentes automáticos

Ejecuta el recopilador de OpenTelemetry con los receptores gRPC de OTLP habilitados. Establece el exportador del agente en otlp y especifica el extremo al que el agente debe exportar los datos. El siguiente ejemplo usa una proporción de muestreo del 10% y envía Seguimientos en el colector que escucha en el puerto localhost 4317.

Terminal

DATASTORE_ENABLE_TRACING=ON                            \
java                                                   \
-javaagent:path/to/opentelemetry-javaagent.jar         \
-Dotel.traces.exporter=otlp                            \
-Dotel.exporter.otlp.endpoint="http://localhost:4317"  \
-Dotel.traces.sampler=traceidratio                     \
-Dotel.traces.sampler.arg=0.1                          \
-Dotel.service.name="My App"                           \
-jar myapp.jar

    

Exporta directamente a un backend de observabilidad con agentes automáticos

Además de configurar la variable de entorno DATASTORE_ENABLE_TRACING=ON, debes agregar la extensión del agente de Java de OpenTelemetry para tu backend específico. En el siguiente ejemplo, se usa la extensión del exportador de seguimientos y una proporción de muestreo de seguimientos del 10%.

Terminal

DATASTORE_ENABLE_TRACING=ON                                                \
java                                                                       \
-javaagent:path/to/opentelemetry-javaagent.jar                             \
-Dotel.javaagent.extensions=/path/to/exporter-auto-0.26.0-alpha-shaded.jar \
-Dotel.traces.exporter=google_cloud_trace                                  \
-Dotel.traces.sampler=traceidratio                                         \
-Dotel.traces.sampler.arg=0.1                                              \
-Dotel.service.name="My Application"                                       \
-jar myapp.jar

    

Seguimiento de ejemplo

En los siguientes ejemplos, se muestra cómo se muestra la información de seguimiento en Cloud Trace. Para obtener más información sobre posibles atributos y valores, consulta Atributos y eventos de intervalos de seguimiento.

Ejemplo de intervalo de seguimiento

Ejemplo de registro de eventos

Ejemplos de valores de atributos

¿Qué sigue?

• Consulta la referencia de Atributos y eventos de intervalos de seguimiento.
• Obtén información sobre la supervisión del servidor.