Monitorize o desempenho com rastreios do lado do cliente

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Para monitorizar e depurar pedidos do Firestore no modo Datastore (Datastore) de forma integral, pode ativar rastreios na biblioteca cliente Java. 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 da biblioteca cliente Java 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, limites de intervalos e muito mais.

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

Limitações

Os intervalos de rastreios só estão disponíveis para a biblioteca de cliente Java.

Faturação

Além da utilização do Datastore, 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:

• Pode configurar rastreios com as APIs OpenTelemetry. Isto requer alterações ao código da sua aplicação. Veja os exemplos seguintes:
  • Exporte para um coletor com APIs OpenTelemetry
  • Exporte diretamente para um back-end de observabilidade com APIs OpenTelemetry
• Pode configurar rastreios sem alterações ao código através de agentes automáticos. Tem de definir a variável de ambiente DATASTORE_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
  • Exporte diretamente para um back-end de observabilidade com agentes automáticos

Exporte rastreios para um coletor com APIs OpenTelemetry

O código seguinte configura a biblioteca 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();

    

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

O código seguinte configura a biblioteca cliente Java para exportar diretamente intervalos de rastreio para o Cloud Trace com uma taxa de amostragem de rastreio de 10%. Pode usar exportadores de outros fornecedores de serviços de observabilidade para exportar diretamente para o respetivo back-end. Se o seu back-end de observabilidade suportar a ingestão de OTLP, pode usar o OpenTelemetry OtlpGrpcSpanExporterpara exportar para o seu 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 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.

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

    

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

Além de definir a variável de ambiente DATASTORE_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%.

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

Exemplo de registo de eventos

Exemplos de valores de atributos

O que se segue?

• Veja a referência para Atributos e eventos de intervalo de rastreio.
• Saiba mais sobre a monitorização do lado do servidor.