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"

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

Você pode fornecer essas credenciais de uma destas 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"

Exemplo de aplicativo

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 visualizar os traces no visualizador de traces do console do Google 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.

Recursos