Logs contextualizados do agente Java

Esta é a abordagem mais simples e é uma ótima opção para desenvolvedores que podem não ter acesso ou interesse em configurar um direcionador de logs ou para contas que desejam ver o poder do log e outros metadados de vinculação no contexto de seus aplicativos sem muita sobrecarga.

Usando esta opção, o agente adiciona span.id, trace.id, hostname, entity.guid e entity.name. Saiba mais sobre as limitações de encaminhamento de logs.

Esta funcionalidade está habilitada por padrão.

Tudo o que você precisa fazer é instalar uma versão do agente com recursos de encaminhamento de logs (agente Java 7.6.0 ou superior). Se o encaminhamento estiver desabilitado, você poderá usar esta configuração:

Arquivo de configuração (newrelic.yml), recuado 2 espaços na seção comum:

application_logging:
  enabled: true
  forwarding:
    enabled: true
    max_samples_stored: 10000
  local_decorating:
    enabled: false

Variável de ambiente:

NEW_RELIC_APPLICATION_LOGGING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_FORWARDING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_FORWARDING_MAX_SAMPLES_STORED=10000
NEW_RELIC_APPLICATION_LOGGING_LOCAL_DECORATING_ENABLED=false

Propriedade do sistema:

-Dnewrelic.config.application_logging.enabled=true
-Dnewrelic.config.application_logging.forwarding.enabled=true
-Dnewrelic.config.application_logging.forwarding.max_samples_stored=10000
-Dnewrelic.config.application_logging.local_decorating.enabled=false

Optional adjustments (max_samples_stored):

Depois que esse recurso estiver ativado, você também terá controle sobre o número máximo de linhas de log enviadas ao New Relic a cada minuto. O valor padrão é 10.000. Se mais de 10.000 linhas log forem visualizadas pelo agente em uma janela de 60 segundos, seu log começará a ser amostrado.

Defina-o para um número mais alto para receber mais log. Defina-o para um número menor para receber menos log. Qualquer número inteiro não negativo é válido.

Arquivo de configuração (newrelic.yml):

application_logging:
  enabled: true
  forwarding:
    enabled: true
    max_samples_stored: 10000
  local_decorating:
    enabled: false

Variável de ambiente:

NEW_RELIC_APPLICATION_LOGGING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_FORWARDING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_FORWARDING_MAX_SAMPLES_STORED=10000
NEW_RELIC_APPLICATION_LOGGING_LOCAL_DECORATING_ENABLED=false

Propriedade do sistema:

-Dnewrelic.config.application_logging.enabled=true
-Dnewrelic.config.application_logging.forwarding.enabled=true
-Dnewrelic.config.application_logging.forwarding.max_samples_stored=10000
-Dnewrelic.config.application_logging.local_decorating.enabled=false

Já tem um encaminhador de logs que você gosta? Estamos protegendo você! O agente Java pode decorar seu log com os metadados de link necessários para fornecer acesso ao recurso automático de log-in-context, e você pode enviá-los para New Relic usando seu manual de direcionamento de logs.

Atualize a configuração do seu agente para desabilitar o encaminhamento de logs e habilitar a decoração local, depois reinicie o agente para começar a decorar seu log.

Arquivo de configuração (newrelic.yml), recuado 2 espaços na seção comum:

application_logging:
  enabled: true
  local_decorating:
    enabled: true
  forwarding:
    enabled: false

Variável de ambiente:

NEW_RELIC_APPLICATION_LOGGING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_LOCAL_DECORATING_ENABLED=true
NEW_RELIC_APPLICATION_LOGGING_FORWARDING_ENABLED=false

Propriedade do sistema:

-Dnewrelic.config.application_logging.enabled=true
-Dnewrelic.config.application_logging.local_decorating.enabled=true
-Dnewrelic.config.application_logging.forwarding.enabled=false

Nosso decorador adiciona cinco atributos a cada mensagem do log no arquivo de log do aplicativo: entity.guid, hostname, trace.id, span.id e entity.name. Exemplo:

This is my log message. NR-LINKING|{entity.guid}|{hostname}|{trace.id}|{span.id}|{entity.name}|

Se a mensagem do log estiver vazia ou em branco, a mensagem de saída também estará vazia. Exemplo:

NR-LINKING|{entity.guid}|{hostname}|{trace.id}|{span.id}|{entity.name}|.

A mensagem do log de saída será uma string vazia.

Alguns atributos podem ficar vazios se o log ocorreu fora de uma transação ou se não forem aplicáveis ao contexto do seu aplicativo.

