Editor de instrumentação personalizada: instrumento da interface

O editor de instrumentação personalizada da New Relic permite que usuários de aplicativos Java implementem instrumentação personalizada por meio da interface do usuário da New Relic. O editor é a escolha preferida quando você não pode modificar o código do seu aplicativo e não possui muitos métodos para instrumentalizá-lo. Veja instrumentação Java personalizada para outras opções de instrumentação e as razões para usar cada uma.

Para utilizar o editor de instrumentação personalizada: Acesse one.newrelic.com > All capabilities > APM & services > (select a Java app) > Settings > Instrumentation. Utilize o editor de instrumentação personalizada para:

Instrumento uma framework sem suporte.
Obtenha insights adicionais sobre métodos não instrumentados.
Ignorar transação específica.

Requisitos

Para utilizar o editor de instrumentação personalizada, você deve atender aos seguintes requisitos:

Requirement	Comments
Agente	Agente Java versão 3.17.0 ou superior
Segurança	O usuário do modo de alta segurança deve exportar sua instrumentação e importá-la manualmente para seu servidor de aplicativos.

Definir instrumentação personalizada

Para definir a instrumentação personalizada a partir da interface do usuário do New Relic, use uma sessão de criação de perfil de thread para coletar rastreamento de pilha detalhado de cada thread em seu aplicativo. Se possível, teste sua instrumentação personalizada em um pré-ambiente de produção antes de alterar as regras de instrumentação no seu aplicativo de produção.

Em qualquer ambiente, utilize o editor de instrumentação personalizada para definir os métodos que deseja instrumentar, e aplique suas alterações:

Crie uma nova sessão do criador de perfil de thread. Para garantir que você colete um conjunto de dados suficiente, a duração da sessão será de pelo menos dois minutos.
Vá para one.newrelic.com > All capabilities > APM & services > (select an app) > Settings > Instrumentation. Role para baixo até a parte inferior da página até ver a lista Recently collected thread profiles e selecione o perfil de conversa mais recente.
Expanda métodos individuais para localizar métodos não instrumentados métodos.
Para definir regras de instrumentação para nós específicos, selecione Instrument ou Ignore e personalize as regras, se necessário.
Para salvar suas configurações, selecione Confirm instrumentation changes.
Implantar suas alterações na páginaInstrumentation :
- Para implantar suas alterações automaticamente, selecione
  Deploy instrumentation changes
  .
- Para implantar suas alterações manualmente, selecione
  Export XML
  e consulte exportando sua instrumentação.

Cuidado

Evite instrumentado demais sempre que possível. Com cada método adicional instrumentado, o agente usará mais recursos e seu aplicativo incorrerá em mais sobrecarga. Além disso, implantar sua instrumentação causará um breve período de maior sobrecarga. Isso pode retardar visivelmente as solicitações do aplicativo por vários segundos.

Se você aplicou suas alterações na interface, o agente começará a instrumentar seus métodos dentro de alguns ciclos de coleta (normalmente alguns minutos).

Instrumentação manual usando o editor

Você também pode criar pontos de instrumentação diretamente no editor sem usar um perfil de rosca:

No editor de instrumentação personalizada, selecione
Add manual instrumentation
para inserir manualmente uma classe e um método a serem instrumentados ou ignorados.
Siga as regras de instrumentação personalizada por XML ao definir seus pontos de instrumentação.
Implantar suas alterações no editor de instrumentação.

Usar esse método para adicionar instrumentação expõe funcionalidades adicionais além do que está disponível em um perfil de thread. Além de combinar métodos por assinatura, você também pode instrumentar métodos por tipo de retorno, métodos em interfaces e por anotação Java.

Esses tipos de instrumentação mais complexos podem ser criados e excluídos no editor, mas não podem ser editados.

Importante

Se um método estiver marcado como Instrumentation not allowed, siga os procedimentos de resolução de problemas da New Relic para instrumentação personalizada.

Alterações implantares manualmente

Você também pode usar o editor de instrumentação personalizada para construir um conjunto de instrumentação personalizada, depois exportar um arquivo de instrumentação e importá-lo manualmente para o seu servidor de aplicativos. Isto é necessário para usuário em modo de alta segurança.

Para exportar sua instrumentação, defina a instrumentação personalizada por meio da interface. Em seguida, selecione Export xml na página Instrumentation e importe o arquivo no seu servidor de aplicativos.

Funções da página

A página Instrumentation oferece suporte ao seguinte recurso:

Se você quiser...	Fazem isto...
Pausar ou desabilitar a instrumentação personalizada	Selecione Disable instrumentation para desativar temporariamente toda a instrumentação personalizada definida pela interface. Selecione Enable instrumentation para reativar suas configurações de instrumentação.
Importe a instrumentação existente	Você pode importar um arquivo xml de instrumentação personalizada existente selecionando Import xml . Você também pode Export xml se não quiser implantar suas alterações automaticamente.
Editar ou excluir pontos de instrumentação	Você não pode editar a instrumentação manual, apenas excluí-la. Selecione Remove para interromper a instrumentação de um método específico. Selecione Edit para alterar as regras de instrumentação.
Ver histórico de instrumentação	Você pode visualizar cada iteração anterior da sua instrumentação personalizada na guia Instrumentation history , incluindo quem implantou as alterações e quando. Você pode restaurar uma versão antiga selecionando export para baixar uma cópia do arquivo de instrumentação personalizada e depois importá -lo para o editor de instrumentação.

