Como configurar o Cloud Trace para Node.js

É possível ativar o Cloud Trace para aplicativos Node.js usando a biblioteca do Cloud Trace para Node.js.

Instalar a biblioteca de cliente

  1. Antes de instalar a biblioteca do Cloud Trace para Node.js, verifique se você preparou o ambiente para desenvolvimento Node.js.

  2. Para instalar a biblioteca do Cloud Trace para Node.js, use npm:

    npm install --save @google-cloud/trace-agent
  3. Importe a biblioteca do Cloud Trace para Node.js na parte superior do script principal ou do ponto de entrada do aplicativo antes de qualquer outro código:

    require('@google-cloud/trace-agent').start();

Para mais informações ou para relatar problemas com a biblioteca do Cloud Trace para Node.js, consulte o repositório do GitHub cloud-trace-nodejs do agente.

Como configurar a biblioteca de cliente

É possível personalizar o comportamento da biblioteca do Cloud Trace para Node.js. Consulte a configuração da biblioteca no GitHub para ver uma lista de opções de configuração que você pode passar para o método start da biblioteca usando um objeto options.

O exemplo a seguir demonstra como especificar o ID do projeto do Google Cloud e configurar o caminho para o arquivo de credenciais. Estas duas instruções são opcionais quando você está executando no Google Cloud:

require('@google-cloud/trace-agent').start({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

Se você estiver executando na infraestrutura do Google Cloud, não será necessário definir projectId como o ID do projeto do Google Cloud. Se você não definir esse campo, a biblioteca de cliente do Node.js coletará automaticamente esses dados de um servidor de metadados do Google Cloud.

Se você não estiver executando na infraestrutura do Google Cloud, forneça o ID do projeto do Google Cloud ao aplicativo.

Independente da sua infraestrutura, para Node.js, quando você não configura explicitamente o ID do projeto do Google Cloud, a biblioteca cloud-trace-nodejs determina automaticamente se a variável de ambiente GCLOUD_PROJECT está configurada e, em caso afirmativo, a biblioteca usa o GCLOUD_PROJECT como o ID do projeto do Google Cloud. Para mais informações sobre o arquivo de descoberta, acesse cloud-trace-nodejs/src/index. Para definir a variável de ambiente, realize as seguintes ações:

Linux ou macOS

export GCLOUD_PROJECT=your-project-id

Windows

set GCLOUD_PROJECT=your-project-id

PowerShell:

$env:GCLOUD_PROJECT="your-project-id"

Como 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 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 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. 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"

Exemplo de app

if (process.env.NODE_ENV === 'production') {
  require('@google-cloud/trace-agent').start();
}

const express = require('express');
const got = require('got');

const app = express();
const DISCOVERY_URL = 'https://www.googleapis.com/discovery/v1/apis';

// This incoming HTTP request should be captured by Trace
app.get('/', async (req, res) => {
  // This outgoing HTTP request should be captured by Trace
  try {
    const {body} = await got(DISCOVERY_URL, {responseType: 'json'});
    const names = body.items.map(item => item.name);
    res.status(200).send(names.join('\n')).end();
  } catch (err) {
    console.error(err);
    res.status(500).end();
  }
});

// Start the server
const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});

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

Resolver problemas

Para informações sobre como solucionar problemas com o Cloud Trace, acesse a página de solução de problemas.

Recursos