Monitorar a performance com rastros do lado do cliente
Para monitorar e depurar solicitações do Firestore de ponta a ponta, ative os rastros nas bibliotecas de cliente. 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 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 das bibliotecas de cliente 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 e limites de período.
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 o coletor cuide de outros processamentos, como reprocessamentos, agrupamentos e criptografia. Um coletor é executado junto com seu aplicativo. O coletor recebe, processa e exporta as mensagens OTLP para o back-end de observabilidade.
Limitações
Os rastros do lado do cliente têm as seguintes limitações:
- Os intervalos de rastreamento estão disponíveis para as bibliotecas de cliente Java e Node.js.
- A biblioteca de cliente não produz intervalos de rastreamento para listeners em tempo real.
Faturamento
Além do uso do Firestore, o rastreamento do lado do cliente pode gerar cobranças.
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 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.userGravar rastros roles/cloudtrace.agentRastros de leitura/gravação roles/cloudtrace.adminVerifique se a API Trace está ativada neste projeto.
Configurar rastros do lado do cliente
Esta seção apresenta 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:
- Para configurar rastros sem mudanças no código, siga os exemplos em Instrumentação sem código.
Exportar rastros para um coletor com APIs do OpenTelemetry
O código a seguir configura a biblioteca de cliente para exportar períodos 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.
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
.setTracerProvider(
SdkTracerProvider.builder()
.setResource(resource)
.addSpanProcessor(otlpGrpcSpanProcessor)
.setSampler(Sampler.traceIdRatioBased(0.1))
.build())
.build();
Firestore firestore = FirestoreOptions
.newBuilder()
.setOpenTelemetryOptions(
FirestoreOpenTelemetryOptions.newBuilder()
.setTracingEnabled(true)
.setOpenTelemetry(otel)
.build())
.build().getService();
Node.js (administrador)
import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';
import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";
import pkg3 from "@opentelemetry/exporter-trace-otlp-grpc";
const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;
const { OTLPTraceExporter } = pkg3;
const provider = new NodeTracerProvider(
// Provide your chosen NodeTracerConfig such as sampler and span limit
{
sampler: new TraceIdRatioBasedSampler(0.1),
}
);
provider.addSpanProcessor(new BatchSpanProcessor(new OTLPTraceExporter()));
provider.register();
// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
instrumentations: [
new GrpcInstrumentation(
// (optional): you can add GrpcInstrumentationConfig here
),
],
});
const settings: Settings = {
projectId: 'my-project-id',
preferRest: false,
openTelemetry: {
tracerProvider: trace.getTracerProvider()
}
};
// Initialize Firestore
const firestore = new Firestore(settings);
// Add app code here
// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
await provider
.shutdown()
.catch(error => console.error('Error terminating NodeTracerProvider:', error));
});
Exportar diretamente para um back-end de observabilidade com as APIs do OpenTelemetry
Se o provedor de serviços de observabilidade oferecer suporte à ingestão do OTLP, use o exportador do OpenTelemetry para exportar rastros diretamente para o back-end. O código a seguir configura a biblioteca de cliente para exportar diretamente os períodos de rastreamento para o Cloud Trace com uma taxa de amostragem de 10%.
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
OpenTelemetrySdk otel = OpenTelemetrySdk.builder()
.setTracerProvider(SdkTracerProvider.builder()
.setResource(resource)
.addSpanProcessor(gcpBatchSpanProcessor)
.setSampler(Sampler.traceIdRatioBased(0.1))
.build())
.build();
Firestore firestore = FirestoreOptions
.newBuilder()
.setOpenTelemetryOptions(
FirestoreOpenTelemetryOptions.newBuilder()
.setTracingEnabled(true)
.setOpenTelemetry(otel)
.build())
.build().getService();
Node.js (administrador)
import { trace } from "@opentelemetry/api";
import {GrpcInstrumentation} from '@opentelemetry/instrumentation-grpc';
import { TraceExporter } from "@google-cloud/opentelemetry-cloud-trace-exporter";
import pkg1 from "@opentelemetry/sdk-trace-node";
import pkg2 from "@opentelemetry/instrumentation";
const { NodeTracerProvider, BatchSpanProcessor, TraceIdRatioBasedSampler } = pkg1;
const { registerInstrumentations } = pkg2;
const provider = new NodeTracerProvider(
// Provide your chosen NodeTracerConfig such as sampler and span limits
{
sampler: new TraceIdRatioBasedSampler(0.1),
}
);
provider.addSpanProcessor(new BatchSpanProcessor(new TraceExporter()));
provider.register();
// If you'd like to see gRPC spans (recommended), enable GrpcInstrumentation
registerInstrumentations({
instrumentations: [
new GrpcInstrumentation(
// (optional): you can add GrpcInstrumentationConfig here
),
],
});
const settings: Settings = {
projectId: 'my-project-id',
preferRest: false,
openTelemetry: {
tracerProvider: trace.getTracerProvider()
}
};
// Initialize Firestore
const firestore = new Firestore(settings);
// ...
// Make sure to shut down your TracerProvider to flush any traces left in memory.
process.on('SIGINT', async () => {
await provider
.shutdown()
.catch(error => console.error('Error terminating NodeTracerProvider:', error));
});
Instrumentação sem código
Siga as instruções abaixo para configurar rastros sem mudanças no código:
Java (Admin)
É possível configurar rastros sem mudanças no código usando agentes automáticos. É necessário definir a variável de ambienteFIRESTORE_ENABLE_TRACING=ON. Você também
precisa definir outras configurações,
conforme descrito em
Configuração do agente.
Veja os exemplos a seguir.
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.
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%.
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 \
Node.js (administrador)
Para configurar a instrumentação sem código, siga as instruções do OpenTelemetry para instrumentação em JavaScript. O snippet de código de exemplo a seguir ativa a instrumentação e envia rastros para um coletor do OpenTelemetry:
npm install --save @opentelemetry/api
npm install --save @opentelemetry/auto-instrumentations-node
env \
FIRESTORE_ENABLE_TRACING=ON \
OTEL_TRACES_EXPORTER=otlp \
OTEL_NODE_ENABLED_INSTRUMENTATIONS="http,grpc" \
OTEL_NODE_RESOURCE_DETECTORS="none" \
node --require @opentelemetry/auto-instrumentations-node/register my_app.js
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 intervalo de rastreamento.
Exemplo de período de rastreamento
Exemplo de registro de eventos
Exemplos de valores de atributo
Exemplo de evento de exceção e stack trace
A seguir
- Confira a referência de Atributos e eventos de período de trace.
- Saiba mais sobre o monitoramento do lado do servidor.