Monitorar a performance com rastreamentos do lado do cliente

Visualizar

Este recurso está sujeito aos Termos das Soluções Pré-GA na seção Termos Gerais de Serviço dos Termos Específicos de Serviço. Os recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Para monitorar e depurar solicitações do Firestore no modo Datastore (Datastore) de ponta a ponta, ative os traces na biblioteca de cliente Java. O rastreamento do lado do cliente pode fornecer um indicador sobre o desempenho do aplicativo, além de insights que podem ajudar a depurar problemas.

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

• Períodos com carimbos de data/hora de quando o cliente enviou a solicitação de RPC e quando 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 importantes nos períodos.
• Rastros de pilha se ocorrer uma falha no cliente.

OpenTelemetry

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

Exportar traces com exportadores e coletores

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

Além de um exportador, o OpenTelemetry recomenda configurar um coletor. Um coletor permite que o serviço descarregue dados rapidamente e cuide de outros processamentos, como novas tentativas, loteamento e criptografia. Um coletor é executado junto com o aplicativo. Ele recebe mensagens do protocolo OpenTelemetry (OTLP), processa as mensagens e as exporta para o back-end de observabilidade.

Limitações

Os períodos de trace estão disponíveis apenas para a biblioteca de cliente Java.

Faturamento

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

Não há cobranças pela coleta de traces ou pelo uso do framework OpenTelemetry.

A ingestão de períodos de trace no back-end de observabilidade pode ser faturável. Por exemplo, se você usar o Cloud Trace como back-end, a cobrança será feita de acordo com os preços do Cloud Trace. Se você usar 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 trace (trace uma pequena porcentagem das RPCs) com base no tráfego.

Antes de começar

Antes de começar:

• Configure a conta de serviço em que o app grava traces no back-end de observabilidade com os papéis de gerenciamento de identidade e acesso necessários :

  Operação de trace	Papel do IAM
  Ler traces	roles/cloudtrace.user
  Gravar traces	roles/cloudtrace.agent
  Ler/gravar traces	roles/cloudtrace.admin

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

Configurar traces do lado do cliente

Esta seção fornece exemplos de configurações para traces 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 traces do lado do cliente:

• É possível configurar traces com as APIs OpenTelemetry. Isso exige mudanças no código do aplicativo. Consulte os exemplos a seguir:
  • Exportar para um coletor com APIs OpenTelemetry
  • Exportar diretamente para um back-end de observabilidade com APIs OpenTelemetry
• É possível configurar traces sem mudanças no código usando agentes automáticos. É necessário definir a variável de ambiente DATASTORE_ENABLE_TRACING=ON. Também é necessário definir outras configurações conforme descrito em Configuração do agente. Consulte os exemplos a seguir:
  • Exportar para um coletor com agentes automáticos
  • Exportar diretamente para um back-end de observabilidade com agentes automáticos

Exportar traces para um coletor com APIs OpenTelemetry

O código a seguir configura a biblioteca de cliente Java do DataStore para exportar períodos com uma taxa de amostragem de 10% para um coletor 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();

    

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

O código a seguir configura a biblioteca de cliente Java para exportar diretamente períodos de trace para o Cloud Trace com uma taxa de amostragem de 10%. É possível usar os exportadores de outros provedores de serviços de observabilidade para exportar diretamente para o back-end deles. Se o back-end de observabilidade oferecer suporte à ingestão de OTLP, use o OtlpGrpcSpanExporter do OpenTelemetry para exportar para o back-end em vez de usar um 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();

    

Exportar para um coletor com agentes automáticos

Execute o OpenTelemetry Collector com os receptores OTLP gRPC ativados. Defina o exportador do agente como otlp e especifique o endpoint em que o agente precisa exportar os dados. O exemplo a seguir usa uma taxa de amostragem de 10% e envia traces para o coletor que ouve na porta 4317 do 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

    

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

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

    

Exemplo de trace

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

Exemplo de período de trace

Exemplo de registro de eventos

Exemplo de valores de atributos

A seguir

• Consulte a referência para atributos e eventos de período de trace..
• Saiba mais sobre o monitoramento do lado do servidor.