Go e OpenTelemetry

Esta página foi projetada para desenvolvedores de aplicativos que querem coletar dados do Cloud Trace para aplicativos Go usando o OpenTelemetry. O OpenTelemetry é um conjunto de bibliotecas de instrumentação para coletar dados de traces e métricas. Elas funcionam com vários back-ends. Para coletar traces com o OpenTelemetry e o Go, faça o seguinte, conforme descrito nesta página:

  • Instale os pacotes do OpenTelemetry.
  • Configure seu aplicativo para exportar períodos para o Cloud Trace.
  • Configure sua plataforma.

Para ver informações sobre a versão, consulte:

Para ver os detalhes mais recentes sobre o OpenTelemetry para Go, junto com a documentação e exemplos adicionais, consulte OpenTelemetry.

Antes de começar

Verifique se a API Cloud Trace está ativada no seu projeto do Google Cloud:

  1. Clique no botão a seguir ou no Console do Google Cloud, selecione APIs e serviços e, em seguida, selecione API Cloud Trace:

    Acessar a API do Trace

  2. Na página API Cloud Trace, se um botão chamado Ativar for exibido, clique nele. Se esse botão não for exibido, a API Cloud Trace estará ativada para o projeto selecionado.

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. Para um exemplo geral do uso do OpenTelemetry, consulte o repositório do GitHub do OpenTelemetry para Go.

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"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Crie o exportador e o provedor de trace:

func main() {
	// Create exporter.
	ctx := context.Background()
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.New(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
	// probabilistic sampling.
	// Example:
	//   tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.0001)), ...)
	tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
	defer tp.ForceFlush(ctx) // flushes any pending spans
	otel.SetTracerProvider(tp)

	// Create custom span.
	tracer := otel.GetTracerProvider().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)
}

Ao criar o exportador, você fornece informações sobre o identificador de projeto do Google Cloud. Neste exemplo, o identificador é armazenado na variável de ambiente GOOGLE_CLOUD_PROJECT.

O aplicativo de exemplo chama a função WithBatcher para configurar o provedor de trace para enviar períodos ao Cloud Monitoring usando um processo em segundo plano. O exemplo também está configurado para chamar a função Shutdown do exportador na saída do aplicativo. Quando Shutdown é executado, ele envia todos os períodos pendentes para o Cloud Monitoring. A configuração mostrada na amostra é a implementação recomendada para todos os ambientes operacionais, incluindo o Cloud Run, em que os contêineres podem ser encerrados a qualquer momento.

Ao criar a instância Tracer, você fornece um nome a ela. No exemplo, o nome é example.com/trace. Recomendamos que você nomeie essas instâncias depois que o componente for rastreado, porque essa estratégia permite que você tenha várias instâncias.

Quando o exemplo é executado, um único trace chamado foo é criado.

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"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
)

Crie o exportador e o provedor de trace:

func main() {
	// Create exporter.
	ctx := context.Background()
	projectID := os.Getenv("GOOGLE_CLOUD_PROJECT")
	exporter, err := texporter.New(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
	// probabilistic sampling.
	// Example:
	//   tp := sdktrace.NewTracerProvider(sdktrace.WithSampler(sdktrace.TraceIDRatioBased(0.0001)), ...)
	tp := sdktrace.NewTracerProvider(sdktrace.WithBatcher(exporter))
	defer tp.ForceFlush(ctx) // flushes any pending spans
	otel.SetTracerProvider(tp)

	// Create custom span.
	tracer := otel.GetTracerProvider().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)
}

Ao criar o exportador, você fornece informações sobre o identificador de projeto do Google Cloud. Neste exemplo, o identificador é armazenado na variável de ambiente GOOGLE_CLOUD_PROJECT.

O aplicativo de exemplo chama a função WithBatcher para configurar o provedor de trace para enviar períodos ao Cloud Monitoring usando um processo em segundo plano. O exemplo também está configurado para chamar a função Shutdown do exportador na saída do aplicativo. Quando Shutdown é executado, ele envia todos os períodos pendentes para o Cloud Monitoring. A configuração mostrada na amostra é a implementação recomendada para todos os ambientes operacionais, incluindo o Cloud Run, em que os contêineres podem ser encerrados a qualquer momento.

Ao criar a instância Tracer, você fornece um nome a ela. No exemplo, o nome é example.com/trace. Recomendamos que você nomeie essas instâncias depois que o componente for rastreado, porque essa estratégia permite que você tenha várias instâncias.

Quando o exemplo é executado, um único trace chamado foo é criado.

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 com o nome foo, adicione o seguinte ao código-fonte:

// Create custom span.
tracer := otel.GetTracerProvider().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 rastreador.

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 do Google Cloud compatíveis, 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ê usar escopos de acesso personalizados, verifique se o escopo de acesso da API Cloud Trace está ativado:

  • Para 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"

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.