Supervisa el rendimiento con registros del cliente

Supervisa el rendimiento con registros del cliente

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see the launch stage descriptions.

Para supervisar y depurar las solicitudes de Firestore de extremo a extremo, puedes habilitar los registros en las bibliotecas cliente. El seguimiento del cliente puede proporcionar una señal sobre el rendimiento que experimenta tu aplicación, así como estadísticas que pueden ayudarte a solucionar 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 las bibliotecas cliente 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 y límites de intervalo.

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 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 las bibliotecas cliente de Java y Node.js.
• 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.

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
• Para configurar registros sin cambios en el código, sigue los ejemplos de Instrumentación sin código.

Exporta seguimientos a un recopilador con las APIs de OpenTelemetry

El siguiente código configura la biblioteca cliente 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();

    

Node.js (administrador)

import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';

import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";
import pkg3 from "@opentelemetry/exporter-trace-otlp-grpc";

const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;
const { OTLPTraceExporter } =  pkg3;

const provider = new NodeTracerProvider(
  // Provide your chosen NodeTracerConfig such as sampler and span limit
  {
    sampler: new TraceIdRatioBasedSampler(0.1),
  }
);
provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter()));
provider.register();

// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
  instrumentations: [
    new GrpcInstrumentation(
      // (optional): you can add GrpcInstrumentationConfig here
    ),
  ],
});


const settings: Settings = {
  projectId: 'my-project-id',
  preferRest: false,
  openTelemetry: {
    tracerProvider: trace.getTracerProvider()
  }
};

// Initialize Firestore
const firestore = new Firestore(settings);
// Add app code here

// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
  await provider
        .shutdown()
        .catch(error => console.error('Error terminating NodeTracerProvider:', error));
});
    

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

Si tu proveedor de servicios de observabilidad admite la transferencia de OTLP, puedes usar su exportador de OpenTelemetry para exportar seguimientos directamente a su backend. El siguiente código configura la biblioteca cliente para exportar directamente intervalos de seguimiento a Cloud Trace con una proporción de muestreo de seguimiento del 10%.

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

    

Node.js (administrador)

import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';
import { TraceExporter } from "@google-cloud/opentelemetry-cloud-trace-exporter";

import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";

const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;

const provider = new NodeTracerProvider(
  // Provide your chosen NodeTracerConfig such as sampler and span limits
  {
    sampler: new TraceIdRatioBasedSampler(0.1),
  }
);
provider.addSpanProcessor(new BatchSpanProcessor(new TraceExporter()));
provider.register();

// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
  instrumentations: [
    new GrpcInstrumentation(
      // (optional): you can add GrpcInstrumentationConfig here
    ),
  ],
});


const settings: Settings = {
  projectId: 'my-project-id',
  preferRest: false,
  openTelemetry: {
    tracerProvider: trace.getTracerProvider()
  }
};

// Initialize Firestore
const firestore = new Firestore(settings);
// ...

// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
  await provider
        .shutdown()
        .catch(error => console.error('Error terminating NodeTracerProvider:', error));
});
    

Instrumentación sin código

Completa las siguientes instrucciones para configurar registros sin cambios en el código:

Java (administrador)

Puedes configurar registros sin cambios en el código con agentes automáticos. Debes configurar la variable de entorno FIRESTORE_ENABLE_TRACING=ON. También debes configurar 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

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 seguimientos al recopilador que escucha en el puerto 4317 de localhost.

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 específico. En el siguiente ejemplo, se usa la extensión del exportador de seguimiento y una proporción de muestreo de seguimiento del 10%.

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                                              \

    

Node.js (administrador)

Para configurar la instrumentación sin código, sigue las instrucciones de OpenTelemetry para la instrumentación de JavaScript. En el siguiente fragmento de código de ejemplo, se habilita la instrumentación y se envían seguimientos a un recopilador de OpenTelemetry:

npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node


env \
FIRESTORE_ENABLE_TRACING=ON \
OTEL_TRACES_EXPORTER=otlp \
OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,grpc" \
OTEL_NODE_RESOURCE_DETECTORS="none" \
node --require @opentelemetry/auto-instrumentations-node/register my_app.js

    

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

Ejemplo de seguimiento de pila y evento de excepción

¿Qué sigue?

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