Migre do exportador de rastreios para o ponto final OTLP

Este documento descreve como configurar a exportação no processo de dados de rastreio pelo SDK OpenTelemetry para o seu projeto do Google Cloud. Google Cloud Os exemplos para Java, Go, Python e Node.js mostram como configurar o SDK para enviar dados de rastreio para a API de telemetria (OTLP) quando usa a instrumentação manual. Para cada idioma, a página fornece informações sobre a utilização de exportadores OTLP para enviar dados de rastreio através dos protocolos de exportação suportados.

A instrumentação descrita nesta página aplica-se apenas aos dados de rastreio. Não envia dados de registo nem de métricas para o seu Google Cloud projeto.

Se a sua aplicação depender de um coletor do OpenTelemetry para enviar dados de rastreio para o seu Google Cloud projeto, este documento não se aplica:

Por que motivo deve migrar

Os SDKs OpenTelemetry geram dados de registo, métricas e rastreios num formato geralmente consistente com os ficheiros proto definidos pelo protocolo OTLP 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 uma aplicação exporta esses dados para um Google Cloud projeto através de um Google Cloud exportador, esse exportador executa os seguintes passos:

  1. Transforma os dados registados do formato OTLP num formato proprietário definido pela API Cloud Logging, pela API Cloud Monitoring ou pela API Cloud Trace.
  2. Envia os dados transformados para a API adequada, que são depois armazenados no seu Google Cloud projeto.

Para dados de rastreio, recomendamos que migre a sua aplicação para usar a API Telemetry (OTLP) para exportar dados, porque esta 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 proprietário pode ter limites inferiores para determinados campos ou alguns campos OTLP podem não ser mapeados para um campo no formato proprietário.

Amostras disponíveis

As aplicações de exemplo referenciadas nesta página estão disponíveis no GitHub. A maioria das aplicações está configurada para exportar dados de rastreio através do gRPC, o que significa que usam dados codificados em protobuf com o formato de transmissão do gRPC através de ligações HTTP/2. Também são fornecidos exemplos de código para aplicações configuradas para exportar dados de rastreio como dados codificados em protobuf através de ligações HTTP:

  • Aplicação Java

    A aplicação de amostra está configurada para exportar rastreios como dados codificados em protobuf através de ligações HTTP. Se preferir usar o gRPC, a instrumentação neste exemplo é aplicável. No entanto, tem de modificar as propriedades do sistema que o módulo de configuração automática consome. A aplicação de exemplo especifica o exportador http/protobuf. Para usar o gRPC, altere esta definição para grpc.

    Recomendamos que as suas aplicações Java, como a aplicação de exemplo, usem o módulo de configuração automática do SDK OpenTelemetry para configurar o SDK.

  • Aplicação Go que usa gRPC e aplicação Go que usa HTTP

    Existem dois repositórios Go. Num repositório, a aplicação de exemplo usa o gRPC. O exemplo no outro repositório usa dados codificados em protobuf através de ligações HTTP.

  • Aplicação Python

    Este repositório contém dois exemplos, um para gRPC e outro que usa dados codificados em protobuf através de ligações HTTP.

  • Aplicação Node.js

    Este repositório contém dois exemplos, um para gRPC e outro que usa dados codificados em protobuf através de ligações HTTP.

Antes de começar

Antes de migrar a sua aplicação para enviar dados de rastreio para o ponto final OTLP, ative a API Telemetry e certifique-se de que lhe foram concedidas as funções de gestão de identidade e de acesso (IAM) necessárias. Também pode ter de conceder funções do IAM a uma conta de serviço.

Ative a faturação e a API Telemetry

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

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

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the APIs

    8.

    Configure autorizações

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

    Esta secção descreve como modificar a sua aplicação para que envie os dados de rastreio para o seu projeto do Google Cloud através da API Telemetry. Não pode enviar dados de métricas nem de registos para este ponto final.

    Adicione dependências

    O primeiro passo é adicionar dependências para o exportador de rastreio OTLP do OpenTelemetry na sua aplicação. Selecione as versões das dependências adequadas para a sua aplicação e sistema de compilação.

    Java

    Para uma aplicação Java, no script build.gradle, adicione as seguintes dependências:

    // use the latest versions
implementation("io.opentelemetry:opentelemetry-exporter-otlp:1.56.0")
implementation("io.opentelemetry:opentelemetry-sdk-extension-autoconfigure:1.56.0")

    Go

    Esta secção ilustra as alterações que tem de fazer às suas dependências quando usa o gRPC para exportação. Se usar dados codificados em protobuf através de ligações HTTP para exportação, inclua o pacote otlptracehttp como uma dependência. Para mais informações, consulte o artigo Aplicação Go que usa HTTP.

    Para uma aplicação Go que usa gRPC para exportação, atualize o ficheiro go.mod para incluir a seguinte dependência:

    // go.mod file
