Node.js e OpenTelemetry

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

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

Para informações sobre o lançamento, consulte:

Para os detalhes mais recentes sobre o OpenTelemetry para Node.js, além de documentação e exemplos adicionais, consulte OpenTelemetry.

Antes de começar

Verifique se a API Cloud Trace está ativada para 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 Ativar for exibido, clique nele. Se esse botão não for exibido, isso significa que a API Cloud Trace está ativada para o projeto selecionado.

Como instalar, inicializar e usar o cliente

O OpenTelemetry oferece três maneiras de instrumentar seu aplicativo:

  • Instrumentação automática para aplicativos Node.js
  • Geração manual de trace
  • Instrumentação automática para aplicativos da Web

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

Instrumentação automática

O módulo @OpenTelemetry/nó fornece 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 geração de trace manual, @opentelemetry/tracing, fornece controle completo sobre a instrumentação e a criação de períodos. 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.

Instrumentação automática para aplicativos da Web

O módulo @opentelemetry/web fornece instrumentação e geração de trace automatizados para aplicativos da Web. Ele coleta dados de desempenho do usuário, incluindo latência e traces distribuídos, que fornecem informações para diagnosticar problemas de front-end e monitorar o status geral do aplicativo.

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/node
npm install --save @opentelemetry/tracing
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/node');
const {SimpleSpanProcessor} = require('@opentelemetry/tracing');
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 send spans to the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

GKE

Adicione o seguinte a Dockerfile:

RUN npm install --save @opentelemetry/api
RUN npm install --save @opentelemetry/node
RUN npm install --save @opentelemetry/tracing
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/node');
const {SimpleSpanProcessor} = require('@opentelemetry/tracing');
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 send spans to the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

Exemplo de aplicativo usando o framework Express

O OpenTelemetry Express Instrumentation permite coletar automaticamente os dados de trace e exportá-los para o back-end de sua escolha, oferecendo observabilidade aos 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/plugin-http
    npm install --save @opentelemetry/plugin-express
    
  2. Adicione o seguinte código ao seu aplicativo, que carrega todos os plug-ins compatíveis:

    const { NodeTracerProvider } = require('@opentelemetry/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
opentelemetry.trace.setGlobalTracerProvider(provider);
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 a 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 ver uma lista de ambientes compatíveis do Google Cloud, 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

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

  • Para usuários de 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.