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

Instale o Ruby 2.2+ ou posterior.
Adicione a gem do Stackdriver ao Gemfile:
```
gem "stackdriver"
```
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

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:

Ambiente flexível do App Engine
Ambiente padrão do App Engine
Google Kubernetes Engine (GKE)

Observação :se você usa o Autopilot ou se ativar a Identidade da carga de trabalho no cluster do GKE, configure o aplicativo para usar a Identidade da carga de trabalho.
Compute Engine
Cloud Run

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 do ambiente usando o console do Google Cloud, consulte Como configurar o 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 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 o Ruby on Rails, forneça os parâmetros por meio da interface de configuração do Ruby on Rails:

# 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

Ver traces

No painel de navegação do console do Google Cloud, selecione Trace e, em seguida, Trace Explorer:

Acessar o Explorador de traces

Solução de problemas

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