require(
  // OTLP exporter that uses grpc protocol for export
  go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.38.0
)

    Python

    Esta secção ilustra as alterações que tem de fazer às suas dependências quando usa o gRPC para exportação. Se usar dados codificados em protobuf através de ligações HTTP para exportação, inclua o pacote opentelemetry-exporter-otlp-proto-http como um requisito. Para mais informações, consulte o artigo Aplicação Python.

    Para uma aplicação Python que usa o gRPC para exportação, instale as seguintes dependências ou atualize o ficheiro requirements.txt:

    # Requirements.txt - use appropriate versions
#
# OTLP exporter that uses grcp protocol for export
opentelemetry-exporter-otlp-proto-grpc==1.39.0
grpcio==1.76.0

    Node.js

    Esta secção ilustra as alterações que tem de fazer às suas dependências quando usa o gRPC para exportação. Se usar dados codificados em protobuf através de ligações HTTP para exportação, inclua o pacote @opentelemetry/exporter-trace-otlp-proto como uma dependência. Para mais informações, consulte o artigo Aplicação Node.js.

    Para uma aplicação Node.js que exporte usando gRPC, adicione as seguintes dependências.

    "@opentelemetry/exporter-trace-otlp-grpc": "0.203.0",
"@grpc/grpc-js": "1.13.4",

    Substitua a utilização de Google Cloud exportadores por exportadores OTLP

    Atualize o código da aplicação de forma que o SDK OpenTelemetry esteja configurado para usar os exportadores OTLP OpenTelemetry em vez do Google Cloud exportador de rastreio. As alterações necessárias dependem do idioma.

    Java

    Para uma aplicação Java, faça o seguinte:

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

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

    2. Atualize o código da aplicação para usar o módulo de configuração automática do SDK 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 em tempo de execução. Esse módulo usa essas propriedades para iniciar o SDK. Também pode usar variáveis de ambiente em vez de propriedades do sistema. Para mais informações, consulte o artigo Variáveis de ambiente e propriedades do sistema.

      A aplicação de exemplo define as propriedades do sistema no build.gradle script:

      // 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=my-service',
  '-Dotel.exporter.otlp.protocol=http/protobuf',
  '-Dotel.java.global-autoconfigure.enabled=true',
  // ID of your Google Cloud Project, required by the auth extension
  '-Dgoogle.cloud.project=PROJECT_ID',
]

// Now pass the config as JVM arguments to your java application:
application {
        // Replace with the fully qualified name of your Main class.
  mainClassName = 'com.example.Main'
  applicationDefaultJvmArgs = autoconf_config
}

      Se preferir exportar dados de rastreio através do gRPC, defina o protocolo OTLP como grpc em vez de o definir como http/protobuf.

    Go

    Esta secção ilustra as alterações que tem de fazer quando usa o gRPC para a exportação. Se usar dados codificados em protobuf através de ligações HTTP para exportação, tem de importar o pacote otlptracehttp e também configurar o exportador com as opções correspondentes. Para mais informações, consulte o artigo Aplicação Go que usa HTTP.

    Para uma aplicação Go que usa gRPC para exportação, adicione as seguintes declaraçõ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"
    // other dependencies
)

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

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

// creds: configure Application Default Credentials

// Initialize the OTLP gRPC exporter
exporter, err := otlptracegrpc.New(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>"
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

    Esta secção ilustra as alterações que tem de fazer quando usa o gRPC para a exportação. Se usar dados codificados em protobuf através de ligações HTTP para exportação, tem de importar a partir do pacote opentelemetry.exporter.otlp.proto.http e também configurar o exportador com as opções correspondentes. Para mais informações, consulte o artigo Aplicação Python.

    Para uma aplicação 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,
)
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

    Além disso, atualize o código de inicialização para configurar o TraceProvider com o exportador 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

    Esta secção ilustra as alterações que tem de fazer quando usa o gRPC para a exportação. Se usar dados codificados em protobuf através de ligações HTTP para exportação, importe o pacote @opentelemetry/exporter-trace-otlp-proto. Para mais informações, consulte o artigo Aplicação Node.js.

    Para uma aplicação Node.js que usa 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 gRPC:

    
// Express App that exports traces via gRPC with protobuf
async function main() {
  // authenticatedClient: configure Application Default Credentials

  // Configure the TraceExporter
  const sdk = new NodeSDK({
    traceExporter: new OTLPTraceExporter({
      credentials: credentials.combineChannelCredentials(
        credentials.createSsl(),
        credentials.createFromGoogleCredential(authenticatedClient),
      ),
    }),
  });
  sdk.start();
}

    Configure a autenticação

    Com as alterações anteriores à configuração do SDK OpenTelemetry, a sua aplicação está configurada para exportar rastreios através dos exportadores OTLP OpenTelemetry usando gRPC ou HTTP. Em seguida, tem de configurar os exportadores para enviar esses rastreios para o seu Google Cloud projeto.

    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 recursos do OpenTelemetry e os cabeçalhos OTLP necessários.
    3. Configure o ponto final do exportador.

    Esta secção detalha cada um destes passos.

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

    Para configurar o exportador com as suas Google Cloud Credenciais padrão da aplicação (ADC), adicione uma biblioteca Google Auth específica do idioma.

    Java

    Para se autenticar no Google Cloud Observability, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

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

    // build.gradle
