Como usar o OpenTelemetry com Go

É possível ativar os aplicativos do Cloud Trace para Go usando o OpenTelemetry. O OpenTelemetry é um conjunto de bibliotecas de instrumentação para coletar dados de rastreamento e métrica que funcionam com vários back-ends. Para ver os detalhes mais recentes sobre o OpenTelemetry para Go, além de documentação e exemplos adicionais, acesse https://opentelemetry.io/.

Instalação e configuração

Para coletar traces, siga estas etapas:

  • Instale as bibliotecas de cliente do OpenTelemetry.
  • Importe os pacotes de trace do OpenTelemetry.
  • Configure o OpenTelemetry para exportar períodos para o Cloud Trace.
  • Ative o escopo de acesso da API Cloud Trace.

Como instalar, inicializar e usar o cliente

Consulte as instruções a seguir para instrumentar seus aplicativos Go no Compute Engine e no Google Kubernetes Engine.

Compute Engine

Instale o pacote OpenTelemetry:

go get -u go.opentelemetry.io/otel
go get -u github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace

Importe pacotes de exportação do OpenTelemetry e do Cloud Trace:

import (
	"context"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/otel/api/global"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Crie o exportador e o provedor de trace:

func main() {
	// Create exporter.
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.NewExporter(texporter.WithProjectID(projectID))
	if err != nil {
		log.Fatalf("texporter.NewExporter: %v", err)
	}

	// Create trace provider with the exporter.
	//
	// By default it uses AlwaysSample() which samples all traces.
	// In a production environment or high QPS setup please use
	// ProbabilitySampler set at the desired probability.
	// Example:
	//   config := sdktrace.Config{DefaultSampler:sdktrace.ProbabilitySampler(0.0001)}
	//   tp, err := sdktrace.NewProvider(sdktrace.WithConfig(config), ...)
	tp, err := sdktrace.NewProvider(sdktrace.WithSyncer(exporter))
	if err != nil {
		log.Fatal(err)
	}
	global.SetTraceProvider(tp)

	ctx := context.Background()
	// Create custom span.
	tracer := global.TraceProvider().Tracer("example.com/trace")
	err = func(ctx context.Context) error {
		ctx, span := tracer.Start(ctx, "foo")
		defer span.End()

		// Do some work.

		return nil
	}(ctx)
}

Aqui, example.com/trace refere-se ao nome da instância do trace e foo é o nome do período. A instância do trace deve ser nomeada de acordo com o componente cujos dados estão sendo coletados, porque é possível ter várias instâncias do trace.

GKE

Adicione o seguinte ao seu Dockerfile:

RUN go get -u go.opentelemetry.io/otel

Importe pacotes de exportação do OpenTelemetry e do Cloud Trace:

import (
	"context"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/otel/api/global"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Crie o exportador e o provedor de trace:

func main() {
	// Create exporter.
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.NewExporter(texporter.WithProjectID(projectID))
	if err != nil {
		log.Fatalf("texporter.NewExporter: %v", err)
	}

	// Create trace provider with the exporter.
	//
	// By default it uses AlwaysSample() which samples all traces.
	// In a production environment or high QPS setup please use
	// ProbabilitySampler set at the desired probability.
	// Example:
	//   config := sdktrace.Config{DefaultSampler:sdktrace.ProbabilitySampler(0.0001)}
	//   tp, err := sdktrace.NewProvider(sdktrace.WithConfig(config), ...)
	tp, err := sdktrace.NewProvider(sdktrace.WithSyncer(exporter))
	if err != nil {
		log.Fatal(err)
	}
	global.SetTraceProvider(tp)

	ctx := context.Background()
	// Create custom span.
	tracer := global.TraceProvider().Tracer("example.com/trace")
	err = func(ctx context.Context) error {
		ctx, span := tracer.Start(ctx, "foo")
		defer span.End()

		// Do some work.

		return nil
	}(ctx)
}

Aqui, example.com/trace refere-se ao nome da instância do trace e foo é o nome do período. A instância do trace recebe o nome do componente cujos dados estão sendo coletados para torná-lo identificável. você pode ter várias instâncias do trace.

Como criar um período personalizado

É possível adicionar mais informações ao trace criado pelo sistema criando um período personalizado.

Para criar um período personalizado, adicione o seguinte trecho ao código-fonte:

ctx := context.Background()
// Create custom span.
tracer := global.TraceProvider().Tracer("example.com/trace")
err = func(ctx context.Context) error {
	ctx, span := tracer.Start(ctx, "foo")
	defer span.End()

	// Do some work.

	return nil
}(ctx)

Aqui, example.com/trace refere-se ao nome da instância do trace e foo é o nome do período. A instância do trace recebe o nome do componente cujos dados estão sendo coletados para torná-lo identificável. você pode ter várias instâncias do trace.

Como 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 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

Se você usar escopos de acesso personalizados, verifique se o escopo de acesso da API Cloud Trace está ativado. Para usuários do gcloud, especifique os escopos de acesso usando a sinalização --scopes e inclua o escopo de acesso da API Cloud Trace trace.append. 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"

Otimização de desempenho

Para reduzir o impacto no desempenho dos dados de trace de relatórios, use um processo em segundo plano para enviar esses dados. Para configurar relatórios em segundo plano de dados de trace, inclua transport=AsyncTransport ao inicializar o StackdriverExporter.

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

Resolver problemas

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