Criar transação via XML (.NET)

Estrutura suportada pelo instrumento New Relic automaticamente. No entanto, você também pode ter outra estrutura para a qual algumas transações não estão sendo criadas automaticamente ou métodos adicionais que você gostaria de utilizar. Você pode adicionar instrumentação personalizada a esses métodos criando transações. transações criadas via XML são classificadas como não-web na interface New Relic.

Este documento descreve como criar transações com um arquivo XML. Você também pode:

• Adicione detalhes à transação existente usando XML
• Crie transações e adicione detalhes às transações existentes com a API do agente .NET.

Se você tiver um aplicativo não IIS, a instrumentação XML exigirá a ativação da opção Instrument all durante a instalação do agente .NET.

Criar transação usando XML

A transação personalizada (transação não instrumentada automaticamente) é definida em um arquivo XML de instrumentação personalizada. Você define um método que aciona a criação de uma transação. Você também pode instrumentar métodos adicionais chamados pelo método trigger.

Algumas regras importantes que você deve saber antes de criar uma transação personalizada:

• Chamadas externas e de banco de dados não exigem instrumentação personalizada porque são instrumentadas automaticamente.
• Certifique-se de que seu arquivo XML esteja no caminho correto. Para definir seu conjunto de instrumentação, o agente .NET lê cada arquivo XML no diretório Extensions .
• Se um método que você tentar instrumentalizar já fizer parte de uma transação existente, ele será adicionado como um segmento a essa transação. Nenhuma nova transação será criada. Isso ocorrerá mesmo se o método pai for instrumentado usando instrumentação personalizada.
• Evite coisas instrumentadas como Main() , pois esse método não terminará até que o aplicativo termine e os dados não poderão ser enviados para o New Relic.

Para criar um arquivo de instrumentação personalizada:

1. Crie um novo arquivo .xml no diretório Extensions dentro do diretório do agente .NET. A localização deste diretório depende do seu sistema operacional:

   Para a framework .NET ou agente Core no Windows

   C:\ProgramData\New Relic\.NET Agent\Extensions

   Copiar

   Importante

   Use o diretório ProgramData , não o diretório Program Files .

   Para .NET Core no Linux

   PATH_TO_AGENT_DIRECTORY/Extensions

   Copiar

   PATH_TO_AGENT_DIRECTORY será o padrão /usr/local/newrelic-dotnet-agent (agente versões 10.0.0 ou superior), /usr/local/newrelic-netcore20-agent (agente versões 9.9.0 ou inferior) ou o diretório escolhido na instalação.

   Para serviços de aplicativos do Azure

   Agente para .NET framework:

   D:\home\site\wwwroot\newrelic\extensions

   Copiar

   Agente para .NET Core:

   D:\home\site\wwwroot\newrelic_core\extensions

   Copiar

2. Copie este modelo no arquivo que você criou. Este modelo define duas classes e métodos separados como transação, mas mais podem ser adicionados:

   <?xml version="1.0" encoding="utf-8"?>
   <extension xmlns="urn:newrelic-extension">
     <instrumentation>
       <!-- Define the method which triggers the creation of a transaction. -->
       <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="TransactionName">
         <match assemblyName="AssemblyName" className="NameSpace.ClassName">
           <exactMethodMatcher methodName="MethodName" />
         </match>
       </tracerFactory>
       <!-- Define the method which triggers the creation of a transaction. -->
       <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="TransactionName2">
         <match assemblyName="AssemblyName" className="NameSpace.ClassName2">
           <exactMethodMatcher methodName="MethodName2" />
         </match>
       </tracerFactory>
       <!-- Define the method which triggers the creation of a transaction. -->
       <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="TransactionName3">
         <match assemblyName="AssemblyName" className="NameSpace.ClassName3" minVersion="1.0.0" maxVersion="99.99.99">
           <exactMethodMatcher methodName="MethodName3" />
         </match>
       </tracerFactory>
     </instrumentation>
   </extension>

   Copiar

3. No arquivo que você criou, personalize os valores de atributo TransactionName, AssemblyName, NameSpace.ClassName e MethodName. Personalize esses valores para o método de gatilho e para quaisquer métodos chamados pelo método de gatilho. Você também pode usar os valores de atributo opcionais minVersion e maxVersion para versões específicas de destino de um assembly, conforme mostrado no terceiro exemplo acima. Observe que esta funcionalidade requer o agente 10.6.0 ou superior.

   Dica

   Esses valores diferenciam maiúsculas de minúsculas.

   • TransactionName: Define o nome da transação. O atributo metricName é opcional. Se omitido, o nome da transação será NameSpace.ClassName/MethodName. A categoria da transação será Custom. O nome completo da métrica resultante será OtherTransaction/Custom/TransactionName. Se você deseja alterar a categoria da transação de Custom, use a chamada de API SetTransactionName . A interface New Relic agrupa as transações em categorias no campo tipo de transação.
   • AssemblyName: o assembly que contém o método de gatilho.
   • NameSpace.ClassName: o nome completo da classe que contém o método de disparo.
   • MethodName: o nome exato do método de gatilho.
   • minVersion: Opcional (você pode removê-lo). A versão mínima de montagem para instrumento (inclusive). Se omitido, a versão mínima será considerada 0. Requer agente 10.6.0 ou superior.
   • maxVersion: Opcional (você pode removê-lo). A versão de montagem máxima para instrumento (exclusiva). Se omitido, não há versão máxima. Requer agente 10.6.0 ou superior.

