Migrar do exportador de rastreamento para o endpoint OTLP

É possível migrar aplicativos Java, Go, Python e Node.js instrumentados manualmente de um exportador de trace do Google Cloud para um exportador OTLP do OpenTelemetry em processo. O exportador do OTLP envia dados de trace diretamente para a API Telemetry (OTLP) no seu projeto do Google Cloud usando protocolos de exportação compatíveis (gRPC ou http/protobuf).

Essa configuração exporta apenas dados de trace e se aplica somente a exportadores em processo. Se o aplicativo usa um coletor do OpenTelemetry, consulte Exemplos de instrumentação baseada em coletor e Coletor do OpenTelemetry criado pelo Google.

Por que você deve migrar

Os SDKs do OpenTelemetry geram dados de registro, métrica e trace em um formato que geralmente é consistente com os arquivos proto definidos pelo protocolo OpenTelemetry. No entanto, os campos podem ser convertidos de um tipo de dados específico do OpenTelemetry para um tipo de dados JSON antes do armazenamento.

Quando um aplicativo exporta esses dados para um projeto do Google Cloud usando um exportador do Google Cloud , esse exportador executa as seguintes etapas:

1. Transforma os dados registrados do formato OTLP em um formato reservado definido pela API Cloud Logging, pela API Cloud Monitoring ou pela API Cloud Trace.
2. Envia os dados transformados para a API apropriada, que são armazenados no projeto do Google Cloud .

Para dados de trace, recomendamos que você migre seu aplicativo para usar a API Telemetry (OTLP) para exportar dados, porque essa exportação não requer uma transformação de dados. A transformação de dados pode causar a perda de alguns dados. Por exemplo, o formato reservado pode ter limites menores para determinados campos, ou alguns campos do OTLP podem não ser mapeados para um campo no formato reservado.

Amostras disponíveis

Os aplicativos de exemplo mencionados nesta página estão disponíveis no GitHub. A maioria dos aplicativos é configurada para exportar dados de trace usando gRPC, o que significa que eles enviam dados codificados em protobuf no formato de transmissão gRPC por conexões HTTP/2. Também fornecemos um exemplo de código para aplicativos configurados para exportar dados de trace como dados codificados em protobuf por conexões HTTP:

• Aplicativo Java

  O aplicativo de exemplo está configurado para exportar traces como dados codificados em protobuf por conexões HTTP. Se você preferir usar o gRPC, a instrumentação neste exemplo é aplicável. No entanto, é necessário modificar as propriedades do sistema que o módulo de configuração automática consome. O aplicativo de exemplo especifica o exportador http/protobuf. Para usar o gRPC, mude essa configuração para grpc.

  Recomendamos que seus aplicativos Java, como o aplicativo de exemplo, usem o módulo de configuração automática do SDK do OpenTelemetry para configurar o SDK.

• Aplicativo Go que usa gRPC e aplicativo Go que usa HTTP

  Há dois repositórios do Go. Em um repositório, o aplicativo de amostra usa o gRPC. O exemplo no outro repositório usa dados codificados em protobuf em conexões HTTP.

• Repositório do Python

  Esse repositório contém duas amostras, uma para gRPC e outra que usa dados codificados em protobuf em conexões HTTP.

• Aplicativo Node.js

  Esse repositório contém duas amostras, uma para gRPC e outra que usa dados codificados em protobuf em conexões HTTP.

Antes de começar

Antes de migrar o aplicativo para enviar dados de trace ao endpoint do OTLP, ative a API Telemetry e verifique se você recebeu os papéis necessários do Identity and Access Management (IAM). Também pode ser necessário conceder papéis do IAM a uma conta de serviço.

Ativar o faturamento e a API Telemetry

Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs, if any are not already enabled.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Configurar permissões

