Monitorar a performance com rastros do lado do cliente

Visualização

Esse recurso está sujeito aos "Termos de ofertas pré-GA" na seção "Termos de Serviço gerais" 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 rastros na biblioteca de cliente Java. O rastreamento do lado do cliente pode fornecer sinal sobre o desempenho do seu aplicativo, bem como insights que podem ajudar na depuração de problemas.

Os rastros do lado do cliente, que são coletados pela execução de RPCs do cliente, fornecem as seguintes informações:

• Períodos com carimbos de data/hora de quando o cliente enviou a solicitação RPC e quando o cliente recebeu a resposta RPC, incluindo a latência introduzida pelo rede e 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 períodos.
• Rastreamento de pilha se ocorrer uma falha no cliente.

OpenTelemetry

Os rastros da biblioteca de cliente Java são instrumentados usando as APIs do OpenTelemetry. O OpenTelemetry é um framework de observabilidade padrão do setor e de código aberto. O OpenTelemetry oferece uma ampla variedade de ferramentas, como APIs de instrumentação e SDKs, 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 rastros com exportadores e coletores

Como parte das suas configurações, é possível exportar os rastros 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 uma Coletor: Com um coletor, o serviço descarrega os dados rapidamente e permite que o coletor cuide de processamento de dados, como novas tentativas, lotes e criptografia. Um coletor é executado com seu aplicativo. O coletor recebe as mensagens do protocolo do OpenTelemetry (OTLP), processa as mensagens e os exporta para o back-end de observabilidade.

Limitações

Os intervalos de traços 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 taxas.

Não há cobranças para coletar rastros ou usar o framework do OpenTelemetry.

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

Para entender melhor o faturamento, comece com uma pequena proporção de amostragem de traces (trace uma pequena porcentagem das RPCs) com base no seu tráfego.

Antes de começar

Antes de começar:

• Configure a conta de serviço em que o app grava rastros no back-end de observabilidade com as funções de gerenciamento de identidade e acesso necessárias:

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

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

Configurar rastros do lado do cliente

Esta seção fornece exemplos de configurações para rastros do lado do cliente. Você pode 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 rastros com as APIs do OpenTelemetry. Isso requer mudanças no código do aplicativo. Confira os exemplos a seguir:
  • Exportar para um coletor com as APIs do OpenTelemetry
  • Exportar diretamente para um back-end de observabilidade com as APIs OpenTelemetry
• É possível configurar rastros sem mudanças no código usando agentes automáticos. Você precisa Defina a variável de ambiente DATASTORE_ENABLE_TRACING=ON. Você também precisa definir outras configurações conforme descrito em Configuração do agente. Confira 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 rastros para um coletor com APIs do OpenTelemetry

O código a seguir configura a biblioteca de cliente Java do Datastore para exportar intervalos com uma taxa de amostragem de 10% para um coletor do 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 as APIs do OpenTelemetry

O código a seguir configura a biblioteca de cliente Java para exportar diretamente o trace abrange o Cloud Trace com uma proporção de amostragem de traces de 10%. Você pode usar de outros provedores de serviços de observabilidade os exportadores exportem diretamente para seus back-end. Se o back-end de observabilidade oferecer suporte à ingestão de OTLP, use 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();

    

Exporte para um coletor com agentes automáticos

Execute o Coletor do OpenTelemetry com os receptores gRPC do OTLP ativados. Defina o exportador do agente como otlp e especifique o endpoint para onde o agente precisa exportar os dados. O exemplo a seguir usa uma proporção de amostragem de 10% e envia traces para o coletor que detecta na porta do localhost 4317.

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 seu back-end específico. O exemplo a seguir usa a extensão do exportador de rastreamento e uma proporção 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 rastro

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 intervalo de rastreamento.

Exemplo de período de rastreamento

Exemplo de registro de eventos

Exemplos de valores de atributos

A seguir

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