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:
- É possível configurar traces com as APIs OpenTelemetry. Isso exige mudanças no código do aplicativo. Confira os exemplos a seguir:
- É possível configurar rastreamentos 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 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
Exemplo de log de eventos
Exemplos de valores de atributos
A seguir
- Consulte a referência para Atributos e eventos de intervalo de rastreamento.
- Saiba mais sobre o monitoramento do lado do servidor.