Node.js e OpenTelemetry

Esta página é voltada a desenvolvedores de aplicativos que querem coletar dados do Cloud Trace para aplicativos Node.js 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 Node.js, além de documentação e mais exemplos, 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

O OpenTelemetry oferece as seguintes maneiras de instrumentar seu aplicativo:

  • Instrumentação automática para aplicativos Node.js

    Ao usar essa abordagem, você configura seu aplicativo para incluir o SDK @opentelemetry/sdk-trace-node. No entanto, não é necessário fazer mudanças de código em nenhuma das bibliotecas que estiver usando.

  • Geração manual de trace

    Ao usar essa abordagem, você modifica as bibliotecas que está usando para coletar informações de rastreamento.

As seções a seguir mostram o caso de uso de cada instrumentação.

Instrumentação automática

O módulo @opentelemetry/sdk-trace-node fornece a instrumentação automática para aplicativos Node.js.

A instrumentação automática identifica automaticamente no seu aplicativo:

  • estruturas, como Express;
  • protocolos comuns, como HTTP, HTTPS e gRPC;
  • bancos de dados, como MySQL, MongoDB, Redis e PostgreSQL;
  • outras bibliotecas no seu aplicativo.

A instrumentação automática fornece geração de trace pronto para que você não precise fazer alterações de código em nenhuma das bibliotecas que estiver usando. O código de instrumentação executa automaticamente as seguintes ações:

  • Extrai um identificador de contexto de trace das solicitações de entrada para permitir a geração distribuída de traces, se aplicável.
  • Garante que o contexto de trace atual seja propagado enquanto a transação passa por um aplicativo.
  • Adiciona o identificador de contexto de trace a solicitações de saída, permitindo que o trace distribuído continue para o próximo salto, se aplicável.
  • Cria e encerra períodos.

O módulo usa plug-ins para instrumentar automaticamente o aplicativo para produzir períodos e fornecer geração completa de trace com apenas algumas linhas de código.

Instrumentação manual

O módulo de rastreamento manual, @opentelemetry/sdk-trace-base, oferece controle total sobre a criação de períodos e a instrumentação. Ele não carrega async_hooks. Ele não usa armazenamento local de continuação ou qualquer plug-in de instrumentação por padrão. A geração de trace manual tem menos implicações de sobrecarga de desempenho em comparação com o módulo de instrumentação automática.

Exemplo

As instruções a seguir mostram como usar o módulo de instrumentação automática para o Compute Engine e o Google Kubernetes Engine.

Compute Engine

Instale os seguintes pacotes:

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-node
npm install --save @opentelemetry/sdk-trace-base
npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Adicione o seguinte código ao seu aplicativo para inicializar e registrar o exportador:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

GKE;

Adicione o seguinte a Dockerfile:

RUN npm install --save @opentelemetry/api
RUN npm install --save @opentelemetry/sdk-trace-node
RUN npm install --save @opentelemetry/sdk-trace-base
RUN npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Adicione o seguinte código ao seu aplicativo para inicializar e registrar o exportador:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { BatchSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to batch and send spans to the exporter
provider.addSpanProcessor(new BatchSpanProcessor(exporter));

Exemplo de aplicativo usando o framework Express

Com a instrumentação do Express do OpenTelemetry, é possível coletar dados de trace automaticamente e exportá-los para o back-end de sua preferência, oferecendo observabilidade a sistemas distribuídos.

Para usar o OpenTelemetry em aplicativos que usam o framework Express, siga estas etapas:

  1. Instale os seguintes pacotes:

    npm install --save @opentelemetry/instrumentation-http
npm install --save @opentelemetry/instrumentation-express

  2. Adicione o seguinte código ao seu aplicativo, que carrega todos os plug-ins compatíveis:

    const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const provider = new NodeTracerProvider();

Para ver um exemplo básico, consulte o exemplo do Express do OpenTelemetry.

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:


// Initialize the OpenTelemetry APIs to use the
// NodeTracerProvider bindings
provider.register();
const tracer = opentelemetry.trace.getTracer("basic");

// Create a span.
const span = tracer.startSpan("foo");

// Set attributes to the span.
span.setAttribute("key", "value");

// Annotate our span to capture metadata about our operation
span.addEvent("invoking work");

// simulate some random work.
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {}

// Be sure to end the span.
span.end();

  • getTracer retorna uma instância de trace, em que basic é o nome do trace ou da biblioteca de instrumentação. Isso informa ao OpenTelemetry quem está criando períodos.

  • foo é o nome do período personalizado.

  • invoking work é o nome do evento de amostra. Isso mostra como usar a API addEvent.

Para ver um exemplo básico de como criar um período personalizado, consulte o exemplo OpenTelemetry.

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.