Visão geral da instrumentação para o Cloud Trace

Neste documento, você encontra uma visão geral sobre como instrumentar seu aplicativo para o Cloud Trace. Para instruções detalhadas sobre como configurar o Cloud Trace, consulte as páginas de configuração específicas da linguagem.

O Cloud Trace fornece dados de geração de trace distribuídos para seus aplicativos. Depois de instrumentar seu aplicativo, você pode inspecionar os dados de latência de uma única solicitação e ver a latência agregada de um aplicativo inteiro no console do Cloud Trace.

O Cloud Trace recomenda o uso do OpenTelemetry. OpenTelemetry é um produto de código aberto da combinação entre OpenCensus e OpenTracing.

Quando instrumentar seu aplicativo

Para que o aplicativo envie traces ao Cloud Trace, ele precisa ser instrumentado. Você pode instrumentar seu código usando as bibliotecas de cliente do Google. No entanto, é recomendável usar o OpenTelemetry ou o OpenCensus para instrumentar seu aplicativo. Esses são pacotes de trace de código aberto. O OpenTelemetry está ativamente em desenvolvimento e é o pacote recomendado.

Como usar aplicativos

Há três maneiras de implementar a geração de trace para seus aplicativos:

  • Use o OpenTelemetry e a biblioteca de cliente do Cloud Trace associada. Essa é a maneira recomendada de instrumentar seus aplicativos.

  • Use o OpenCensus se uma biblioteca de cliente do OpenTelemetry não estiver disponível para sua linguagem.

  • Use a API do Cloud Trace e grave métodos personalizados para enviar dados de geração de trace ao Cloud Trace.

A tabela a seguir lista a instrumentação recomendada para cada linguagem de programação:

Idioma Instrumentação recomendada
C# .NET API Cloud Trace
Go OpenTelemetry
Java OpenTelemetry
Node.js OpenTelemetry
PHP OpenCensus
Python OpenTelemetry
Ruby Cloud Trace API

Quando criar períodos

As bibliotecas de cliente do Cloud Trace normalmente mantêm um contexto de trace global que contém informações sobre o período atual, incluindo o ID do trace e se o trace é amostrado. Essas bibliotecas geralmente criam períodos nos limites da RPC. No entanto, talvez seja necessário criar períodos se o algoritmo de criação padrão não for suficiente para suas necessidades.

O período ativo atual pode ser acessado pelo contexto de trace global, que às vezes é agrupado em um objeto Trace. É possível adicionar informações relevantes ao aplicativo usando anotações e tags personalizadas em períodos existentes ou criar novos intervalos filhos com as próprias anotações e tags para rastrear o comportamento do aplicativo com granularidade mais precisa. Como o contexto é global, os aplicativos com várias linhas de execução que atualizam o contexto precisam usar o isolamento adequado.

Quando fornecer credenciais de autenticação

Você não precisa fornecer credenciais de autenticação ao aplicativo nem especificar o ID do projeto do Google Cloud no aplicativo quando estiver em execução no Google Cloud. Para algumas linguagens, você precisa especificar o ID do projeto do Google Cloud, mesmo que esteja em execução no Google Cloud.

Se você estiver executando fora do Google Cloud, precisará fornecer credenciais de autenticação ao aplicativo. Você também precisa especificar o ID do projeto do Google Cloud no aplicativo.

Para mais detalhes, acesse as páginas de configuração de linguagens específicas.

Como forçar o rastreamento de uma solicitação

O Cloud Trace não cria amostras de todas as solicitações. Por exemplo, se você usa Java e OpenCensus, apenas uma solicitação de cada 10.000 é coletada. Se você estiver usando o App Engine, as solicitações serão amostradas a uma taxa de 0,1 solicitação por segundo para cada instância do App Engine. Se você usa a API Cloud Trace, pode configurar taxas personalizadas. Alguns pacotes, como o pacote Java OpenCensus, são compatíveis com a configuração da taxa de amostragem.

Se você configurar um microsserviço com uma taxa de amostragem, a taxa será aplicada somente às solicitações iniciadas a ele. Se você não configurar uma taxa de amostragem para um microsserviço, a taxa de amostragem do contexto principal determinará a do microsserviço.

Para forçar a geração de trace de uma solicitação específica, adicione um cabeçalho X-Cloud-Trace-Context à solicitação. A especificação do cabeçalho é:

"X-Cloud-Trace-Context: TRACE_ID/SPAN_ID;o=TRACE_TRUE"

Em que:

  • TRACE_ID é um valor hexadecimal de 32 caracteres que representa um número de 128 bits. Ele precisa ser exclusivo entre as solicitações, a menos que você queira agrupar intencionalmente as solicitações.

  • SPAN_ID é a representação decimal do ID de período (não assinado). Ele precisa ser gerado aleatoriamente e exclusivamente no seu trace. Para solicitações subsequentes, defina SPAN_ID como o ID do período da solicitação pai. Consulte a descrição de TraceSpan (REST, RPC) para mais informações sobre traces aninhados.

  • TRACE_TRUE precisa ser 1 para rastrear esta solicitação. Especifique 0 para não rastrear a solicitação.

Por exemplo, para forçar um trace com cURL:

curl "http://www.example.com" --header "X-Cloud-Trace-Context:
  105445aa7843bc8bf206b12000100000/1;o=1"

Como criar exemplares do Cloud Trace

