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 una señal 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, proporcionan la siguiente información:

• Intervalos con marcas de tiempo de cuándo el cliente envió la solicitud de RPC y cuándo recibió la respuesta de RPC, incluida la latencia que introducen la red y el sistema del 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 y estándar de la industria. OpenTelemetry ofrece una amplia variedad de herramientas, como APIs y SDK de instrumentación, recopiladores, exportadores específicos del backend y opciones de configuración flexibles, 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 un recopilador. Un recopilador permite que tu servicio transfiera datos rápidamente y que el recopilador se encargue del manejo adicional, como las reintentos, los lotes y la encriptación. Un recopilador se ejecuta junto con tu aplicación. El recopilador recibe mensajes del protocolo OpenTelemetry (OTLP), los procesa y los exporta a tu backend de observabilidad.

Limitaciones

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

Facturación

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

No se cobran cargos por recopilar seguimientos ni por el uso del framework de OpenTelemetry.

Es posible que se pueda facturar la transferencia de intervalos de seguimiento a tu backend de observabilidad. Por ejemplo, si usas Cloud Trace como backend, se te 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 pequeña proporción de muestreo de seguimiento (registra un pequeño porcentaje de tus RPC) según 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
  Registros de lectura y 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:
  • Cómo exportar 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 Java de Datastore para exportar intervalos con una proporción de muestreo del 10% a un recopilador de OpenTelemetry.

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();

    

Cómo 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. En el siguiente ejemplo, se usa una proporción de muestreo del 10% y se envían registros al recopilador que escucha en el puerto 4317 de localhost.

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

    

Ejemplo de seguimiento

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 los posibles atributos y valores, consulta Atributos y eventos de intervalo 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 intervalo de seguimiento.
• Obtén información sobre la supervisión del servidor.