Monitorar a performance com rastros do lado do cliente

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 todas as solicitações do Firestore, faça o seguinte: e ativar traces 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 na soluçã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
• Rastreamentos de pilha se ocorrer uma falha no cliente

OpenTelemetry

Os traces da biblioteca de cliente Java são instrumentados 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 configurações, é possível exportar traces para um back-end de observabilidade. A maioria dos provedores de serviços de observabilidade oferece exportadores para você usar, como 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 e processa as mensagens do OTLP, e os exporta para o back-end de observabilidade.

Limitações

Os traces do lado do cliente têm as seguintes limitações:

• Os intervalos de traços estão disponíveis para a biblioteca de cliente Java.
• A biblioteca de cliente não produz períodos de trace para listeners em tempo real.

Faturamento

Além do uso do Firestore, o rastreamento do lado do cliente pode gerar cargas.

Não há cobranças pela coleta de rastros ou pelo uso do OpenTelemetry. de análise de dados em nuvem.

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 seu aplicativo grava traces no back-end de observabilidade com as informações Papéis do Identity and Access Management:

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

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

Configurar traces do lado do cliente

Nesta seção, você verá exemplos de configuração 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 do OpenTelemetry. Isso exige código mudanças no aplicativo. Confira os exemplos a seguir:
  • Exportar para um coletor com as APIs do OpenTelemetry
  • Exportar diretamente para um back-end de observabilidade com APIs do OpenTelemetry
• É possível configurar traces sem alterações de código usando agentes automáticos. Você precisa Defina a variável de ambiente FIRESTORE_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 as APIs do OpenTelemetry

O código a seguir configura a biblioteca de cliente Java do Firestore para exportar intervalos com uma taxa de amostragem de 10% para um coletor do OpenTelemetry.

Java (Admin)

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 also use other `BatchSpanProcessorBuilder` methods
// to further customize.
BatchSpanProcessor otlpGrpcSpanProcessor =
  BatchSpanProcessor.builder(otlpGrpcSpanExporter).build();

// Export to a collector that is expecting OTLP using gRPC.
OpenTelemetry otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(otlpGrpcSpaaudit-loggingnProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build());

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().getService();

    

Exporte 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 (Admin)

// 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 also use other `BatchSpanProcessorBuilder` methods
// to further customize.
SpanProcessor gcpBatchSpanProcessor =
  BatchSpanProcessor.builder(gcpTraceExporter).build();

// Export directly to Cloud Trace with 10% trace sampling ratio
OpenTelemetry otel = OpenTelemetrySdk.builder()
        .setTracerProvider(SdkTracerProvider.builder()
            .setResource(resource)
            .addSpanProcessor(gcpBatchSpanProcessor)
            .setSampler(Sampler.traceIdRatioBased(0.1))
            .build());

Firestore firestore = FirestoreOptions
  .newBuilder()
  .setOpenTelemetryOptions(
    FirestoreOpenTelemetryOptions.newBuilder()
      .setTracingEnabled(true)
      .setOpenTelemetry(otel)
      .build())
  .build().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 para otlp e especifique o endpoint em que o agente deve 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

FIRESTORE_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 FIRESTORE_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 taxa de amostragem de 10%.

Terminal

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

    

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 do período de trace.

Exemplo de período de trace

Exemplo de log de eventos

Exemplos de valores de atributos

Exemplo de rastreamento de pilha e evento de exceção

A seguir

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