Oferecemos uma extensão Dropwizard para logs contextualizados com o agente Java. Para começar, revise o código e um exemplo de aplicativo no GitHub.

Para configurar o logs contextualizados para seu aplicativo Java com a extensão DropWizard:

1. Certifique-se de ter o pacote Dropwizard 1.3 ou superior instalado e funcionando em seu aplicativo. Use os anexadores originais do Dropwizard e o log de fábrica instalado e funcionando no aplicativo.

2. Certifique-se de ter o agente Java New Relic versão 5.6.0 ou superior instalado em seu aplicativo e de ter ativado o argumento JVM -javaagent.

3. Atualize a dependência do seu projeto para incluir a extensão Dropwizard 1.3 conforme aplicável:

   Gradle: Adicione o seguinte ao seu arquivo build.gradle :

   dependencies {
     implementation("com.newrelic.logging:dropwizard:2.0")
   }

   Copiar

   Maven: Adicione o seguinte ao seu arquivo pom.xml :

   <dependencies>
     <dependency>
       <groupId>com.newrelic.logging</groupId>
       <artifactId>dropwizard</artifactId>
       <version>2.0</version>
     </dependency>
   </dependencies>

   Copiar

4. Atualize seu arquivo de configuração .yaml do Dropwizard com um layout newrelic-json , substituindo o type: console ou type: file usado atualmente por type: newrelic-console ou type: newrelic-file conforme apropriado. Por exemplo:

   logging:
     appenders:
       - type: newrelic-console
         # Add the two lines below if you don't have a layout specified on the appender.
         # If you have a layout, remove all parameters to the layout and set the type.
         layout:
           type: newrelic-json

   Copiar

   A extensão New Relic Dropwizard também oferece suporte a um tipo de layout log-format que usa o registro padrão do Dropwizard. Para fins de teste, você pode alterar o tipo de layout com uma alteração de uma linha:

   logging:
     appenders:
       - type: newrelic-file
         # This format will be ignored by the newrelic-json layout, but used by the log-format layout.
         logFormat: "%date{ISO8601} %c %-5p: %m trace.id=%mdc{trace.id} span.id=%mdc{span.id}%n"
         layout:
           # type: newrelic-json
           type: log-format

   Copiar

Oferecemos uma extensão java.util.logging para logs contextualizados com o agente Java. Para começar, revise o código e um exemplo de aplicativo no GitHub.

Para configurar o logs contextualizados para seu aplicativo Java com a extensão java.util.logging :

1. Certifique-se de ter o pacote java.util.logging instalado e funcionando no aplicativo.

2. Certifique-se de ter o agente Java New Relic versão 5.6.0 ou superior instalado em seu aplicativo e de ter ativado o argumento JVM -javaagent.

3. Atualize a dependência do seu projeto para incluir a extensão java.util.logging conforme aplicável. Se não for possível editar esses arquivos, você poderá adicionar os jars diretamente ao aplicativo classpath.

   Gradle: Adicione o seguinte ao seu arquivo build.gradle :

   dependencies {
     implementation("com.newrelic.logging:jul:2.0")
   }

   Copiar

   Maven: Adicione o seguinte ao seu arquivo pom.xml :

   <dependencies>
     <dependency>
       <groupId>com.newrelic.logging</groupId>
       <artifactId>jul</artifactId>
       <version>2.0</version>
     </dependency>
   </dependencies>

   Copiar

4. Verifique se a propriedade handlers do seu arquivo de registro está definida como algo diferente de NewRelicMemoryHandler. Procure uma linha listando os manipuladores do agente root, assim:

   handlers = java.util.logging.FileHandler

   Copiar

5. Atualize seu arquivo de propriedades de registro para definir o manipulador do agente raiz como NewRelicMemoryHandler para que ele intercepte mensagens destinadas a outro manipulador:

   handlers = com.newrelic.logging.jul.NewRelicMemoryHandler

   Copiar

6. Configure o NewRelicMemoryHandler definindo o destino para o manipulador que foi atribuído anteriormente ao agente root, para que ele capture os dados que New Relic precisa no thread de onde vem a mensagem do log:

   com.newrelic.logging.jul.NewRelicMemoryHandler.target = java.util.logging.FileHandler

   Copiar

