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 um sinal sobre o desempenho do aplicativo, além de insights que podem ajudar a resolver problemas de depuração.

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

• Intervalos com carimbos de data/hora de quando o cliente enviou a solicitação de RPC e quando 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 mostram informações sobre o cliente e a configuração dele.
• Registros associados a eventos principais nos períodos.
• Stack traces se ocorrer uma falha no cliente.

OpenTelemetry

Os rastros da biblioteca de cliente Java são instrumentados usando APIs do OpenTelemetry. O OpenTelemetry é um framework de observabilidade de código aberto e padrão do setor. O OpenTelemetry oferece uma ampla 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 controles de amostragem, limites de intervalo 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 um Coletor. Um coletor permite que seu serviço descarregue dados rapidamente e que ele cuide de outros processamentos, como reprocessamentos, agrupamentos e criptografia. Um coletor é executado com seu aplicativo. O coletor recebe, processa e exporta mensagens do protocolo OpenTelemetry (OTLP) 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 intervalos de trace no back-end de observabilidade pode ser cobrada. Por exemplo, se você usar o Cloud Trace como seu 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 (rastre uma pequena porcentagem dos seus 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 trace	Papel do IAM
  Ler rastros	roles/cloudtrace.user
  Gravar rastros	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 os rastros 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 APIs do OpenTelemetry
  • Exportar diretamente para um back-end de observabilidade com APIs do OpenTelemetry
• É possível configurar rastros sem mudanças no código usando agentes automáticos. É necessário definir 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 os intervalos de rastreamento para o Cloud Trace com uma taxa de amostragem de 10%. É possível usar exportadores de outros provedores de serviços de observabilidade para exportar diretamente para o back-end. Se o back-end de observabilidade oferecer suporte à ingestão 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 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 rastros para o coletor que ouve 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 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 duração do Trace.

Exemplo de período de rastreamento

Exemplo de registro de eventos

Exemplos de valores de atributo

A seguir

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