• Para garantir que a conta de serviço usada pelo aplicativo tenha as permissões necessárias para gravar dados de registro, métrica e trace, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço usada pelo aplicativo:

  Importante: conceda esses papéis à conta de serviço usada pelo aplicativo, não à sua conta de usuário. Se os papéis não forem concedidos ao principal correto, poderão ocorrer erros de permissão.
  • Gravador de registros (roles/logging.logWriter) no projeto
  • Gravador de métricas do Monitoring (roles/monitoring.metricWriter) no seu projeto
  • Gravador de traces de telemetria do Cloud (roles/telemetry.tracesWriter) no seu projeto
  • Consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer) no projeto de cota

  Para saber como configurar um projeto de cota, consulte Definir o projeto de cota.

  Para saber mais sobre o Application Default Credentials (ADC), consulte Como o Application Default Credentials funciona e Configurar o Application Default Credentials (ADC) para um ambiente de desenvolvimento local.

• Para ter as permissões necessárias para visualizar os dados de registro, métrica e trace, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

  • Visualizador de registros (roles/logging.viewer)
  • Leitor do Monitoring (roles/monitoring.viewer)
  • Usuário do Cloud Trace (roles/cloudtrace.user)

  Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

  Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Guia de migração para instrumentação manual

Nesta seção, descrevemos como modificar seu aplicativo para que ele envie os dados de trace ao projeto do Google Cloud usando a API Telemetry.

Adicionar dependências

A primeira etapa é adicionar dependências para o exportador de trace OTLP do OpenTelemetry no seu aplicativo. Selecione as versões de dependência adequadas para seu aplicativo e sistema de build.

Java

Observação : recomendamos que você use o módulo de configuração automática do SDK do OpenTelemetry para configurar o SDK. O aplicativo de exemplo usa esse módulo.

Para um aplicativo Java, no script build.gradle, adicione as seguintes dependências:

implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.62.0")
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.62.0")

Go

Nesta seção, mostramos as mudanças que você precisa fazer nas dependências ao usar o gRPC para exportação. Se você usar dados codificados em protobuf em conexões HTTP para exportação, inclua o pacote otlptracehttp como uma dependência. Para mais informações, consulte Aplicativo Go que usa HTTP.

Para um aplicativo Go que usa o gRPC para exportação, atualize o arquivo go.mod para incluir a seguinte dependência:

require (
	// ...
	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.44.0
)

Python

Nesta seção, mostramos as mudanças que você precisa fazer nas dependências ao usar o gRPC para exportação. Se você usar dados codificados em protobuf em conexões HTTP para exportação, inclua o pacote opentelemetry-exporter-otlp-proto-http como um requisito. Para mais informações, consulte o repositório do Python.

Para um aplicativo Python que usa o gRPC para exportação, instale as seguintes dependências ou atualize o arquivo requirements.txt:

opentelemetry-exporter-otlp-proto-grpc==1.42.1
grpcio==1.80.0

Node.js

Nesta seção, mostramos as mudanças que você precisa fazer nas dependências ao usar o gRPC para exportação. Se você usar dados codificados em protobuf em conexões HTTP para exportação, inclua o pacote @opentelemetry/exporter-trace-otlp-proto como uma dependência. Para mais informações, consulte Aplicativo Node.js.

Para um aplicativo Node.js que exporta dados de trace usando gRPC, adicione as seguintes dependências:

"@opentelemetry/exporter-trace-otlp-grpc": "0.221.0",
"@grpc/grpc-js": "1.14.4"

Substituir o uso de exportadores do Google Cloud por exportadores do OTLP

Atualize o código do aplicativo para que o SDK do OpenTelemetry seja configurado para usar os exportadores OTLP do OpenTelemetry em vez de um exportador de trace do Google Cloud . As mudanças necessárias são específicas do idioma.

Java

Para um aplicativo Java, faça o seguinte:

1. Adicione as seguintes instruções de importação:

   import io.opentelemetry.sdk.OpenTelemetrySdk;
   import io.opentelemetry.sdk.autoconfigure.AutoConfiguredOpenTelemetrySdk;

2. Atualize o código do aplicativo para usar o módulo de configuração automática do SDK do OpenTelemetry para configurar o SDK:

   public static void main(String[] args) {
     // Configure the OpenTelemetry pipeline with Auto configuration
     openTelemetrySdk = AutoConfiguredOpenTelemetrySdk.initialize().getOpenTelemetrySdk();
   
     // ...
   }

