Visão geral

Neste documento, você encontrará 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.

Geração de trace de instrumentação para 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ê usar a API Cloud Trace, poderá 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 pai determinará a taxa de amostragem para o 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"

Onde:

  • 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. É possível usar UUIDs.

  • 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 as 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 cria exemplares do Cloud Trace quando grava dados de séries temporais para serviços gRPC. Para visualizá-los, crie um gráfico e use a barra de ferramentas do gráfico para ativar a exibição. Para mais informações, consulte Como usar a barra de ferramentas do gráfico.

Se você tiver interesse em gravar métricas personalizadas, consulte os seguintes recursos:

Se você estiver criando métricas personalizadas, crie exemplares. O snippet de código Go a seguir ilustra a criação de um único Point em uma série temporal. O primeiro elemento é o intervalo de tempo, rotulado por Interval, e o segundo é o valor. O valor é uma instância de um objeto TypedValue e precisa ser resolvido para um distributionValue.

import (
	"time"

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

func createDataPointWithExemplar() *monitoringpb.Point {
	end := time.Now().Unix()
	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{
					&distributionpb.Distribution_Exemplar{Value: 1, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
					&distributionpb.Distribution_Exemplar{Value: 4, Timestamp: &googlepb.Timestamp{Seconds: end - 30}},
				},
			},
		}},
	}
	return dataPoint
}

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 mensagem API ativada for exibida, quer dizer que a API já está ativada e você não precisa fazer nada. 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: