Rack

Para instrumentar aplicações Rack, o AppSignal fornece um middleware de instrumentation Rack. Se você usa algum dos frameworks Rack suportados como Rails, Sinatra, Hanami, Grape ou Padrino, recomendamos usar essas instrumentations em vez deste.

Adicionar o middleware de instrumentation

Usando uma gem AppSignal Ruby mais antiga? Siga nosso guia legado.

Para integrar o AppSignal em uma aplicação Rack, primeiro precisamos carregar, configurar e iniciar o AppSignal. Em seguida, instrumente o app Rack adicionando nossos middlewares EventMiddleware e InstrumentationMiddleware do Rack à pilha de middleware. Esta documentação explica como fazer isso no arquivo config.ru da sua aplicação.

# config.ru
require "appsignal"                           # Carrega o AppSignal

Appsignal.start                               # Inicia a integração AppSignal

# Adiciona primeiro o EventMiddleware do Rack
use Appsignal::Rack::EventMiddleware
# Adiciona o InstrumentationMiddleware do Rack
use Appsignal::Rack::InstrumentationMiddleware

# Carregue seu app com uma instrução require aqui, como
require_relative "app"

# Adicione outros middleware aqui, se necessário

# Por fim, execute o app
use MyApp.run

Certifique-se de que EventMiddleware e InstrumentationMiddleware estejam registrados na pilha de middleware da aplicação o mais cedo possível. Quanto mais cedo esses middlewares forem registrados, mais runtime da requisição o middleware irá instrumentar. Se outros middlewares forem registrados antes, nossos middlewares não irão instrumentá-los. Após adicionar EventMiddleware e InstrumentationMiddleware à pilha de middleware do seu app, a action precisa ser definida para cada rota no seu app no AppSignal. Sem um nome de action para agrupar as requisições, o event middleware não reportará as informações da requisição. Para mais insights sobre o funcionamento da sua aplicação Rack, recomendamos adicionar instrumentation adicional aos endpoints da aplicação.

O event middleware Rack

Recomendamos adicionar nosso event middleware Rack a todas as aplicações Rack. Este middleware garantirá que rastreemos O event middleware Rack do AppSignal tem as seguintes funcionalidades:

Instrumentation da requisição e registro de um evento process_request.rack.
Reporte de Exceptions que ocorrem no app e no middleware.
Rastreamento do status code da response como a tag response_status no trace.
Rastreamento do status code da response como a métrica response_status, com as tags namespace e status.

O instrumentation middleware Rack

Recomendamos que além do Appsignal::Rack::EventMiddleware, o AppSignal::Rack::InstrumentationMiddleware seja adicionado ao app. Este middleware complementa a instrumentation do event middleware adicionando tags para o caminho da requisição e o método da requisição, bem como rastreando o tratamento e o fechamento do response body. O instrumentation middleware tem as seguintes funcionalidades:

Instrumentation da requisição e registro de um evento process_request.rack.
Reporte de Exceptions que ocorrem no app.
Rastreamento do caminho da requisição e do método da requisição como tags no trace.
Instrumentation do tratamento do response body e registro de um evento process_response_body.rack para esta operação.
Instrumentation do fechamento do response body e registro de um evento close_response_body.rack para esta operação.

Usando o middleware de instrumentation legado

O middleware GenericInstrumentation foi descontinuado na gem Ruby 3.10.0. Por favor, use o novo guia em vez disso.

Para integrar o AppSignal em uma aplicação Rack, primeiro precisamos carregar, configurar e iniciar o AppSignal. Em seguida, instrumente o app Rack adicionando nosso middleware GenericInstrumentation do Rack à pilha de middleware. Esta documentação explica como fazer isso no arquivo config.ru da sua aplicação.

# config.ru
# Carrega e configura o AppSignal
require "appsignal"                           # Carrega o AppSignal

Appsignal.config = Appsignal::Config.new(
  File.expand_path("../", __FILE__),          # Caminho raiz da aplicação
  ENV["RACK_ENV"],                            # Ambiente da aplicação
)
Appsignal.start                               # Inicia a integração AppSignal
Appsignal.start_logger                        # Inicia o logger

# Carregue seu app com uma instrução require aqui, como
require_relative "app"

# Adiciona o middleware GenericInstrumentation
use Appsignal::Rack::GenericInstrumentation

# Adicione outros middleware aqui, se necessário

# Por fim, execute o app
use MyApp.run

Definindo o nome da action

Defina um nome de action na transaction do AppSignal para uma requisição para que possamos agrupar endpoints em nossos issues e métricas. Recomendamos usar um nome de action estático por endpoint, como GET /blog, POST /users, PUT /users/:id, etc. Para definir um nome de action para uma requisição, chame o helper Appsignal.set_action a partir do app.

Não use o caminho da requisição da rota como o nome da action se o caminho tiver segmentos dinâmicos. Usar caminhos de requisição reais para nomes de action quebra nosso agrupamento de requisições, criando issues únicos para cada possível caminho de requisição.

# app.rb
require "rack"

# Exemplo de app Rack puro
class MyApp
  def call(env)
    case [env["REQUEST_METHOD"], env["PATH_INFO"]]
    when ["GET", "/"]
      Appsignal.set_action("GET /") # Nome da action definido aqui
      body = <<~BODY
        <h1>Rack example app</h1>

        <ul>
          <li><a href="/slow">Slow request</a></li>
          <li><a href="/error">Error request</a></li>
        </ul>
      BODY
      [200, {"Content-Type" => "text/html"}, [body]]
    when ["GET", "/slow"]
      Appsignal.set_action("GET /slow") # Nome da action definido aqui
      sleep 1
      [200, {"Content-Type" => "text/plain"}, ["Slow response"]]
    when ["GET", "/error"]
      Appsignal.set_action("GET /error") # Nome da action definido aqui
      raise "uh oh"
    else
      Appsignal.set_action("NotFound") # Nome da action definido aqui
      [404, {"Content-Type" => "text/plain"}, ["Page not found"]]
    end
  end
end

Atributos de span

Somente no modo collector: isso se aplica quando o AppSignal para Ruby é executado no modo collector. Nos demais casos, não tem efeito.

O span da requisição carrega:

http.request.method — o método da requisição.
url.scheme, url.path e url.query — o endereço requisitado.
http.response.status_code — o status com o qual sua aplicação respondeu.

Um span para uma requisição que gerou um erro também carrega error.type, a classe do erro.

Distributed tracing

Somente no modo collector: isso se aplica quando o AppSignal para Ruby é executado no modo collector. Nos demais casos, não tem efeito.

Uma requisição que chega com um header de requisição traceparent continua o trace que ele nomeia. A requisição aparece dentro do trace do serviço que a chamou, sob a requisição que a causou. Você pode seguir uma requisição lenta desse serviço até esta aplicação sem trocar de trace. Os clientes HTTP suportados pelo AppSignal iniciam o trace. Uma requisição sem o header inicia um novo.

SDKs & telemetria

SDKs de linguagem

Ferramentas de telemetria

Adicionar o middleware de instrumentation

O event middleware Rack

O instrumentation middleware Rack

Usando o middleware de instrumentation legado

Definindo o nome da action

Atributos de span

Distributed tracing

​Adicionar o middleware de instrumentation

​O event middleware Rack

​O instrumentation middleware Rack

​Usando o middleware de instrumentation legado

​Definindo o nome da action

​Atributos de span

​Distributed tracing

Adicionar o middleware de instrumentation

O event middleware Rack

O instrumentation middleware Rack

Usando o middleware de instrumentation legado

Definindo o nome da action

Atributos de span

Distributed tracing