7. Use um NewRelicFormatter para o manipulador final. Atualize seu arquivo de propriedades de criação de log para configurar a propriedade formatter como no exemplo a seguir. Certifique-se de que o manipulador onde você definiu o formatador seja o manipulador target da etapa anterior (java.util.logging.FileHandler neste exemplo).

   java.util.logging.FileHandler.formatter = com.newrelic.logging.jul. NewRelicFormatter

   Copiar

   O formato New Relic Logs é JSON com metadados de telemetria que usamos para correlacionar transações e logs juntos. Atualmente não oferecemos suporte a nenhuma personalização desse formato.

   Depois de concluído, JSON é log em vez de texto. O JSON deve ser formatado como objetos únicos, um por linha, e deve conter campos como log.level e thread.name. O trace.id, que é necessário para logs contextualizados, só deve ter valor para mensagem do log que ocorrer dentro de uma transação.

A maneira mais direta de obter as extensões de contexto de login é adicionar essas dependências ao pom.xml do Maven ou ao build.gradle do Gradle. Isso permite que as ferramentas de empacotamento selecionem a dependência correta.

Se não for possível editar esses arquivos, você poderá adicionar os jars diretamente ao aplicativo classpath para a configuração da sua framework de log.

Antes de modificar o caminho de classe:

1. Ative o argumento JVM -javaagent no agente Java do seu aplicativo.
2. Verifique qual framework de log o aplicativo está usando.
3. Certifique-se de poder alterar a configuração da sua framework de log.
4. Adicione os três jars a seguir ao caminho de classe se eles ainda não estiverem presentes. Geralmente, recomendamos usar as versões mais recentes publicadas no Maven Central.

• ID do grupo com.newrelic.logging e ID do artefato: selecione o artefato com o nome framework de registro do seu aplicativo no Maven.
• ID do grupo com.fasterxml.jackson.core e ID do artefato: Use jackson-core.
• ID do grupo com.newrelic.agent.java e ID do artefato: Use newrelic-api.

Oferecemos uma extensão Log4j 1.x para logs contextualizados manual com o agente Java. Para começar, revise o código e um exemplo de aplicativo no GitHub.

Para configurar o logs contextualizados manual para seu aplicativo Java com a extensão Log4j 1.x, você deve configurar a extensão Log4j em código ou via XML. Os arquivos de propriedades não são suportados porque a instância AsyncAppender só pode ser configurada automaticamente via XML.

1. Certifique-se de ter o pacote Log4j 1.x instalado e funcionando no aplicativo.

2. Certifique-se de ter o agente Java New Relic versão 5.6.0 ou superior instalado em seu aplicativo e de ter ativado o argumento JVM -javaagent.

3. Atualize a dependência do seu projeto para incluir a extensão Log4j 1.x conforme aplicável.

   Gradle: Adicione o seguinte ao seu arquivo build.gradle :

   dependencies {
     implementation("com.newrelic.logging:log4j1:2.0")
   }

   Copiar

   Maven: Adicione o seguinte ao seu arquivo pom.xml :

   <dependencies>
     <dependency>
       <groupId>com.newrelic.logging</groupId>
       <artifactId>log4j1</artifactId>
       <version>2.0</version>
     </dependency>
   </dependencies>

   Copiar

4. No arquivo XML de configuração de registro, atualize seu elemento <appender> com um NewRelicLayout, adicionando <layout class="com.newrelic.logging.log4j1.NewRelicLayout"/>:

   <appender name="TypicalFile" class="org.apache.log4j.FileAppender">
     <param name="file" value="logs/log4j1-app.log"/>
     <param name="append" value="false"/>
     <layout class="com.newrelic.logging.log4j1.NewRelicLayout"/> <!-- only this line needs to be added -->
   </appender>

   Copiar

5. Use NewRelicAsyncAppender para agrupar quaisquer anexadores que irão direcionar os logs do New Relic. Por exemplo:

   <appender name="NewRelicFile"
             class="com.newrelic.logging.log4j1.NewRelicAsyncAppender">
     <appender-ref ref="TypicalFile" />
   </appender>

   Copiar

6. Use o anexador assíncrono no agente raiz. Por exemplo:

   <root>
     <appender-ref ref="NewRelicFile" />
   </root>

   Copiar

   Example configuration file for the Log4j 1.x extension:

   <?xml version="1.0" encoding="UTF-8" ?>
   <!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
   <log4j:configuration debug="false">
     <appender name="TypicalFile" class="org.apache.log4j.FileAppender">
       <param name="file" value="logs/log4j1-app.log"/>
       <param name="append" value="false"/>
       <!-- layout has been replaced -->
       <layout class="com.newrelic.logging.log4j1.NewRelicLayout"/>
     </appender>
   
       <!-- this appender was added -->
     <appender name="NewRelicFile"
               class="com.newrelic.logging.log4j1.NewRelicAsyncAppender">
       <appender-ref ref="TypicalFile" />
     </appender>
   
     <appender name="TypicalConsole" class="org.apache.log4j.ConsoleAppender">
       <layout class="org.apache.log4j.PatternLayout">
         <param name="ConversionPattern" value="%-5p %c{1} - %m%n"/>
       </layout>
     </appender>
   
     <root>        ​
       <!-- the new appender was used here -->​​
       <appender-ref ref="NewRelicFile" />
       <appender-ref ref="TypicalConsole" />
     </root>
   
   </log4j:configuration>

   Copiar

