Monitorar a performance com rastros do lado do cliente

Para monitorar e depurar solicitações do Firestore no modo Datastore (Datastore) de ponta a ponta, é possível ativar rastreamentos 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 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 rastreamentos da biblioteca de cliente Java são instrumentados usando APIs do 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, limites de extensão e muito mais.

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 mensagens do protocolo OpenTelemetry (OTLP), processa e exporta para o back-end de observabilidade.

Limitações

Os intervalos de rastreamento 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 custos.

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 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 APIs OpenTelemetry

O código a seguir configura a biblioteca de cliente Java para exportar diretamente intervalos de rastreamento para o Cloud Trace com uma taxa de amostragem de rastreamento de 10%. É possível usar 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 OpenTelemetry OtlpGrpcSpanExporter 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 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.

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 backend específico. O exemplo a seguir usa a extensão do exportador de rastreamento e uma taxa de amostragem de rastreamento 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 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 período de rastreamento visto do Cloud Trace.

Exemplo de log de eventos

Um registro de evento de período de trace visualizado no Cloud Trace.

Exemplos de valores de atributos

Valores de atributos de um período de trace visualizado no Cloud Trace.

A seguir