How do I create a logger in Jenkins for troubleshooting and diagnostic information?

Article ID:204880580
3 minute readKnowledge base

Issue

  • How do I create a logger?

  • How can I get more detailed diagnostic information?

Resolution

In this article, the two possibilities to define a custom log recorder are explained. Both options are on sync meaning that if a custom logger is created via UI, the $JENKINS_HOME/log/kb-article.xml will be created by Jenkins and vice versa.

It is recommended that you remove any log recorders you have added once they are no longer needed. Depending on how much data they are capturing, they can have a significant impact on Jenkins’s performance.

To view logs from a specific action exposed by Jenkins, or a plugin not typically monitored, you can add a logger under Manage Jenkins -> System Log -> Add new log recorder

To add a new logger you will be asked to provide it a name and choose a function to monitor. You’ll also have the ability to change the verbosity.

To find what loggers are available you can simply start typing a keyword. For instance, typing 'git' will provide you with a list of loggers that may be relevant. You can also look at the source code for Jenkins and its plugins to identify class names which you can get logs from.

After saving the log recorder and refresh the page, logs will only be displayed there (while the page is open). If you need to manipulate the Jenkins UI in order to trigger the logging you want to see, you would need to do that in a separate tab or window while continuing to view the log recorder page.

logger.png

Adding a logger from the filesystem (in case the UI is not accessible)

Pre-requisite: Support Core plugin. is installed. This plugin will write custom log recorders into $JENKINS_HOME/logs/custom/ on the Jenkins controller’s filesystem. You can then tail the relevant file to see updates to it. (Jenkins 2.114 introduced a system property which allows you to specify a different location to store Jenkins logs. Support Core plugin 2.47 supports this, so you may need to check if that property has been set if you are not seeing logs in the default location.)

$JENKINS_HOME (root)
+- log
|   +- kb-article.xml         # Custom log recorder definition
+- logs
   +- custom
      +- kb-article.log       # Custom log recorder file

You can add a logger by creating a new xml file under ${JENKINS_HOME}/log.

The folder is named log, not logs.
The UI logger name (e.g. <name>kb-article</name>) and the name of the file must keep consistency (e.g. kb-article.xml) because it is the way the System log recorder maps the custom logger under $JENKINS_HOME/logs/custom.

Here is an example creating a logger called kb-article for the com.cloudbees package on all kind of levels:

cat >kb-article.xml <<"EOF"
  <?xml version='1.1' encoding='UTF-8'?>
    <log>
      <name>kb-article</name>
      <targets>
        <target>
          <name>com.cloudbees</name>
          <level>-2147483648</level> <!--all -->
        </target>
        <target>
          <name>com.cloudbees</name>
          <level>300</level> <!--finest -->
        </target>
        <target>
          <name>com.cloudbees</name>
          <level>400</level> <!--finer -->
        </target>
        <target>
          <name>com.cloudbees</name>
          <level>500</level> <!--fine -->
        </target>
        <target>
          <name>com.cloudbees</name>
          <level>700</level> <!--config -->
        </target>
        <target>
          <name>com.cloudbees</name>
          <level>800</level> <!--info -->
        </target>
        <target>
          <name>com.cloudbees</name>
          <level>900</level> <!--warning -->
        </target>
        <target>
          <name>com.cloudbees</name>
          <level>1000</level> <!--severe -->
        </target>
        <target>
          <name>com.cloudbees</name>
          <level>2147483647</level> <!--off -->
        </target>
      </targets>
    </log>
EOF

As another example, here is how to add the needed loggers to debug SAML issues on CloudBees CI:

kubectl exec -i ${CONTROLLER_POD_NAME} -n ${CLOUDBEES_CI_NAMESPACE} -- bash -c "mkdir -p /var/jenkins_home/log && cat >/var/jenkins_home/log/kb-article.xml <<EOF
<?xml version='1.1' encoding='UTF-8'?>
<log>
  <name>kb-article</name>
  <targets>
    <target>
      <name>org.jenkinsci.plugins.saml</name>
      <level>300</level>
    </target>
    <target>
      <name>org.pac4j</name>
      <level>500</level>
    </target>
  </targets>
</log>
EOF"

Tested product/plugin versions

The latest update of this article has been tested with