Oferecemos uma extensão Log4j 2.x para log em contexto com o agente Java. Para começar, revise o código e um exemplo de aplicativo no GitHub.

Para configurar o logs contextualizados para seu aplicativo Java com a extensão Log4j 2.x:

1. Certifique-se de ter o pacote de ligação Log4j 2.13.2 ou superior ou Logs4j 2 instalado e funcionando em seu aplicativo.

2. Certifique-se de ter o agente Java New Relic versão 5.6.0 ou superior instalado em seu aplicativo e de ter ativado o argumento JVM -javaagent.

3. Atualize a dependência do seu projeto para incluir a extensão Log4j 2.x conforme aplicável:

   Gradle: Adicione a seção destacada ao seu arquivo build.gradle :

   dependencies {
     implementation("com.newrelic.logging:log4j2:2.0")
   }

   Copiar

   Maven: Adicione a seção destacada ao seu arquivo pom.xml :

   <dependencies>
     <dependency>
       <groupId>com.newrelic.logging</groupId>
       <artifactId>log4j2</artifactId>
       <version>2.0</version>
     </dependency>
   </dependencies>

   Copiar

4. No arquivo XML de configuração de geração de registros, atualize o elemento <configuration> adicionando a seção destacada:

   <Configuration xmlns="http://logging.apache.org/log4j/2.0/config"
         packages="com.newrelic.logging.log4j2"
   >

   Copiar

   Se você estiver usando um arquivo de propriedades, adicione packages=com.newrelic.logging.log4j2.

5. Adicione <NewRelicLayout/> para usar um elemento NewRelicLayout em um dos anexadores. Por exemplo:

   <File name="MyFile" fileName="logs/app-log-file.log">
     <NewRelicLayout/>
   </File>

   Copiar

   Se você estiver usando um arquivo de propriedades, altere apenas layout.type:

   appender.console.type = Console
   appender.console.name = STDOUT
   appender.console.layout.type = NewRelicLayout

   Copiar

6. Se você modificou apenas um anexador existente, pule esta etapa. Se você adicionou um novo anexador, adicione <AppenderRef/> em <Root> para usar este anexador. Use o atributo ref para se referir ao anexador name que você criou na etapa anterior. Por exemplo:

   <Root level="info">
     <AppenderRef ref="MyFile"/>
   </Root>

   Copiar

   Se você estiver usando um arquivo de propriedades e adicionou um novo anexador, adicione:

   rootLogger.level = info
   rootLogger.appenderRef.stdout.ref = STDOUT

   Copiar

Oferecemos uma extensão Logback para logs contextualizados com o agente Java. Para começar, revise o código e um exemplo de aplicativo no GitHub.

Para configurar o logs contextualizados para seu aplicativo Java com Logback:

1. Certifique-se de ter o Logback versão 1.2.0 ou superior e o agente Java New Relic versão 5.6.0 ou superior instalado e funcionando em seu aplicativo.

2. Certifique-se de ter o agente Java New Relic versão 5.6.0 ou superior instalado em seu aplicativo e de ter ativado o argumento JVM -javaagent.

3. Atualize a dependência do seu projeto para incluir a extensão Logback conforme aplicável:

   Gradle: Adicione a seção destacada ao seu arquivo build.gradle :

   dependencies {
     implementation("com.newrelic.logging:logback:2.0")
   }

   Copiar

   Maven: Adicione a seção destacada ao seu arquivo pom.xml :

   <dependencies>
     <dependency>
       <groupId>com.newrelic.logging</groupId>
       <artifactId>logback</artifactId>
       <version>2.0</version>
     </dependency>
   </dependencies>

   Copiar

4. Atualize sua configuração de geração de registros xml para substituir qualquer elemento <encoder> existente.

   Se você estiver efetuando login no console (stdout/stderr), procure por ConsoleAppender e substitua:

   <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
     <encoder class="com.newrelic.logging.logback.NewRelicEncoder"/>
   </appender>

   Copiar

   Se você estiver registrando em um arquivo, procure FileAppender e substitua <encoder>:

   <appender name="LOG_FILE" class="ch.qos.logback.core.FileAppender">
     <file>logs/app-log-file.log</file>
     <encoder class="com.newrelic.logging.logback.NewRelicEncoder"/>
   </appender>

   Copiar

