Supervisa el rendimiento con registros del cliente

Vista previa

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles “tal cual” y pueden 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 el registro de seguimiento en la biblioteca cliente de Java. El registro del cliente puede proporcionar una señal sobre el rendimiento que experimenta tu aplicación, así como estadísticas que pueden ayudar a depurar problemas.

Los registros del cliente, que se recopilan ejecutando RPC desde el cliente, proporcionan la siguiente información:

• Intervalos con marcas de tiempo que indican cuándo el cliente envió la solicitud de RPC y cuándo recibió la respuesta de RPC, incluida la latencia que introdujeron la red y el sistema del cliente
• Son atributos (pares clave-valor) que muestran información sobre el cliente y su configuración.
• Son los registros asociados con los eventos clave en los períodos.
• Seguimientos de pila si se produce una falla en el cliente

OpenTelemetry

Los registros de seguimiento 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 SDKs de instrumentación, recopiladores, exportadores específicos del backend y opciones de configuración flexibles, como controles de muestreo, límites de tramos y mucho más.

Cómo exportar registros con exportadores y recopiladores

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

Además de un exportador, OpenTelemetry recomienda configurar un recopilador. Un recopilador permite que tu servicio descargue datos rápidamente y que el recopilador se encargue del procesamiento adicional, como reintentos, procesamiento por lotes y 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 rastreo del cliente puede generar cargos.

No se aplican cargos por recopilar registros ni por usar el framework de OpenTelemetry.

Es posible que la transferencia de intervalos de seguimiento a tu backend de observabilidad sea facturable. Por ejemplo, si usas Cloud Trace como tu backend, se te facturará 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 registros pequeña (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 Identity and Access Management necesarios:

  Operación de seguimiento	Función de IAM
  Cómo leer registros	roles/cloudtrace.user
  Registrar rutas	roles/cloudtrace.agent
  Registros de lectura y escritura	roles/cloudtrace.admin

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

Configura el registro de seguimiento del cliente

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

• Puedes configurar 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 cambiar el código con los 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 los 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 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 OtlpGrpcSpanExporter de OpenTelemetry 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();

    

Exporta a un recopilador con agentes automáticos

Ejecuta tu recopilador de OpenTelemetry con los receptores gRPC de OTLP habilitados. Configura 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 a Collector, 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 los 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 usan la extensión del exportador de registros de seguimiento y una proporción de muestreo de registros de seguimiento 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 registro

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 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 más información sobre la supervisión del servidor.