Go e OpenTelemetry

Esta página é voltada a desenvolvedores de aplicativos que querem coletar dados do Cloud Trace para aplicativos Go usando o OpenTelemetry. O OpenTelemetry é um framework de instrumentação neutro em relação a fornecedores que pode ser usado para coletar dados de rastreamento e métricas. Para mais informações sobre como instrumentar seu código, consulte Instrumentação e observabilidade.

  • 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 conferir conteúdo de referência do OpenTelemetry, consulte:

Para ver os detalhes mais recentes sobre o OpenTelemetry para Go, além de documentação e exemplos extras, consulte OpenTelemetry.

Antes de começar

  1. No painel de navegação do console do Google Cloud, selecione APIs e serviços, clique em Ativar APIs e serviços e ative a API Cloud Trace:

    Acessar as configurações da API Cloud Trace

  2. Se a mensagem API ativada for exibida, quer dizer que a API já está ativada. Caso contrário, clique no botão Ativar.

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 de como usar o OpenTelemetry, consulte o repositório do OpenTelemetry para Go do GitHub.

Compute Engine

Instale o pacote OpenTelemetry:

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

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

import (
	"context"
	"errors"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/contrib/detectors/gcp"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

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.New: %v", err)
	}

	// Identify your application using resource detection
	res, err := resource.New(ctx,
		// Use the GCP resource detector to detect information about the GCP platform
		resource.WithDetectors(gcp.NewDetector()),
		// Keep the default detectors
		resource.WithTelemetrySDK(),
		// Add your own custom attributes to identify your application
		resource.WithAttributes(
			semconv.ServiceNameKey.String("my-application"),
		),
	)
	if errors.Is(err, resource.ErrPartialResource) || errors.Is(err, resource.ErrSchemaURLConflict) {
		log.Println(err)
	} else if err != nil {
		log.Fatalf("resource.New: %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),
		sdktrace.WithResource(res),
	)
	defer tp.Shutdown(ctx) // flushes any pending spans, and closes connections.
	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 e 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 do exemplo é recomendada para todos os ambientes operacionais, incluindo o Cloud Run, em que os contêineres podem ser encerrados a qualquer momento.

Você nomeia a instância Tracer no momento da criação. 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 várias instâncias.

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

GKE;

Adicione o seguinte ao seu Dockerfile:

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

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

import (
	"context"
	"errors"
	"log"
	"os"

	texporter "github.com/GoogleCloudPlatform/opentelemetry-operations-go/exporter/trace"
	"go.opentelemetry.io/contrib/detectors/gcp"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/sdk/resource"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"
	semconv "go.opentelemetry.io/otel/semconv/v1.24.0"
)

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.New: %v", err)
	}

	// Identify your application using resource detection
	res, err := resource.New(ctx,
		// Use the GCP resource detector to detect information about the GCP platform
		resource.WithDetectors(gcp.NewDetector()),
		// Keep the default detectors
		resource.WithTelemetrySDK(),
		// Add your own custom attributes to identify your application
		resource.WithAttributes(
			semconv.ServiceNameKey.String("my-application"),
		),
	)
	if errors.Is(err, resource.ErrPartialResource) || errors.Is(err, resource.ErrSchemaURLConflict) {
		log.Println(err)
	} else if err != nil {
		log.Fatalf("resource.New: %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),
		sdktrace.WithResource(res),
	)
	defer tp.Shutdown(ctx) // flushes any pending spans, and closes connections.
	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 e 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 do exemplo é recomendada para todos os ambientes operacionais, incluindo o Cloud Run, em que os contêineres podem ser encerrados a qualquer momento.

Você nomeia a instância Tracer no momento da criação. 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 várias instâncias.

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

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

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 do ambiente usando o console do Google Cloud, consulte Como configurar o projeto do Google Cloud.

  • 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.

É possível fornecer essas credenciais de três maneiras:

  • Executar gcloud auth application-default login

  • Coloque a conta de serviço em um caminho padrão para seu sistema operacional. Veja a seguir os caminhos padrão para Windows e Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Defina a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho para sua conta de serviço:

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"

Ver traces

No painel de navegação do console do Google Cloud, selecione Trace e, em seguida, Trace Explorer:

Acessar o Explorador de traces

Solução de problemas

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