3. Configure as propriedades do sistema que o módulo de configuração automática consome no ambiente de execução. Esse módulo usa essas propriedades para inicializar o SDK. Também é possível usar variáveis de ambiente em vez de propriedades do sistema. Para mais informações, consulte Variáveis de ambiente e propriedades do sistema.

   O aplicativo de exemplo define as propriedades do sistema no script build.gradle:

   // You can switch the desired protocol here by changing `otel.exporter.otlp.protocol`.
   def autoconf_config = [
   	'-Dotel.exporter.otlp.endpoint=https://telemetry.googleapis.com',
   	'-Dotel.traces.exporter=otlp',
   	'-Dotel.logs.exporter=none',
   	'-Dotel.metrics.exporter=none',
   	'-Dotel.service.name=otlptrace-example',
   	'-Dotel.exporter.otlp.protocol=http/protobuf',
   	'-Dotel.java.global-autoconfigure.enabled=true',
   ]

   Além disso, transmita a configuração como argumentos da JVM:

   application {
   	mainClassName = 'com.google.cloud.opentelemetry.samples.otlptrace.OTLPTraceExample'
   	// Pass the config as JVM arguments to the Java application
   	applicationDefaultJvmArgs = autoconf_config
   }

   Se você preferir exportar dados de trace usando gRPC, defina o protocolo OTLP como grpc em vez de http/protobuf.

Go

Nesta seção, mostramos as mudanças que você precisa fazer ao usar o gRPC para exportação. Se você usar dados codificados em protobuf em conexões HTTP para exportação, será necessário importar o pacote otlptracehttp e também configurar o exportador com as opções correspondentes. Para mais informações, consulte Aplicativo Go que usa HTTP.

Para um aplicativo Go que usa gRPC para exportação, adicione as seguintes instruções de importação:

import (
	"context"
	"go.opentelemetry.io/otel"
	"go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
	sdktrace "go.opentelemetry.io/otel/sdk/trace"

	// ...
)

Além disso, atualize o código de inicialização para configurar o TraceProvider com o exportador do gRPC:

// Initializes OpenTelemetry with OTLP exporters
ctx := context.Background()

// Configure gRPC client with Google Application Default Credentials
creds, err := oauth.NewApplicationDefault(ctx)
if err != nil {
	panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
// Configure exporter to use the credentials
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
	panic(err)
}

tp := sdktrace.NewTracerProvider(
	// For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
	// In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
	sdktrace.WithSampler(sdktrace.AlwaysSample()),
	sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

Python

Nesta seção, mostramos as mudanças que você precisa fazer ao usar o gRPC para exportação. Se você usar dados codificados em protobuf em conexões HTTP para exportação, importe do pacote opentelemetry.exporter.otlp.proto.http e configure o exportador com as opções correspondentes. Para mais informações, consulte o repositório do Python.

Para um aplicativo Python que usa gRPC para exportação, adicione as seguintes importações:

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
    OTLPSpanExporter,
)

Além disso, atualize o código de inicialização para configurar o TraceProvider com o exportador do gRPC:

# Initialize OpenTelemetry with OTLP exporters
# channel_creds: configure Application Default Credentials
trace_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(
    OTLPSpanExporter(
        credentials=channel_creds,
        endpoint="https://telemetry.googleapis.com:443/v1/traces",
    )
)
trace_provider.add_span_processor(processor)
trace.set_tracer_provider(trace_provider)
tracer = trace.get_tracer("my.tracer.name")

Node.js

Nesta seção, mostramos as mudanças que você precisa fazer ao usar o gRPC para exportação. Se você usa dados codificados em protobuf em conexões HTTP para exportação, importe o pacote @opentelemetry/exporter-trace-otlp-proto. Para mais informações, consulte Aplicativo Node.js.

Para um aplicativo Node.js que usa o gRPC para exportação, adicione as seguintes importações:

import {OTLPTraceExporter} from '@opentelemetry/exporter-trace-otlp-grpc';

Além disso, atualize o código de inicialização para configurar o TraceProvider com o exportador do gRPC:

const sdk = new NodeSDK({
  traceExporter: new OTLPTraceExporter({
    credentials: credentials.combineChannelCredentials(
      credentials.createSsl(),
      credentials.createFromGoogleCredential({
        async getRequestHeaders(
          url?: string,
        ): Promise<{[index: string]: string}> {
          const rawHeaders = await authenticatedClient.getRequestHeaders(url);
          return Object.fromEntries(rawHeaders.entries());
        },
      }),
    ),
  }),
});
sdk.start();