4. A adição de métodos adicionais deve incluir o atributo "NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" para ser definido como uma transação. tag sem esse atributo adicionará detalhes apenas às transações existentes .

5. Opcional: para verificar se o arquivo XML está formatado corretamente, você pode verificá-lo no XSD (localizado em C:\ProgramData\New Relic\.NET Agent\Extensions\extension.xsd) usando qualquer validador XSD.

Ver transação na interface

A transação personalizada começa quando o método especificado por methodName é invocado no assembly especificado por assemblyName. A transação termina quando o método retorna ou lança uma exceção.

Você pode visualizar essas métricas na páginaTransactions e no trace da transação. Para visualizar a transação: Vá para one.newrelic.com > All capabilities > APM & services > (select an app) > Monitor > Transactions > Type > (select a type). O tipo será Non-web/Custom , a menos que você use a API para alterar a categoria.

Exemplo: instrumento três métodos

Este exemplo apresenta uma implementação simples de criação de transação.

<?xml version="1.0" encoding="utf-8"?>
<extension xmlns="urn:newrelic-extension">
  <instrumentation>
    <!-- Define the method which triggers the creation of a transaction. -->
    <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="Bars">
      <match assemblyName="Foo" className="Foo.Bar">
        <exactMethodMatcher methodName="Bar1" />
        <exactMethodMatcher methodName="Bar2" />
      </match>
    </tracerFactory>
    <!-- Instrument 0 or more methods called by the trigger method. These methods appear in the transaction breakdown table and in transaction traces. -->
    <tracerFactory>
      <match assemblyName="Foo" className="Foo.Bar">
        <exactMethodMatcher methodName="Bar3" />
      </match>
    </tracerFactory>
  </instrumentation>
</extension>

var bar = new Bar();
bar.Bar1(); // Creates a transaction named Bars in the Custom category.
bar.Bar2(); // Creates a transaction named Bars in the Custom category.
bar.Bar3(); // Won't create a new transaction. See `If Bar3 is called directly`, below.

namespace Foo
{
    public class Bar
    {
        // The agent creates a transaction that includes an external service request in its transaction traces.
        public void Bar1()
        {
            new WebClient().DownloadString("https://www.google.com/");
        }

        // Creates  a transaction containing one segment.
        public void Bar2()
        {
            // The Bar3 segment will contain your SQL query inside of it and possibly an execution plan.
            Bar3();
        }

        // If Bar3 is called directly, the agent will not create a transaction.
        // However, if Bar3 is called from Bar1 or Bar2, Bar3 will appear as a segment containing its SQL query.
        private void Bar3()
        {
            using (var connection = new SqlConnection(ConnectionStrings["MsSqlConnection"].ConnectionString))
            {
                connection.Open();
                using (var command = new SqlCommand("SELECT * FROM table", connection))
                using (var reader = command.ExecuteReader())
                {
                    reader.Read();
                }
            }
        }
    }
}

Exemplo: instrumento para aplicativo de console

Este aplicativo de console simples demonstra a criação de transações. Depois de executar o aplicativo algumas vezes, você verá a transação que criou na página de transação (em one.newrelic.com > All capabilities > APM & services > (select an app) > Transactions > Type). O segmento Dummy ficará visível na tabela de detalhamento das transações e em qualquer rastreamento da transação.

<?xml version="1.0" encoding="utf-8"?>
<extension xmlns="urn:newrelic-extension">
    <instrumentation>
        <!-- Define the method which triggers the creation of a transaction. -->
        <tracerFactory name="NewRelic.Agent.Core.Tracer.Factories.BackgroundThreadTracerFactory" metricName="CustomTransaction">
          <match assemblyName="ConsoleApplication1" className="ConsoleApplication1.CustomTransaction">
            <exactMethodMatcher methodName="StartTransaction" />
          </match>
        </tracerFactory>
        <!-- Instrument 0 or more methods called by the trigger method. These methods appear in the transaction breakdown table and in transaction traces. -->
        <tracerFactory>
          <match assemblyName="ConsoleApplication1" className="ConsoleApplication1.CustomTransaction">
            <exactMethodMatcher methodName="Dummy" />
          </match>
        </tracerFactory>
    </instrumentation>
</extension>

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace ConsoleApplication1
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Custom Transactions");
            var t = new CustomTransaction();
            while (true)
                t.StartTransaction();
        }
    }
    class CustomTransaction
    {
        public void StartTransaction()
        {
            Console.WriteLine("StartTransaction");     
            Dummy();
        }
        void Dummy()
        {
            System.Threading.Thread.Sleep(5000);
        }
    }

}