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

Issue

  • How do I create a logger?
  • How can I get more detailed diagnostic information?

Environment

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.

Important: 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.

Adding a logger from the UI (recommended)

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 master’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 (note that is log not logs). Note: 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 Core:

kubectl exec -i ${MASTER_POD_NAME} -n ${CLOUDBEES_CORE_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.xml</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

Have more questions?

4 Comments

  • 0
    Avatar
    Sorin Sbarnea

    This doesn't tell anything about log files. As part of the debugging process we need to be able to save specialized logs like this to files. Where are these logs saved and that would be their filenames?

    It is essential to have lots that survive Jenkins restart.

  • 1
    Avatar
    Arnaud Héritier

    Hi Sorin,

      If you have the Support plugin installed, they'll be automatically stored under $JENKINS_HOME/logs/custom/

    Best regards

  • 1
    Avatar
    Chris Weiss

    Logs created by this function turn over quickly - Is there a way to increase the log size or (better yet) pipe the logs to an external logger?

  • 0
    Avatar
    Denys Digtiar

    Hi Chris,

    Jenkins wiki also provides a way to make logs available outside of the web UI. It should probably give you enough flexibility to achieve what you need.

Please sign in to leave a comment.