Configurar a autenticação

Com as mudanças anteriores na configuração do SDK do OpenTelemetry, seu aplicativo está configurado para exportar traces com os exportadores OTLP do OpenTelemetry usando gRPC ou HTTP. Em seguida, configure os exportadores para enviar esses traces ao projeto do Google Cloud .

Para configurar a autenticação, faça o seguinte:

1. Configure os cabeçalhos de autenticação para as chamadas de exportação.
2. Configure os atributos de recurso do OpenTelemetry e os cabeçalhos OTLP necessários.
3. Configure o endpoint do exportador.

Esta seção detalha cada uma dessas etapas.

Configurar cabeçalhos de autenticação para as chamadas de exportação

Para configurar o exportador com suas Google Cloud Application Default Credentials (ADC), adicione uma biblioteca do Google Auth específica para a linguagem.

Java

Para um aplicativo Java que usa o módulo de configuração automática do SDK do OpenTelemetry, recomendamos que você também use a extensão de autenticação do Google Cloud.

implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.56.0-alpha")

Go

Para um aplicativo Go que usa o gRPC para exportação, atualize o arquivo go.mod para incluir a seguinte dependência:

// When using gRPC based OTLP exporter, the auth is built in.
google.golang.org/grpc v1.82.1

Para um aplicativo Go que usa HTTP para exportação, atualize o arquivo go.mod para incluir a seguinte dependência:

// When using http based OTLP exporter, use explicit auth library
golang.org/x/oauth2 v0.36.0

Python

Para um aplicativo Python, adicione as seguintes dependências ao arquivo requirements.txt:

# Google Auth Library
google-auth==2.53.0

Node.js

Para um aplicativo Node.js, adicione a seguinte dependência:

"google-auth-library": "10.5.0"

Em seguida, atualize o código do aplicativo que cria o exportador de períodos do OTLP para que ele adicione os tokens de autorização recuperados da biblioteca aos cabeçalhos. Essa etapa é específica para cada linguagem, mas a implementação é semelhante para todas as linguagens.

Java

Quando você tem um aplicativo Java que usa o módulo de configuração automática do SDK do OpenTelemetry e a extensão de autenticação do Google Cloud, não é necessário realizar nenhuma etapa especial durante a inicialização do aplicativo. O módulo de configuração automática executa automaticamente as etapas necessárias para configurar o ADC.

Go

Nesta seção, mostramos as mudanças que você precisa fazer ao usar o gRPC para exportação. Se você usar dados codificados em protobuf em conexões HTTP para exportação, importe o pacote otlptracehttp e configure o exportador para ser um objeto otlptracehttp. Para mais informações, consulte Aplicativo Go que usa HTTP.

Para um aplicativo Go que usa gRPC para exportação, adicione as seguintes instruções de importação:

"google.golang.org/grpc"
"google.golang.org/grpc/credentials/oauth"

Além disso, atualize o código de inicialização para configurar o ADC antes de instanciar o exportador do gRPC:

// Initializes OpenTelemetry with OTLP exporters
ctx := context.Background()

// Configure gRPC client with Google Application Default Credentials
creds, err := oauth.NewApplicationDefault(ctx)
if err != nil {
	panic(err)
}

// set OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=<project_id>"
// set endpoint with OTEL_EXPORTER_OTLP_ENDPOINT=https://<endpoint>
// set OTEL_EXPORTER_OTLP_HEADERS="x-goog-user-project=<project_id>"
// Configure exporter to use the credentials
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
	panic(err)
}

tp := sdktrace.NewTracerProvider(
	// For this example code we use sdktrace.AlwaysSample sampler to sample all traces.
	// In a production application, use sdktrace.TraceIDRatioBased with a desired probability.
	sdktrace.WithSampler(sdktrace.AlwaysSample()),
	sdktrace.WithBatcher(exporter))

otel.SetTracerProvider(tp)

Python

Nesta seção, mostramos as mudanças que você precisa fazer ao usar o gRPC para exportação. Se você usar dados codificados em protobuf em conexões HTTP para exportação, use as credenciais padrão. Você também precisa transmitir essas credenciais ao instanciar o BatchSpanProcessor. Para mais informações, consulte o repositório do Python.