implementation("io.opentelemetry.contrib:opentelemetry-gcp-auth-extension:1.52.0-alpha")

    Go

    Para se autenticar no Google Cloud Observability, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

    Para uma aplicação Go que usa gRPC para exportação, atualize o ficheiro go.mod para incluir a seguinte dependência:

    // go.mod file
require (
    // When using gRPC based OTLP exporter, auth is built-in
    google.golang.org/grpc v1.75.1
)

    Para uma aplicação Go que usa HTTP para exportação, atualize o ficheiro go.mod para incluir a seguinte dependência:

    // go.mod file
require (
    // When using http based OTLP exported, use explicit auth library
  golang.org/x/oauth2 v0.31.0
)

    Python

    Para se autenticar no Google Cloud Observability, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

    Para uma aplicação Python, adicione as seguintes importações:

    # requirements.txt
# Google Auth Library
google-auth==2.38.0

    Node.js

    Para se autenticar no Google Cloud Observability, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local.

    Para uma aplicação Node.js, adicione as seguintes dependências:

    "google-auth-library": "9.15.1",

    Em seguida, atualize o código da aplicação que cria o exportador de intervalos OTLP para que adicione os tokens de autorização obtidos da biblioteca aos cabeçalhos. Este passo é específico do idioma, mas a implementação é semelhante para todos os idiomas.

    Java

    Quando tem uma aplicação Java que usa o módulo de configuração automática do SDK OpenTelemetry e a extensão de autenticação do Google Cloud, não precisa de realizar passos especiais durante a inicialização da aplicação. O módulo de configuração automática executa automaticamente os passos necessários para configurar o ADC.

    Go

    Esta secção ilustra as alterações que tem de fazer quando usa o gRPC para a exportação. Se usar dados codificados em protobuf através de ligações HTTP para exportação, tem de importar o pacote otlptracehttp e configurar o exportador para ser um objeto otlptracehttp. Para mais informações, consulte o artigo Aplicação Go que usa HTTP.

    Para uma aplicação Go que usa gRPC para exportação, adicione as seguintes declaraçõ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"
    // other dependencies
    "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 gRPC:

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

// Retrieve and store 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>"
exporter, err := otlptracegrpc.New(ctx, otlptracegrpc.WithDialOption(grpc.WithPerRPCCredentials(creds)))
if err != nil {
  panic(err)
}

// Other OpenTelemetry configuration remains unaffected.

    Python

    Esta secção ilustra as alterações que tem de fazer quando usa o gRPC para a exportação. Se usar dados codificados em protobuf através de ligações HTTP para exportação, use as credenciais predefinidas. Também tem de transmitir estas credenciais quando instanciar o BatchSpanProcessor. Para mais informações, consulte o artigo Aplicação Python.

    Para uma aplicação 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,
)
from opentelemetry.sdk.resources import SERVICE_NAME, Resource

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 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),
)

# Configure the TraceProvider

    Node.js

    Esta secção ilustra as alterações que tem de fazer quando usa o gRPC para a exportação. Se usar dados codificados em protobuf através de ligações HTTP para exportação, as alterações que tem de fazer são ligeiramente diferentes das descritas aqui. Para saber mais, consulte o ficheiro app-http-proto-export.ts incluído na aplicação Node.js.

    Para uma aplicação Node.js que usa 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 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();

  // Configure the TraceExporter
}

    Configure os atributos de recursos do OpenTelemetry necessários

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

    Exemplo:

    export OTEL_RESOURCE_ATTRIBUTES="gcp.project_id=PROJECT_ID"

    Se usar Java e configurar a sua aplicação para usar a extensão de autenticação do Google Cloud, como faz a aplicação Java de exemplo, não precisa de definir o ID do projeto como parte dos atributos de recursos do OpenTelemetry. No entanto, a definição deste atributo não é prejudicial.

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

    Defina o ID do projeto de quota

    O projeto de quota é o Google Cloud projeto que monitoriza a sua utilização de pedidos API. Uma vez que a API Telemetry é uma API baseada no cliente, a forma como se autentica determina se o projeto de quota é identificado automaticamente. Por exemplo, não precisa de especificar o projeto de quota quando usa uma conta de serviço para autenticação. No entanto, tem de especificar o projeto de quota quando as credenciais do utilizador são usadas para autenticação.

    Pode definir um projeto de quota através de uma variável de ambiente. Para determinar que variável de ambiente definir para a sua linguagem de programação, consulte Defina o projeto de quota através de uma variável de ambiente.

    Por exemplo, para o Go, pode definir o projeto de quota da seguinte forma:

    export GOOGLE_CLOUD_QUOTA_PROJECT="QUOTA_PROJECT_ID"

    Para obter informações sobre como resolver erros de autenticação, consulte o artigo As credenciais do utilizador não estão a funcionar.

    Configure o ponto final do exportador

    Defina o valor da variável de ambiente OTEL_EXPORTER_OTLP_ENDPOINT para o ponto final OTLP para Google Cloud.

    Exemplo:

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

    Se usar Java e o módulo de configuração automática, pode definir o ponto final do exportador usando propriedades do sistema, tal como a aplicação Java de exemplo. Não precisa de 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 a secção Configuração geral do SDK.