Monitorize o desempenho com rastreios do lado do cliente

Para monitorizar e depurar pedidos do Firestore de forma integral, pode ativar rastreios nas bibliotecas cliente. A monitorização do lado do cliente pode fornecer um sinal sobre o desempenho, tal como é experimentado pela sua aplicação, bem como estatísticas que podem ajudar a depurar problemas.

Os rastreios do lado do cliente, que são recolhidos através da execução de RPCs a partir do cliente, fornecem as seguintes informações:

  • Intervalos com data/hora em que o cliente enviou o pedido de RPC e em que o cliente recebeu a resposta de RPC, incluindo a latência introduzida pela rede e pelo sistema do cliente
  • Atributos (pares de chave-valor) que apresentam informações sobre o cliente e a respetiva configuração
  • Registos associados a eventos principais nos intervalos
  • Rastreios de pilha se ocorrer uma falha de sistema no cliente

OpenTelemetry

Os rastreios das bibliotecas cliente são instrumentados através das APIs OpenTelemetry. O OpenTelemetry é uma framework de observabilidade de código aberto, uma norma da indústria. O OpenTelemetry oferece uma vasta gama de ferramentas, como APIs de instrumentação e SDKs, coletores, exportadores específicos do back-end e opções de configuração flexíveis, como controlos de amostragem e limites de intervalos.

Exporte rastreios com exportadores e coletores

Como parte das suas configurações, pode exportar os seus rastreios para um back-end de observabilidade. A maioria dos fornecedores de serviços de observabilidade oferece exportadores para utilização, como o Cloud Trace.

Além de um exportador, o OpenTelemetry recomenda a configuração de um coletor. Um coletor permite que o seu serviço transfira dados rapidamente e permite que o coletor cuide do processamento adicional, como novas tentativas, processamento em lote e encriptação. Um coletor é executado juntamente com a sua aplicação. O coletor recebe mensagens OTLP, processa as mensagens e exporta-as para o seu back-end de observabilidade.

Limitações

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

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

Faturação

Além da utilização do Firestore, a monitorização do lado do cliente pode incorrer em custos.

Não existem custos para a recolha de rastreios nem para a utilização da framework OpenTelemetry.

A ingestão de intervalos de rastreio no seu back-end de observabilidade pode ser faturável. Por exemplo, se usar o Cloud Trace como back-end, a faturação é feita de acordo com os preços do Cloud Trace. Se usar outro fornecedor de serviços de observabilidade, descubra o respetivo modelo de faturação e custos associados.

Para compreender melhor a faturação, comece com uma pequena taxa de amostragem de rastreio (rastreie uma pequena percentagem das suas RPCs) com base no seu tráfego.

Antes de começar

Antes de começar:

  • Certifique-se de que configura a conta de serviço na qual a sua app escreve rastreios no back-end de observabilidade com as funções de gestão de identidade e de acesso necessárias:

    Operação de rastreio Função de IAM
    Ler rastreios roles/cloudtrace.user
    Escrever rastreios roles/cloudtrace.agent
    Rastreios de leitura/escrita roles/cloudtrace.admin

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

Configure rastreios do lado do cliente

Esta secção apresenta exemplos de configurações para rastreios do lado do cliente. Pode exportar para um coletor ou diretamente para um back-end de observabilidade. Também tem as seguintes opções para configurar rastreios do lado do cliente:

Exporte rastreios para um coletor com APIs OpenTelemetry

O código seguinte configura a biblioteca de cliente para exportar intervalos com uma taxa de amostragem de 10% para um OpenTelemetry Collector.

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

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

Se o seu fornecedor de serviços de observabilidade suportar a ingestão de OTLP, pode usar o respetivo exportador do OpenTelemetry para exportar rastreios diretamente para o respetivo back-end. O código seguinte configura a biblioteca de cliente para exportar diretamente intervalos de rastreio para o Cloud Trace com uma taxa de amostragem de rastreio de 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));
});

Instrumentação sem código

Conclua as instruções seguintes para configurar rastreios sem alterações ao código:

Java (administrador)
Pode configurar rastreios sem alterações ao código através de agentes automáticos. Tem de definir a variável de ambiente FIRESTORE_ENABLE_TRACING=ON. Também tem de definir outras definições de configuração, conforme descrito em Configuração do agente. Veja os exemplos seguintes.

Exporte para um coletor com agentes automáticos

Execute o OpenTelemetry Collector com recetores gRPC OTLP ativados. Defina o exportador do agente como otlp e especifique o ponto final para o qual o agente deve exportar os dados. O exemplo seguinte usa uma taxa de amostragem de 10% e envia rastreios para o coletor que escuta na porta 4317 do anfitrião local. 


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

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

Além de definir a variável de ambiente FIRESTORE_ENABLE_TRACING=ON, tem de adicionar a extensão do agente Java OpenTelemetry para o seu back-end específico. O exemplo seguinte usa a extensão do exportador de rastreios e uma taxa de amostragem de rastreios 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 (administrador)

Para configurar a instrumentação sem código, siga as instruções do OpenTelemetry para a instrumentação de JavaScript. O seguinte exemplo de fragmento do código ativa a instrumentação e envia rastreios para um coletor 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 rastreio

Os exemplos seguintes mostram como as informações de rastreio são apresentadas no Cloud Trace. Para mais informações sobre os possíveis atributos e valores, consulte o artigo Atributos e eventos de intervalo de rastreio.

Exemplo de intervalo de rastreio

Um intervalo de rastreio visto a partir do Cloud Trace

Exemplo de registo de eventos

Um registo de eventos de intervalo de rastreio visto a partir do Cloud Trace

Exemplos de valores de atributos

Valores de atributos de um intervalo de rastreio visto a partir do Cloud Trace

Exemplo de rastreio da pilha e evento de exceção

Um rastreio de pilha visto a partir do Cloud Trace

Um evento de exceção visto a partir do Cloud Trace

O que se segue?