Como configurar o Cloud Trace para Ruby

É possível ativar os aplicativos do Cloud Trace para Ruby usando a biblioteca do Cloud Trace para Ruby.

Como instalar a biblioteca

  1. Instale o Ruby 2.2+ ou superior.

  2. Adicione a gem do Stackdriver ao Gemfile:

    gem "stackdriver"
  3. Use o bundler para instalar a gem:

    bundle install
    

Como ativar a biblioteca

Rails

Se você estiver usando o Ruby on Rails, o bundler carregará a biblioteca no seu aplicativo automaticamente quando ele for iniciado.

Outros

Outros aplicativos baseados em Rack podem usar o middleware do Rack fornecido pela biblioteca:

require "google/cloud/trace"

use Google::Cloud::Trace::Middleware

Para saber mais ou informar problemas com a biblioteca, consulte o repositório de código-fonte da biblioteca.

Como configurar o cliente

É possível personalizar o comportamento da biblioteca do Cloud Trace para Ruby. Consulte a configuração da biblioteca para conseguir uma lista das possíveis opções de configuração.

Adicionar período de trace personalizado

A biblioteca do Cloud Trace para Ruby cria automaticamente um registro de trace para cada solicitação recebida pelo aplicativo Rack. Também é possível adicionar períodos de trace personalizados a cada solicitação:

Google::Cloud::Trace.in_span "my_task" do |_span|
  # Insert task

  Google::Cloud::Trace.in_span "my_subtask" do |subspan|
    # Insert subtask
  end
end

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 para Ruby usam o Application Default Credentials (ADC) para encontrar as credenciais do seu aplicativo. A seção a seguir descreve como definir essas credenciais e o código do projeto do Google Cloud.

Como configurar o ID e as credenciais do projeto do Google Cloud

Esta seção descreve três abordagens diferentes que você pode usar para definir o código do projeto do Google Cloud, as credenciais de autenticação ou ambos no seu aplicativo Ruby.

Variável de ambiente

Quando você não define explicitamente o código do projeto do Google Cloud, a biblioteca Ruby google-cloud determina automaticamente se a variável de ambiente GOOGLE_CLOUD_PROJECT está definida e, em caso afirmativo, a biblioteca usa o valor de GOOGLE_CLOUD_PROJECT como seu código do projeto do Cloud. Para mais informações, acesse Autenticação.

Conforme descrito anteriormente, as bibliotecas de cliente do Google Cloud usam o Application Default Credentials (ADC) para encontrar as credenciais do seu aplicativo. É possível fornecer essas credenciais definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS:

Linux/macOS

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Windows

Janela de comando:

set GOOGLE_CLOUD_PROJECT=your-project-id
set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

PowerShell:

$env:GOOGLE_CLOUD_PROJECT="your-project-id"
$env:GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

Interface de configuração do Ruby on Rails

Se você estiver usando Ruby on Rails, uma alternativa ao Ruby é fornecer os parâmetros por meio da interface de configuração:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Trace specific parameters
  config.google_cloud.trace.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.trace.keyfile    = "/path/to/service-account.json"
end

Também é possível definir a configuração compartilhada para o gem completo do Stackdriver usando:

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Shared parameters
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
end

O Trace é ativado por padrão quando o Rails está em execução no modo de produção. Para ativar o Trace no modo de desenvolvimento, adicione o código a seguir:

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_trace = true
end

Interface de configuração de instrumentação

Outra alternativa ao Ruby é fornecer os parâmetros por meio da interface de configuração quando usado em outros aplicativos baseados no Rack:

require "google/cloud/trace"

Google::Cloud.configure do |config|
  # Stackdriver Trace specific parameters
  config.trace.project_id = "YOUR-PROJECT-ID"
  config.trace.keyfile    = "/path/to/service-account.json"
end

Você também pode definir o compartilhamento das configurações para todas as gems do Stackdriver. Para isso, use o comando:

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

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