5. Atualize sua configuração de geração de registros xml com o NewRelicAsyncAppender. Para garantir que NewRelicAsyncAppender envolva todos os anexadores que irão direcionar os logs do New Relic, adicione a seção a seguir. Altere "LOG_FILE" para o nome do anexador que você atualizou na etapa anterior.

   <appender name="ASYNC" class="com.newrelic.logging.logback.NewRelicAsyncAppender">
     <appender-ref ref="LOG_FILE" />
   </appender>

   Copiar

6. Certifique-se de que NewRelicAsyncAppender seja o primeiro anexador usado em seu agente. Substitua os anexadores do seu agente raiz pelo anexador ASYNC criado na etapa anterior. Em seguida, liste quaisquer outros anexadores após NewRelicAsyncAppender na lista <root>.

   <root>
     <appender-ref ref="ASYNC" />
   </root>

   Copiar

   Aqui estão exemplos de um arquivo de registro .xml atualizado para a extensão Logback. Você também pode ver um exemplo prático no GitHub.

   Single console appender example

   Exemplo de arquivo de configuração após adicionar as informações da extensão de registro:

   <configuration>
     <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
   
       <!-- changed the encoder -->
       <encoder class="com.newrelic.logging.logback.NewRelicEncoder"/>
   
     </appender>
   
     <!-- added the ASYNC appender -->
     <appender name="ASYNC" class="com.newrelic.logging.logback.NewRelicAsyncAppender">
       <appender-ref ref="STDOUT" />
     </appender>
   
     <root level="debug">
   
       <!-- changed the root logger -->
       <appender-ref ref="ASYNC" />
   
     </root>
   </configuration>

   Copiar

   Two console appenders example

   Este exemplo envia o log do New Relic para um arquivo, mas ainda envia o log padrão para o console:

   <configuration>
     <appender name="FILE" class="ch.qos.logback.core.FileAppender">
       <file>myApp.log</file>
       <!-- encoder changed -->
       <encoder class="com.newrelic.logging.logback.NewRelicEncoder"/>
     </appender>
   
     <!-- this appender does normal console logging -->
     <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
       <encoder>
         <pattern>%msg%n</pattern>
       </encoder>
     </appender>
   
     <!-- The required New Relic ASYNC appender wraps the FILE appender -->
     <appender name="ASYNC" class="com.newrelic.logging.logback.NewRelicAsyncAppender">
       <appender-ref ref="FILE" />
     </appender>
   
     <root level="debug">
       <!-- ASYNC is one of the main appenders -->
       <appender-ref ref="ASYNC" />
   
       <!-- Send every message to normal console logging, as well. -->
       <appender-ref ref="STDOUT" />
     </root>
   </configuration>

   Copiar

Oferecemos extensões para versões atuais do Spring e Spring Boot. Se você já conhece a biblioteca de log, pode pular diretamente para essa documentação:

• java.util.logging

• log4j 1

• log4j 2

• logback

  As extensões suportam configuração padrão apenas no Spring Boot 2.0 e superior.

  With Spring Boot:

  Aqui estão algumas dicas para determinar qual biblioteca de registro você possui:

• Se você tem spring-boot-starter-log4j2 na sua dependência, você está usando log4j 2.x. Consulte a documentação do Spring Boot log4j 2.x para configuração básica e a extensão New Relic log4j 2 para personalizar sua configuração.

• Se você estiver usando o Spring Boot, mas não o starter-log4j2, estará usando logback por padrão. Consulte a documentação de logback do Spring Boot para configuração básica e a extensão de logback do New Relic para personalizar sua configuração.

  With Spring (but not Spring Boot):

  Primavera 5 ou superior:

  Spring implementa uma ponte para outra biblioteca de log que os encontrará automaticamente. No entanto, essas bibliotecas individuais devem ser configuradas e incluídas explicitamente na dependência do seu projeto.

  Para identificar sua dependência de log, consulte sua árvore de dependência Gradle, Maven ou outra ferramenta de construção. Em seguida, siga os procedimentos para configurar o logs contextualizados para seu aplicativo Java com essa extensão.

  Primavera 4 ou inferior:

  Spring versão 4 e inferior usa Apache Commons Logging para sua ponte. Consulte a documentação do Spring para obter informações sobre como configurar sua ponte.