Exemplo de instrumentação de Node.js

Este documento descreve como modificar uma app JavaScript Node.js para recolher dados de rastreio e métricas através da framework OpenTelemetry de código aberto e como escrever registos JSON estruturados para saída padrão. Este documento também fornece informações sobre uma app Node.js de exemplo que pode instalar e executar. A app usa a estrutura Web Fastify e está configurada para gerar métricas, rastreios e registos.

Para saber mais sobre a instrumentação, consulte os seguintes documentos:

Acerca da instrumentação manual e sem código

Para este idioma, o OpenTelemetry define a instrumentação sem código como a prática de recolher telemetria de bibliotecas e frameworks sem fazer alterações ao código. No entanto, pode instalar módulos e definir variáveis de ambiente.

Este documento não descreve a instrumentação sem código. Para obter informações sobre esse tópico, consulte o artigo Instrumentação de código zero em JavaScript.

Para informações gerais, consulte o artigo Instrumentação do OpenTelemetry para o Node.

Antes de começar

  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. Install the Google Cloud CLI.

  3. Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro, tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  4. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  5. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

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

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

    gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

  8. Install the Google Cloud CLI.

  9. Se estiver a usar um fornecedor de identidade (IdP) externo, primeiro, tem de iniciar sessão na CLI gcloud com a sua identidade federada.

  10. Para inicializar a CLI gcloud, execute o seguinte comando: 

    gcloud init

  11. Create or select a Google Cloud project.

    • Create a Google Cloud project:

      gcloud projects create PROJECT_ID

      Replace PROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set project PROJECT_ID

      Replace PROJECT_ID with your Google Cloud project name.

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

  13. Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs: 

    gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com

    14. Instrumente a sua app para recolher rastreios, métricas e registos

    Para instrumentar a sua app de modo a recolher dados de rastreio e métricas, e para escrever JSON estruturado para a saída padrão, siga os passos descritos nas secções subsequentes deste documento:

    1. Configure o OpenTelemetry
    2. Configure a sua app para pré-carregar a configuração do OpenTelemetry
    3. Configure o registo estruturado
    4. Escreva registos estruturados

    Configure o OpenTelemetry

    A configuração predefinida do SDK Node.js do OpenTelemetry exporta rastreios através do protocolo OTLP. Também configura o OpenTelemetry para usar o formato W3C Trace Context para propagar o contexto de rastreio. Esta configuração garante que os intervalos têm a relação principal-secundário correta numa rastreabilidade.

    O seguinte exemplo de código ilustra um módulo JavaScript para configurar o OpenTelemetry.

    Para ver o exemplo completo, clique em Mais e, de seguida, selecione Ver no GitHub.

    
diag.setLogger(
  new DiagConsoleLogger(),
  opentelemetry.core.getEnv().OTEL_LOG_LEVEL
);

const sdk = new opentelemetry.NodeSDK({
  instrumentations: getNodeAutoInstrumentations({
    // Disable noisy instrumentations
    '@opentelemetry/instrumentation-fs': {enabled: false},
  }),
  resourceDetectors: getResourceDetectorsFromEnv(),
  metricReader: getMetricReader(),
});

try {
  sdk.start();
  diag.info('OpenTelemetry automatic instrumentation started successfully');
} catch (error) {
  diag.error(
    'Error initializing OpenTelemetry SDK. Your application is not instrumented and will not produce telemetry',
    error
  );
}

// Gracefully shut down the SDK to flush telemetry when the program exits
process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(() => diag.debug('OpenTelemetry SDK terminated'))
    .catch(error => diag.error('Error terminating OpenTelemetry SDK', error));
});

    O exemplo de código anterior configura o OpenTelemetry para exportar métricas através do protocolo OTLP e usa o pacote @opentelemetry/auto-instrumentations-node para configurar todas as instrumentações do Node.js disponíveis.

    Para garantir que toda a telemetria pendente é descarregada e que as ligações são fechadas de forma adequada antes de a aplicação ser encerrada, o controlador SIGTERM chama shutdown.

    Para mais informações e opções de configuração, consulte o artigo Configuração da instrumentação sem código.

    Configure a sua app para pré-carregar a configuração do OpenTelemetry

    Para configurar a app para escrever registos estruturados e recolher métricas e dados de rastreio através do OpenTelemetry, atualize a invocação da app para pré-carregar o módulo de instrumentação com a flag --require do Node.js. A utilização da flag --require garante que o OpenTelemetry é inicializado antes de a sua app ser iniciada. Para mais informações, consulte o artigo Introdução ao OpenTelemetry Node.js.

    O seguinte exemplo de código ilustra um Dockerfile que passa a flag --require:

    CMD node --require ./build/src/instrumentation.js build/src/index.js 2>&1 | tee /var/log/app.log

    Configure o registo estruturado

    Para incluir as informações de rastreio como parte dos registos formatados em JSON escritos para a saída padrão, configure a sua app para gerar registos estruturados no formato JSON. O Fastify usa a estrutura de registo do Pino e fornece um registador em cada controlador de pedidos. O seguinte exemplo de código ilustra um objeto Pino LoggerOptions que configura a app para gerar registos estruturados JSON:

    
// Expected attributes that OpenTelemetry adds to correlate logs with spans
interface LogRecord {
  trace_id?: string;
  span_id?: string;
  trace_flags?: string;
  [key: string]: unknown;
}

// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
const PinoLevelToSeverityLookup: Record<string, string | undefined> = {
  trace: 'DEBUG',
  debug: 'DEBUG',
  info: 'INFO',
  warn: 'WARNING',
  error: 'ERROR',
  fatal: 'CRITICAL',
};

export const loggerConfig = {
  messageKey: 'message',
  // Same as pino.stdTimeFunctions.isoTime but uses "timestamp" key instead of "time"
  timestamp(): string {
    return `,"timestamp":"${new Date(Date.now()).toISOString()}"`;
  },
  formatters: {
    log(object: LogRecord): Record<string, unknown> {
      // Add trace context attributes following Cloud Logging structured log format described
      // in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
      const {trace_id, span_id, trace_flags, ...rest} = object;

      return {
        'logging.googleapis.com/trace': trace_id,
        'logging.googleapis.com/spanId': span_id,
        'logging.googleapis.com/trace_sampled': trace_flags
          ? trace_flags === '01'
          : undefined,
        ...rest,
      };
    },
    // See
    // https://getpino.io/#/docs/help?id=mapping-pino-log-levels-to-google-cloud-logging-stackdriver-severity-levels
    level(label: string) {
      return {
        severity:
          PinoLevelToSeverityLookup[label] ?? PinoLevelToSeverityLookup['info'],
      };
    },
  },
} satisfies LoggerOptions;

    A configuração anterior extrai informações sobre o intervalo ativo da mensagem de registo e, em seguida, adiciona essas informações como atributos ao registo estruturado JSON. Estes atributos podem ser usados para correlacionar um registo com um rastreio:

    • logging.googleapis.com/trace: nome do recurso do rastreio associado à entrada do registo.
    • logging.googleapis.com/spanId: o ID do intervalo com o rastreio associado à entrada do registo.
    • logging.googleapis.com/trace_sampled: o valor deste campo tem de ser true ou false.

    Para mais informações sobre estes campos, consulte a LogEntry estrutura.

    Para usar a configuração do Pino com o Fastify, passe o objeto de configuração do registador quando criar a app Fastify:

    // Create the Fastify app providing the Pino logger config
const fastify = Fastify({
  logger: loggerConfig,
});

    Escreva registos estruturados

    Para escrever registos estruturados que remetem para um rastreio, use o Pino logger fornecido pelo Fastify. Por exemplo, a seguinte declaração mostra como chamar o método Logger.info():

    request.log.info({subRequests}, 'handle /multi request');

    O OpenTelemetry preenche automaticamente as entradas de registo do Pino com o contexto do intervalo do intervalo ativo atual no contexto do OpenTelemetry. Este contexto de intervalo é, em seguida, incluído nos registos JSON, conforme descrito em Configurar o registo estruturado.

    Execute uma app de exemplo configurada para recolher telemetria

    A app de exemplo usa formatos independentes do fornecedor, incluindo JSON para registos e OTLP para métricas e rastreios, e a estrutura Fastify. Para encaminhar a telemetria para Google Cloud, este exemplo usa o OpenTelemetry Collector configurado com exportadores da Google. A app tem dois pontos finais:

    • O ponto final /multi é processado pela função handleMulti. O gerador de carga na app envia pedidos para o ponto final /multi. Quando este ponto final recebe um pedido, envia entre três e sete pedidos para o ponto final /single no servidor local.

      /**
 * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
 *
 * OpenTelemetry instrumentation requires no changes here. It will automatically generate a
 * span for the handler body.
 */
fastify.get('/multi', async request => {
  const subRequests = randInt(3, 8);
  request.log.info({subRequests}, 'handle /multi request');

  for (let i = 0; i < subRequests; i++) {
    await axios.get(`http://localhost:${port}/single`);
  }
  return 'ok';
});

    • O ponto final /single é processado pela função handleSingle. Quando este ponto final recebe um pedido, fica inativo durante um breve período e, em seguida, responde com uma string.

      /**
 * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
 * milliseconds slept as its response.
 */
fastify.get('/single', async request => {
  // Sleep between 100-200 milliseconds
  const sleepMillis = randInt(100, 200);
  request.log.info({sleepMillis}, 'Going to sleep');
  await sleep(sleepMillis);
  return `slept ${sleepMillis}\n`;
});

    Transfira e implemente a app

    Para executar o exemplo, faça o seguinte:

    1. In the Google Cloud console, activate Cloud Shell.

      Activate Cloud Shell

      At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    2. Clone o repositório:

      git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-js

    3. Aceda ao diretório de exemplo:

      cd opentelemetry-operations-js/samples/instrumentation-quickstart

    4. Crie e execute o exemplo:

      docker compose up --abort-on-container-exit

      Se não estiver a usar o Cloud Shell, execute a aplicação com a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS a apontar para um ficheiro de credenciais. As Credenciais padrão da aplicação fornecem um ficheiro de credenciais em $HOME/.config/gcloud/application_default_credentials.json.

      # Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"

# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit

      5. Veja as suas métricas

      A instrumentação do OpenTelemetry na app de exemplo gera métricas do Prometheus que pode ver através do Explorador de métricas:

      • Prometheus/http_server_duration_milliseconds/histogram registam a duração dos pedidos do servidor e armazenam os resultados num histograma.

      • Prometheus/http_client_duration_milliseconds/histogram regista a duração dos pedidos do cliente e armazena os resultados num histograma.

      Para ver as métricas geradas pela app de amostra, faça o seguinte:

      1. Na Google Cloud consola, aceda à página  Explorador de métricas:

        Aceda ao Metrics Explorer

        Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cujo subtítulo é Monitorização.

      2. Na barra de ferramentas da Google Cloud consola, selecione o seu Google Cloud projeto. Para configurações do App Hub, selecione o projeto anfitrião do App Hub ou o projeto de gestão da pasta com apps ativadas.
      3. No elemento Métrica, expanda o menu Selecionar uma métrica, introduza http_server na barra de filtro e, de seguida, use os submenus para selecionar um tipo de recurso e uma métrica específicos:
        1. No menu Recursos ativos, selecione Alvo do Prometheus.
        2. No menu Categorias de métricas ativas, selecione Http.
        3. No menu Métricas ativas, selecione uma métrica.
        4. Clique em Aplicar.
      4. Configure a forma como os dados são vistos.

        Quando as medições de uma métrica são cumulativas, o explorador de métricas normaliza automaticamente os dados medidos pelo período de alinhamento, o que resulta na apresentação de uma taxa no gráfico. Para mais informações, consulte o artigo Tipos, tipos e conversões.

        Quando são medidos valores inteiros ou duplos, como com as duas métricas counter, o explorador de métricas soma automaticamente todas as séries cronológicas. Para ver os dados das rotas HTTP /multi e /single, defina o primeiro menu da entrada Agregação como Nenhuma.

        Para mais informações sobre como configurar um gráfico, consulte o artigo Selecione métricas quando usar o explorador de métricas.

      Veja os seus rastreios

      Pode demorar vários minutos até que os dados de rastreio estejam disponíveis. Por exemplo, quando o seu projeto recebe dados de rastreio, o Google Cloud Observability pode ter de criar uma base de dados para armazenar esses dados. A criação da base de dados pode demorar alguns minutos e, durante esse período, não estão disponíveis dados de rastreio para visualização.

      Para ver os dados de rastreio, faça o seguinte:

      1. Na Google Cloud consola, aceda à página Explorador de rastreios:

        Aceda ao Explorador de rastreios

        Também pode encontrar esta página através da barra de pesquisa.

      2. Na secção de tabelas da página, selecione uma linha com o nome do intervalo /multi.

      3. No gráfico de Gantt no painel Detalhes do rastreio, selecione o intervalo etiquetado como /multi.

        É aberto um painel que apresenta informações sobre o pedido HTTP. Estes detalhes incluem o método, o código de estado, o número de bytes e o agente do utilizador do autor da chamada.

      4. Para ver os registos associados a este rastreio, selecione o separador Registos e eventos.

        O separador mostra registos individuais. Para ver os detalhes da entrada do registo, expanda a entrada do registo. Também pode clicar em Ver registos e ver o registo através do Explorador de registos.

      Para mais informações sobre como usar o explorador do Cloud Trace, consulte o artigo Encontre e explore rastreios.

      Veja os seus registos

      No Explorador de registos, pode inspecionar os seus registos e também ver rastreios associados, quando existirem.

      1. Na Google Cloud consola, aceda à página Explorador de registos:

        Aceda ao Explorador de registos

        Se usar a barra de pesquisa para encontrar esta página, selecione o resultado cuja legenda é Registo.

      2. Localize um registo com a descrição de handle /multi request.

        Para ver os detalhes do registo, expanda a entrada do registo.

      3. Clique em Rastreios numa entrada de registo com a mensagem "handle /multi request" e, de seguida, selecione Ver detalhes do rastreio.

        É aberto um painel Detalhes do rastreio que apresenta o rastreio selecionado.

        Os dados de registo podem estar disponíveis vários minutos antes dos dados de rastreio. Se encontrar um erro ao ver os dados de rastreio pesquisando um rastreio por ID ou seguindo os passos desta tarefa, aguarde um ou dois minutos e tente novamente a ação.

      Para mais informações sobre a utilização do Explorador de registos, consulte o artigo Veja registos através do Explorador de registos.

      O que se segue?