Opções de instrumentação

Você pode definir as seguintes opções com o editor de instrumentação personalizada:

Instrumentation options	Comments
Métodos de instrumento	Comece instrumentado o método selecionado. Os métodos instrumentados ficarão visíveis na interface do New Relic. Instrument oferece suporte às seguintes opções filhas: Name the transaction (transaction name) : Substitui o nome da transação padrão, definido pelas regras de nomenclatura automática. Em vez disso, a interface usará o nome listado. Start the transaction when this method executes : em vez de incluir métricas desta métrica dentro de sua transação pai, crie uma nova transação para este método. O comportamento do agente com esta opção depende da existência de uma transação pré-existente no encadeamento.
Report atributo personalizado	O parâmetro do método pode ser capturado como atributo em uma transação. A New Relic relata esses atributos para rastreamento de transação, erros de rastreamento e `Transaction` evento. Por motivos de segurança, a captura de atributo personalizado usando o Custom Instrumentation Editor é disabled por padrão e não pode ser ativada enquanto você estiver usando o modo de alta segurança. Se você deseja reportar um atributo personalizado utilizando o editor de instrumentação personalizada e não deseja que o agente Java esteja em modo de alta segurança, desative o modo de alta segurança e adicione o seguinte texto no bloco `common:` do seu newrelic.yml: `reinstrument: attributes_enabled: true`
Ignorar transação	Ignore totalmente esse método. O agente não reportará métricas deste método, e o método não contribuirá para os cálculos do Apdex.

Instrumentation options

Comments

Métodos de instrumento

Comece instrumentado o método selecionado. Os métodos instrumentados ficarão visíveis na interface do New Relic. Instrument oferece suporte às seguintes opções filhas:

Name the transaction (transaction name)
: Substitui o nome da transação padrão, definido pelas regras de nomenclatura automática. Em vez disso, a interface usará o nome listado.
Start the transaction when this method executes
: em vez de incluir métricas desta métrica dentro de sua transação pai, crie uma nova transação para este método. O comportamento do agente com esta opção depende da existência de uma transação pré-existente no encadeamento.

Report atributo personalizado

O parâmetro do método pode ser capturado como atributo em uma transação. A New Relic relata esses atributos para rastreamento de transação, erros de rastreamento e Transaction evento.

Por motivos de segurança, a captura de atributo personalizado usando o Custom Instrumentation Editor é disabled por padrão e não pode ser ativada enquanto você estiver usando o modo de alta segurança. Se você deseja reportar um atributo personalizado utilizando o editor de instrumentação personalizada e não deseja que o agente Java esteja em modo de alta segurança, desative o modo de alta segurança e adicione o seguinte texto no bloco common: do seu newrelic.yml:

reinstrument:
    attributes_enabled: true

Ignorar transação

Ignore totalmente esse método. O agente não reportará métricas deste método, e o método não contribuirá para os cálculos do Apdex.

Resultados com opção "iniciar"

Se você selecionar Instrument methods > Start the transaction when this method executes, o comportamento do agente dependerá de haver uma transação pré-existente no encadeamento.

Quando a classe ou método é instrumentado:

A sinalização "Start the transaction" está marcada?
Se uma transação pré-existente is nesse encadeamento e o sinalizador Start the transaction is estiver marcado: O agente ignora o sinalizador Start the transaction . O agente inclui a classe/método na transação pré-existente.	Se uma transação pré-existente is nesse thread e o sinalizador Start the transaction não estiverem marcados, o agente inclui a classe/método na transação pré-existente.
Se uma transação não estiver nesse encadeamento e o sinalizador Start the transaction is estiver marcado: O agente descobre que não há transação atual. O agente cria uma nova transação começando pela classe/método que você instrumentou.	Se uma transação não estiver nesse encadeamento e o sinalizador Start the transaction não estiver verificado: O agente procura uma transação nesse thread e não a encontra. A métrica foi descartada.

A sinalização "Start the transaction" está marcada?

Yes

Se uma transação pré-existente is nesse encadeamento e o sinalizador Start the transaction is estiver marcado:

O agente ignora o sinalizador
Start the transaction
.
O agente inclui a classe/método na transação pré-existente.

Se uma transação pré-existente is nesse thread e o sinalizador Start the transaction não estiverem marcados, o agente inclui a classe/método na transação pré-existente.

Se uma transação não estiver nesse encadeamento e o sinalizador Start the transaction is estiver marcado:

O agente descobre que não há transação atual.
O agente cria uma nova transação começando pela classe/método que você instrumentou.

Se uma transação não estiver nesse encadeamento e o sinalizador Start the transaction não estiver verificado:

O agente procura uma transação nesse thread e não a encontra.
A métrica foi descartada.

Esta tradução de máquina é fornecida para sua comodidade.