Guia de migração do agente Ruby 9.x para 10.x

Este guia aborda as principais mudanças entre as séries 9.x e 10.x do agente Ruby e como ter uma migração bem-sucedida.

Resumo

As principais mudanças na v10.0 incluem:

Removido o suporte para Ruby 2.4 e 2.5
Removido o Cross Application Tracing (CAT) e APIs relacionadas
Removida a compatibilidade com o registro de implantações por meio do agente
Removido NewRelic::Agent::SqlSampler#notice_sql e simplificadas as APIs NewRelic::Agent::Datastores
Removido o suporte para versões do Puma '<' 3.9.0
Removeu o recurso experimental Configurable Security Policies (CSP)
Métricas e segmentos do ActiveJob renomeados
Comando bin/newrelic renomeado para bin/newrelic_rpm

Consulte o marco para 10.0 para obter mais informações.

Juntamente com essas mudanças significativas, há várias outras melhorias. Consulte o CHANGELOG para obter mais detalhes.

Removido o suporte para Ruby 2.4 e 2.5

Ruby 2.4 e 2.5 não são mais suportados pelo agente Ruby. Para continuar usando a versão mais recente do agente Ruby, atualize para Ruby 2.6.0 ou superior.

A New Relic continua a oferecer suporte a certas versões mais antigas do Ruby, mesmo depois que elas saíram da janela de manutenção oficialmente suportada fornecida pela equipe de desenvolvimento da linguagem Ruby. Por exemplo, em 31 de março de 2026, a versão Ruby mais antiga suportada pela equipe Ruby será a versão 3.3, enquanto com a versão 10.0 do agente Ruby, as versões Ruby 2.6 e superiores ainda são suportadas. Para obter mais informações sobre o suporte oficial da equipe Ruby às versões Ruby, consulte Ruby Maintenance Branches.

Removido o Cross Application Tracing (CAT) e APIs Relacionadas

O Cross Application Tracing (CAT) foi removido em favor do Distributed Tracing. O CAT usava cabeçalhos específicos do New Relic para vincular transações entre aplicativos monitorados pelo APM, enquanto o Distributed Tracing adota o W3C Trace Context. Para ativar o Distributed Tracing, defina a opção de configuração distributed_tracing.enabled como true.

distributed_tracing.enabled: true

A opção de configuração cross_application_tracer.enabled foi removida junto com os seguintes métodos de API pública:

Removida a API CAT	Substituição de Rastreamento Distribuído	Contexto
`NewRelic::Agent::External.process_request_metadata`	`NewRelic::Agent::DistributedTracing.accept_distributed_trace_headers`	Lê os cabeçalhos de contexto de rastreamento W3C de uma solicitação de entrada para vincular o serviço ao rastreamento upstream.
`NewRelic::Agent::External.get_response_metadata`	Nenhum equivalente necessário	Os metadados da resposta são obsoletos; a ligação é tratada pelos cabeçalhos W3C na solicitação.
`NewRelic::Agent::Transaction::ExternalRequestSegment#process_response_metadata`	Nenhum equivalente necessário	O processamento baseado em resposta é removido em favor da propagação do cabeçalho da solicitação.
`NewRelic::Agent::Transaction::ExternalRequestSegment#get_request_metadata`	`NewRelic::Agent::DistributedTracing.insert_distributed_trace_headers`	Cria e adiciona cabeçalhos de Contexto de Rastreamento W3C aos cabeçalhos de requisição de saída.
`NewRelic::Agent::Transaction::ExternalRequestSegment#read_response_headers`	Nenhum equivalente necessário	A ligação de rastreamento não requer a leitura dos cabeçalhos de resposta.

Saiba mais sobre como usar APIs de Rastreamento Distribuído.

Removida a compatibilidade com o registro de implantações por meio do agente

O agente não suporta mais a capacidade de enviar informações de implantação de aplicativos usando uma receita Capistrano ou o comando CLI newrelic deployments. Para rastrear alterações e implantações no New Relic, consulte nosso guia para Rastreamento de Alterações para obter uma lista de opções disponíveis.

Removido `NewRelic::Agent::SqlSampler#notice_sql` e simplificado `NewRelic::Agent::Datastores`

Removeu o método NewRelic::Agent::SqlSampler#notice_sql

O método NewRelic::Agent::SqlSampler#notice_sql foi removido. Para rastrear consultas SQL, você deve usar o método NewRelic::Agent::Datastores.notice_sql em vez disso.

Removidos argumentos não utilizados de várias APIs `NewRelic::Agent::Datastores`

Várias APIs NewRelic::Agent::Datastores foram simplificadas removendo argumentos redundantes. Informações de tempo (elapsed) e escopo de métricas são derivadas automaticamente do segmento atual.

As seguintes APIs foram atualizadas:

API antiga	Nova API	Mudar
`NewRelic::Agent::Datastores.notice_sql(query, scoped_metric, elapsed)`	`NewRelic::Agent::Datastores.notice_sql(query)`	Removidos os argumentos `scoped_metric` e `elapsed`.
`NewRelic::Agent::Datastores.notice_statement(statement, elapsed)`	`NewRelic::Agent::Datastores.notice_statement(statement)`	Removido o argumento `elapsed`.
`NewRelic::Agent::Datastores.wrap(...) do \\|result, scoped_metric, elapsed_time\\|`	`NewRelic::Agent::Datastores.wrap(...) do \\|result\\|`	Removido `scoped_metric` e `elapsed_time` dos argumentos do bloco de retorno.

Removido o suporte para versões do Puma '<'

A versão mínima do Puma agora suportada é 3.9.0 ou superior. Se estiver usando o Puma, atualize para a versão 3.9.0 ou posterior antes de atualizar o agente.

Removeu o recurso experimental Configurable Security Policies (CSP)

O recurso experimental, Configurable Security Policies (CSP), não é mais suportado e foi removido. As configurações de segurança padrão do agente automaticamente fornecem segurança para seus dados APM, no entanto, você pode restringir ainda mais as informações que o New Relic recebe usando o modo de alta segurança.

Métricas e segmentos do ActiveJob renomeados

As métricas e segmentos do ActiveJob foram atualizados para incluir o nome da classe do trabalho para relatórios mais específicos. Atualize todos os painéis personalizados e alertas NRQL que consultam métricas e segmentos do ActiveJob para refletir o novo formato.

Formato antigo:

"Ruby/ActiveJob/#{QueueName}/#{Method}" # metrics
"ActiveJob/#{Adapter}/Queue/#{Event}/Named/#{JobQueueName}" # segments

Novo formato:

"Ruby/ActiveJob/#{QueueName}/#{JobClassName}/#{Method}" # metrics
"ActiveJob/#{Adapter}/Queue/#{Event}/Named/#{JobQueueName}/#{JobClassName}" # segments

Comando `bin/newrelic` renomeado para `bin/newrelic_rpm`

O arquivo executável para a CLI do agente foi renomeado de bin/newrelic para bin/newrelic_rpm. Essa alteração resolve uma colisão de nomes com a ferramenta CLI New Relic autônoma.

Comando antigo:

bash

$bin/newrelic install

Novo comando: