Supervisa el rendimiento con seguimientos del cliente

Supervisa el rendimiento con seguimientos 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 de extremo a extremo, puedes habilitar los seguimientos 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 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 la configuración, puedes exportar los seguimientos a un backend de observabilidad. La mayoría de los proveedores de servicios de observabilidad exportadores que puedes utilizar, 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 corre junto a tu aplicación. El recopilador recibe mensajes de OTLP, los procesa y los exporta a tu backend de observabilidad.

Limitaciones

Los seguimientos del cliente tienen las siguientes limitaciones:

• Los intervalos de seguimiento están disponibles para la biblioteca cliente de Java.
• La biblioteca cliente no produce intervalos de seguimiento para los objetos de escucha en tiempo real.

Facturación

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

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

La transferencia de intervalos de seguimiento a tu backend de observabilidad podría ser 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, identifica 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 parámetros de configuración de ejemplo 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 seguimientos con las APIs de OpenTelemetry. Esto requiere código cambios 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 seguimientos sin cambios de código usando agentes automáticos. Debes configurar la variable de entorno FIRESTORE_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 registros a un recopilador con las APIs de OpenTelemetry

En el siguiente código, se configura la biblioteca cliente de Java de Firestore para exportar intervalos con una proporción de muestreo del 10% a un recopilador de OpenTelemetry.

Java (Administrador)

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 also use other `BatchSpanProcessorBuilder` methods
// 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();

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().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 el seguimiento de forma directa a Cloud Trace con una proporción de muestreo de seguimientos del 10%. Puedes usar de otros proveedores de servicios de observabilidad exportadores directamente a sus 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 (Administrador)

// 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 also use other `BatchSpanProcessorBuilder` methods
// 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();

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().getService();

    

Cómo exportar a un recopilador con agentes automáticos

Ejecuta tu OpenTelemetry Collector con los receptores gRPC de OTLP habilitados. Establece el exportador del agente a otlp y especifica el extremo en el que 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

FIRESTORE_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 FIRESTORE_ENABLE_TRACING=ON, debes agregar la extensión del agente de Java de OpenTelemetry para tu backend. En el siguiente ejemplo, se usa la extensión del exportador de seguimiento y una proporción de muestreo de seguimiento del 10%.

Terminal

FIRESTORE_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                                              \

    

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

Ejemplo de seguimiento de pila y evento de excepción

¿Qué sigue?

• Consulta la referencia sobre los atributos y eventos de intervalos de seguimiento.
• Obtén más información sobre la supervisión del servidor.