O OpenCensus pode criar exemplos do Cloud Trace ao gravar dados de série temporal para serviços do gRPC. Exemplas são pontos de exemplo que podem ser anexados a medições de distribuição. Por exemplo, você pode querer que uma métrica de latência inclua um rótulo para um URL. Não é possível adicionar um rótulo de URL à métrica porque ela teria uma cardinalidade alta, o que resulta em problemas de desempenho. No entanto, você pode criar um exemplo que registre o URL. Para ver mais informações, consulte Exemplar.

Para ver exemplos, faça o seguinte:

  1. Crie um gráfico de uma métrica de valor de distribuição e defina o tipo do gráfico como Gráfico de mapa de calor. É possível criar um gráfico em um painel ou usar o Metrics Explorer.
  2. Na barra de ferramentas do gráfico, selecione Trace exemplars na barra de ferramentas do gráfico. Para ver exemplos, consulte a barra de ferramentas do gráfico.

Para criar exemplos, é possível escrever suas próprias métricas personalizadas ou usar bibliotecas como o OpenCensus. Para informações gerais sobre métricas personalizadas, consulte:

O exemplo de código a seguir mostra como escrever um exemplo.

  1. Crie as informações adicionais a serem incluídas nas contagens do bucket:

    • O objeto SpanContext armazena um ID do projeto, um ID de trace e um ID de período. Verifique se esses campos correspondem aos valores de um trace que foi enviado ao Cloud Trace. O Cloud Monitoring usa esses campos para identificar o trace a ser exibido.

    • O objeto DroppedLabels define os outros rótulos. O exemplo de código a seguir adiciona um rótulo. A chave é "Label" e o valor é "Dropped". No exemplo de métrica de latência descrito anteriormente, é possível adicionar um rótulo com a chave de "URL".

  2. Escreva um Point para a série temporal:

    • O campo TimeInterval define os horários de início e término do ponto.
    • O campo DistributionValue especifica os dados. Os dados incluem a definição dos buckets do Distribution e os valores do bucket. Esse campo também inclui todos os exemplos a serem gravados com os dados. O exemplo grava dois exemplos de exemplo, um deles inclui o contexto de período e objetos de rótulos descartados.
import (
	"fmt"
	"time"

	googlepb "github.com/golang/protobuf/ptypes/timestamp"
	distributionpb "google.golang.org/genproto/googleapis/api/distribution"
	monitoringpb "google.golang.org/genproto/googleapis/monitoring/v3"
	"google.golang.org/protobuf/types/known/anypb"
)

// Generates metric TimeSeries points containing Exemplars with attached tracing span.
func createDataPointWithExemplar(projectID string) (*monitoringpb.Point, error) {
	// projectID := "my-cloud-project-id"
	end := time.Now().Unix()
	traceId := "0000000000000001"
	spanId := "00000001"
	spanCtx, err := anypb.New(&monitoringpb.SpanContext{
		SpanName: fmt.Sprintf("projects/%s/traces/%s/spans/%s", projectID, traceId, spanId),
	})
	if err != nil {
		return nil, err
	}
	droppedLabels, err := anypb.New(&monitoringpb.DroppedLabels{
		Label: map[string]string{"Label": "Dropped"},
	})
	if err != nil {
		return nil, err
	}
	dataPoint := &monitoringpb.Point{
		Interval: &monitoringpb.TimeInterval{
			StartTime: &googlepb.Timestamp{Seconds: end - 60},
			EndTime:   &googlepb.Timestamp{Seconds: end},
		},
		Value: &monitoringpb.TypedValue{Value: &monitoringpb.TypedValue_DistributionValue{
			DistributionValue: &distributionpb.Distribution{
				Count: 14,
				BucketOptions: &distributionpb.Distribution_BucketOptions{Options: &distributionpb.Distribution_BucketOptions_LinearBuckets{
					LinearBuckets: &distributionpb.Distribution_BucketOptions_Linear{NumFiniteBuckets: 2, Width: 3, Offset: 0},
				}},
				BucketCounts: []int64{5, 6, 3},
				Exemplars: []*distributionpb.Distribution_Exemplar{
					{Value: 1, Timestamp: &googlepb.Timestamp{Seconds: end - 30}, Attachments: []*anypb.Any{spanCtx, droppedLabels}},
					{Value: 4, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
				},
			},
		}},
	}
	return dataPoint, nil
}

Como configurar seu projeto do Google Cloud

Para usar o Cloud Trace, seu projeto do Google Cloud precisa ter a API Cloud Trace ativada. Essa configuração permite que o projeto do Google Cloud receba dados de trace de fontes autenticadas.

Por padrão, os projetos do Google Cloud têm a API Cloud Trace ativada, e você não precisa fazer nada. Se você modificou os escopos de acesso do seu projeto do Google Cloud e quer verificar as configurações, faça o seguinte:

  1. No console do Google Cloud, acesse APIs e serviços:

    Acessar APIs e Serviços

  2. Clique em Ativar APIs e serviços.

  3. Na barra de pesquisa, digite Trace API.

  4. Se a API ativada for exibida, essa API já estará ativada e não haverá nada para fazer. Caso contrário, clique em Ativar.

A seguir

Para informações detalhadas de configuração, amostras e links para o GitHub e outros repositórios de código aberto, acesse a página de configuração da sua linguagem: