Monitorar a performance com rastreamentos do lado do cliente

Para monitorar e depurar solicitações do Firestore de ponta a ponta, é possível ativar rastreamentos nas bibliotecas de cliente. O rastreamento do lado do cliente pode fornecer um indicador sobre o desempenho do aplicativo, além de insights que ajudam a depurar problemas.

Os rastreamentos do lado do cliente, que são coletados executando RPCs do cliente, fornecem as seguintes informações:

  • Abrangências com carimbos de data/hora de quando o cliente enviou a solicitação de RPC e quando ele recebeu a resposta de RPC, incluindo a latência introduzida pela rede e pelo sistema do cliente.
  • Atributos (pares de chave-valor) que mostram informações sobre o cliente e a configuração dele.
  • Registros associados a eventos principais nos intervalos
  • Rastreamentos de pilha se ocorrer uma falha no cliente

OpenTelemetry

Os traces das bibliotecas de cliente são instrumentados usando as APIs OpenTelemetry. O OpenTelemetry é um framework de observabilidade de código aberto padrão do setor. O OpenTelemetry oferece uma ampla variedade de ferramentas, como APIs e SDKs de instrumentação, coletores, exportadores específicos do back-end e opções de configuração flexíveis, como controles de amostragem e limites de período.

Exportar rastreamentos com exportadores e coletores

Como parte das suas configurações, é possível exportar seus rastreamentos para um back-end de observabilidade. A maioria dos provedores de serviços de observabilidade oferece exportadores para você usar, como o Cloud Trace.

Além de um exportador, o OpenTelemetry recomenda configurar um Collector. Um coletor permite que seu serviço descarregue dados rapidamente e que o coletor cuide de outros processos, como novas tentativas, agrupamento em lotes e criptografia. Um coletor é executado ao lado do seu aplicativo. O coletor recebe e processa mensagens OTLP e as exporta para seu back-end de observabilidade.

Limitações

Os rastreamentos do lado do cliente têm as seguintes limitações:

  • Os intervalos de rastreamento estão disponíveis para as bibliotecas de cliente Java e Node.js.
  • A biblioteca de cliente não gera intervalos de rastreamento para listeners em tempo real.

Faturamento

Além do uso do Firestore, o rastreamento do lado do cliente pode gerar cobranças.

Não há cobranças pela coleta de rastreamentos ou pelo uso da estrutura OpenTelemetry.

A ingestão de intervalos de rastreamento no back-end de observabilidade pode ser faturável. Por exemplo, se você usar o Cloud Trace como back-end, será cobrado de acordo com os preços do Cloud Trace. Se você usa outro provedor de serviços de observabilidade, descubra o modelo de faturamento e os custos associados.

Para entender melhor o faturamento, comece com uma pequena taxa de amostragem de rastreamento (rastreie uma pequena porcentagem das suas RPCs) com base no seu tráfego.

Antes de começar

Antes de começar:

  • Verifique se você configurou a conta de serviço em que seu app grava rastreamentos no back-end de observabilidade com os papéis do Identity and Access Management necessários:

    Operação de rastreamento Papel do IAM
    Ler rastreamentos roles/cloudtrace.user
    Gravar rastros roles/cloudtrace.agent
    Rastreamentos de leitura/gravação roles/cloudtrace.admin

  • Verifique se a API Trace está ativada neste projeto.

Configurar rastreamentos do lado do cliente

Nesta seção, apresentamos exemplos de configurações para rastreamentos do lado do cliente. É possível exportar para um coletor ou diretamente para um back-end de observabilidade. Você também tem as seguintes opções para configurar rastreamentos do lado do cliente:

Exportar rastreamentos para um coletor com APIs do OpenTelemetry

O código a seguir configura a biblioteca de cliente para exportar períodos com uma taxa de amostragem de 10% para um coletor do OpenTelemetry.

Java (Admin)

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

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

Exportar diretamente para um back-end de observabilidade com APIs OpenTelemetry

Se o provedor de serviços de observabilidade oferecer suporte à ingestão de OTLP, use o exportador do OpenTelemetry dele para exportar rastreamentos diretamente para o back-end. O código a seguir configura a biblioteca de cliente para exportar diretamente períodos de rastreamento para o Cloud Trace com uma taxa de amostragem de rastreamento de 10%.

Java (Admin)

// 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 (Admin)

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

Instrumentação sem código

Siga estas instruções para configurar rastreamentos sem fazer mudanças no código:

Java (Admin)
É possível configurar rastreamentos sem mudanças no código usando agentes automáticos. É necessário definir a variável de ambiente FIRESTORE_ENABLE_TRACING=ON. Você também precisa definir outras configurações de configuração, conforme descrito em Configuração do agente. Veja os exemplos a seguir.

Exportar para um coletor com agentes automáticos

Execute o OpenTelemetry Collector com os receptores gRPC do OTLP ativados. Defina o exportador do agente como otlp e especifique o endpoint para onde o agente deve exportar os dados. O exemplo a seguir usa uma taxa de amostragem de 10% e envia rastreamentos para o coletor que escuta na porta localhost 4317. 


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

Exportar diretamente para um back-end de observabilidade com agentes automáticos

Além de definir a variável de ambiente FIRESTORE_ENABLE_TRACING=ON, é necessário adicionar a extensão do agente Java do OpenTelemetry para seu backend específico. O exemplo a seguir usa a extensão do exportador de rastreamento e uma taxa de amostragem de rastreamento de 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 (Admin)

Para configurar a instrumentação sem código, siga as instruções do OpenTelemetry para instrumentação em JavaScript. O snippet de código de exemplo a seguir ativa a instrumentação e envia rastreamentos para um coletor do OpenTelemetry:


npm install @opentelemetry/api
npm install @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

Exemplo de rastreamento

Os exemplos a seguir mostram como as informações de rastreamento são exibidas no Cloud Trace. Para mais informações sobre possíveis atributos e valores, consulte Atributos e eventos de intervalo de rastreamento.

Exemplo de período de rastreamento

Um intervalo de rastreamento visto no Cloud Trace

Exemplo de log de eventos

Um registro de evento de período de rastreamento visto no Cloud Trace

Exemplos de valores de atributos

Valores de atributos de um período de trace exibido no Cloud Trace

Exemplo de rastreamento de pilha e evento de exceção

Um stack trace visto no Cloud Trace

Um evento de exceção visto no Cloud Trace

A seguir