Para um aplicativo Python que usa gRPC para exportação, adicione as seguintes importações:

import google.auth
import google.auth.transport.grpc
import google.auth.transport.requests
import grpc
from google.auth.transport.grpc import AuthMetadataPlugin

Além disso, atualize o código de inicialização para configurar o ADC antes de instanciar o exportador do gRPC:

credentials, _ = google.auth.default()
request = google.auth.transport.requests.Request()
resource = Resource.create(attributes={SERVICE_NAME: "otlp-gcp-grpc-sample"})

auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
channel_creds = grpc.composite_channel_credentials(
    grpc.ssl_channel_credentials(),
    grpc.metadata_call_credentials(auth_metadata_plugin),
)

Node.js

Nesta seção, ilustramos as mudanças que você precisa fazer ao usar o gRPC para exportação. Se você usa dados codificados em protobuf em conexões HTTP para exportação, as mudanças necessárias são um pouco diferentes das descritas aqui. Para saber mais, consulte o arquivo app-http-proto-export.ts incluído no aplicativo Node.js.

Para um aplicativo Node.js que usa o gRPC para exportação, adicione as seguintes importações:

import {AuthClient, GoogleAuth} from 'google-auth-library';
import {credentials} from '@grpc/grpc-js';

Além disso, atualize o código de inicialização para configurar o ADC antes de instanciar o exportador do gRPC:

async function getAuthenticatedClient(): Promise<AuthClient> {
  const auth: GoogleAuth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/cloud-platform',
  });
  return await auth.getClient();
}

// Express App that exports traces via gRPC with protobuf
async function main() {
  const authenticatedClient: AuthClient = await getAuthenticatedClient();

  // ...
}

Configurar os atributos de recurso obrigatórios do OpenTelemetry

Adicione à variável de ambiente OTEL_RESOURCE_ATTRIBUTES o par de chave-valor que especifica seu projeto. Para a chave, use gcp.project_id. Como valor, use o ID do projeto do Google Cloud .

Exemplo:

export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

Se você usa Java e configura o aplicativo para usar a extensão de autenticação do Google Cloud, como o aplicativo Java de amostra faz, não é necessário definir o ID do projeto como parte dos atributos de recurso do OpenTelemetry. No entanto, definir esse atributo não é prejudicial.

Para mais informações sobre as variáveis de ambiente do OpenTelemetry, consulte Configuração geral do SDK.

Definir o ID do projeto de cota

O projeto de cota é o projeto do Google Cloud que rastreia seu uso de solicitações de API. Como a API Telemetry é uma API baseada em cliente, a forma como você se autentica determina se o projeto de cota é identificado automaticamente. Por exemplo, não é necessário especificar o projeto de cota ao usar uma conta de serviço para autenticação. No entanto, é necessário especificar o projeto de cota quando as credenciais do usuário são usadas para autenticação.

É possível definir um projeto de cota usando uma variável de ambiente. Para determinar qual variável de ambiente definir para sua linguagem de programação, consulte Definir o projeto de cota usando uma variável de ambiente.

Por exemplo, para Go, é possível definir o projeto de cota da seguinte maneira:

export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

Para informações sobre como resolver erros de autenticação, consulte Credenciais do usuário que não funcionam.

Observação: não atualize a variável de ambiente OTEL_EXPORTER_OTLP_HEADERS com um par de chave-valor que use a chave x-goog-user-project. Essa configuração pode resultar em valores duplicados na solicitação, o que faz com que os comandos da API falhem.

Configurar o endpoint do exportador

Defina o valor da variável de ambiente OTEL_EXPORTER_OTLP_ENDPOINT como o endpoint OTLP para Google Cloud.

Exemplo:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://telemetry.googleapis.com

Se você usa Java e o módulo de configuração automática, é possível definir o endpoint do exportador usando propriedades do sistema, como faz o aplicativo Java de amostra. Não é necessário definir a variável de ambiente do exportador para essa configuração.

Para mais informações sobre as variáveis de ambiente do OpenTelemetry, consulte Configuração geral do SDK.