Como configurar o Cloud Trace para Go

É possível ativar o Cloud Trace para aplicativos Go usando o OpenCensus. O OpenCensus é um conjunto de bibliotecas de instrumentação para coletar dados de trace e métrica que funcionam com vários back-ends. Para ver os detalhes mais recentes sobre o OpenCensus para Go, além de documentação e exemplos adicionais, consulte opencensus-go.

Como instalar o pacote

Recupere o pacote de trace do OpenCensus:

go get -u go.opencensus.io/trace

Como configurar o exportador do Stackdriver

Para exportar os dados de Trace coletados, use um exportador do Stackdriver.


import (
	"log"
	"os"

	"contrib.go.opencensus.io/exporter/stackdriver"
	"go.opencensus.io/trace"
)

func main() {
	// Create and register a OpenCensus Stackdriver Trace exporter.
	exporter, err := stackdriver.NewExporter(stackdriver.Options{
		ProjectID: os.Getenv("GOOGLE_CLOUD_PROJECT"),
	})
	if err != nil {
		log.Fatal(err)
	}
	trace.RegisterExporter(exporter)
}

Se você estiver executando na infraestrutura do Google Cloud, não será necessário definir o campo ProjectID para o ID do projeto do Google Cloud porque a biblioteca de cliente para Go coleta automaticamente esses dados de um servidor de metadados do Google Cloud.

Se você não estiver em execução na infraestrutura do Google Cloud, defina o campo ProjectID como o ID do projeto do Google Cloud. No código de exemplo, uma variável de ambiente é usada, e o aplicativo foi modificado para ler essa variável.

Como configurar a integração com o Cloud Logging

Para informações sobre como enviar dados do Cloud Trace para o Cloud Logging, consulte Como integrar ao Cloud Logging.

Configurar sua plataforma

Você pode usar o Cloud Trace no Google Cloud e em outras plataformas.

Como executar no Google Cloud

Quando seu aplicativo está em execução no Google Cloud, não é necessário fornecer credenciais de autenticação na forma de uma conta de serviço para a biblioteca de cliente. No entanto, verifique se o escopo de acesso da API Cloud Trace está ativado no Google Cloud Platform.

Para uma lista de ambientes compatíveis do Google Cloud, consulte Suporte ao ambiente.

Para as seguintes configurações, as definições de escopo de acesso padrão ativam a API Cloud Trace:

  • Ambiente flexível do App Engine
  • Ambiente padrão do App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

Se você usa escopos de acesso personalizados, verifique se o escopo de acesso da API Cloud Trace está ativado:

  • Para mais informações sobre como configurar os escopos de acesso para o ambiente usando o Console do Google Cloud, consulte Como configurar o projeto do Google Cloud.

  • Para usuários gcloud, especifique os escopos de acesso usando a sinalização --scopes e inclua o escopo de acesso trace.append da API Cloud Trace. Por exemplo, para criar um cluster do GKE com apenas a API Cloud Trace ativada, faça o seguinte:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Execução local e em outro lugar

Se o aplicativo estiver em execução fora do Google Cloud, forneça as credenciais de autenticação na forma de uma conta de serviço para a biblioteca de cliente. A conta de serviço precisa conter o papel de agente do Cloud Trace. Para instruções, consulte Como criar uma conta de serviço.

As bibliotecas de cliente do Google Cloud usam o Application Default Credentials (ADC) para encontrar as credenciais do aplicativo. Forneça essas credenciais definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Aplicativo do Trace de amostra para Go


// Sample trace_quickstart traces incoming and outgoing requests.
package main

import (
	"log"
	"net/http"
	"os"

	"contrib.go.opencensus.io/exporter/stackdriver"
	"contrib.go.opencensus.io/exporter/stackdriver/propagation"
	"go.opencensus.io/plugin/ochttp"
	"go.opencensus.io/trace"
)

func main() {
	// Create and register a OpenCensus Stackdriver Trace exporter.
	exporter, err := stackdriver.NewExporter(stackdriver.Options{
		ProjectID: os.Getenv("GOOGLE_CLOUD_PROJECT"),
	})
	if err != nil {
		log.Fatal(err)
	}
	trace.RegisterExporter(exporter)

	// By default, traces will be sampled relatively rarely. To change the
	// sampling frequency for your entire program, call ApplyConfig. Use a
	// ProbabilitySampler to sample a subset of traces, or use AlwaysSample to
	// collect a trace on every run.
	//
	// Be careful about using trace.AlwaysSample in a production application
	// with significant traffic: a new trace will be started and exported for
	// every request.
	trace.ApplyConfig(trace.Config{DefaultSampler: trace.AlwaysSample()})

	client := &http.Client{
		Transport: &ochttp.Transport{
			// Use Google Cloud propagation format.
			Propagation: &propagation.HTTPFormat{},
		},
	}

	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		req, _ := http.NewRequest("GET", "https://www.google.com", nil)

		// The trace ID from the incoming request will be
		// propagated to the outgoing request.
		req = req.WithContext(r.Context())

		// The outgoing request will be traced with r's trace ID.
		resp, err := client.Do(req)
		if err != nil {
			log.Fatal(err)
		}
		// Because we don't read the resp.Body, need to manually call Close().
		resp.Body.Close()
	})
	http.Handle("/foo", handler)

	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}
	log.Printf("Listening on port %s", port)

	// Use an ochttp.Handler in order to instrument OpenCensus for incoming
	// requests.
	httpHandler := &ochttp.Handler{
		// Use the Google Cloud propagation format.
		Propagation: &propagation.HTTPFormat{},
	}
	if err := http.ListenAndServe(":"+port, httpHandler); err != nil {
		log.Fatal(err)
	}
}

Como visualizar os traces

Após a implantação, é possível ver os traces no Visualizador de traces do Console do Cloud.

Acesse a página do visualizador do Trace

Solução de problemas

Para informações sobre como solucionar problemas com o Cloud Trace, acesse a página de solução de problemas.

Falha no upload dos períodos do exportador do Go OpenCensus

Veja a seguir exemplos de erros que ocorrem quando a biblioteca do bundler usada pelo exportador não consegue gerenciar o número de períodos que o aplicativo está gerando e fazendo upload:

OpenCensus Stackdriver exporter: failed to upload span: buffer full
OpenCensus Stackdriver exporter: failed to upload 183 spans: buffer full

Para resolver essa situação, tente uma ou mais das seguintes opções:

  • Na estrutura Options transmitida para o construtor traceExporter, aumente o valor do campo TraceSpansBufferMaxBytes. Esse campo opcional especifica o número máximo de bytes usados para armazenar períodos em buffer. O valor padrão é 8 MB.

  • No objeto Options passado para o construtor traceExporter, diminua os valores dos seguintes campos:

    • BundleDelayThreshold: esse campo opcional especifica o tempo máximo que o exportador pode aguardar antes de fazer o upload de períodos de trace. O valor padrão desse campo é de dois segundos.

    • BundleCountThreshold: este campo opcional especifica o número de períodos que podem ser armazenados em buffer. O valor padrão desse campo é 50.

  • Exporte menos períodos. Para reduzir o número de períodos que você exporta, configure um amostrador global ou transmita um amostragem para cada StartSpan. Para ver uma amostra do código e mais informações sobre essas configurações, consulte Amostragem do OpenCensus (em inglês).

Recursos