Tracing and logging

GitBucket uses slf4j and logback as implementation; thus any logback configuration can apply to GitBucket logging system.

GitBucket provides its own logback.xml (still true in 4.0) preventing external configuration via providing this exact same file. Logback official configuration page explain how to override the logging settings:

• provide a file logback.groovy at the root of the classpath
• provide a file logback-test.xml at the root of the classpath
• provide a file logback.xml at the root of the classpath (not usable since GitBucket provides its own)
• provide an implementation of com.qos.logback.classic.spi.Configurator via ServiceLoader

Another possibility, as explained in the documentation, is to provide the System property logback.configurationFile when launching the application and fill this property with the full path to configuration file.

Using this approach, you could for example launch GitBucket using:

java -Dlogback.configurationFile=/opt/gitbucket/config/logback-settings.xml -jar gitbucket.war

In the above example, a logback configuration stored inside /opt/gitbucket/config would be used, such a file could look like to:

<configuration debug="true" scan="true" scanPeriod="60 seconds">
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender"> 
    <!-- encoders are  by default assigned the type
         ch.qos.logback.classic.encoder.PatternLayoutEncoder -->
        <filter class="ch.qos.logback.classic.filter.LevelFilter">
            <level>INFO</level>
            <onMatch>ACCEPT</onMatch>
            <onMismatch>DENY</onMismatch>
        </filter>
        <encoder>
            <pattern>ROLLING %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <appender name="ROLLING" class="ch.qos.logback.core.rolling.RollingFileAppender"> 
    <!-- encoders are  by default assigned the type
         ch.qos.logback.classic.encoder.PatternLayoutEncoder -->
        <file>/opt/gitbucket/log/gitbucket.log</file>
        <append>false</append>
        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!-- rollover daily -->
            <fileNamePattern>gitbucket-%d{yyyy-MM-dd}.%i.txt</fileNamePattern>
            <timeBasedFileNamingAndTriggeringPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedFNATP">
                <!-- or whenever the file size reaches 100MB -->
                <maxFileSize>25MB</maxFileSize>
            </timeBasedFileNamingAndTriggeringPolicy>
        </rollingPolicy>
        <encoder>
            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
        </encoder>
    </appender>

    <root level="DEBUG">
        <appender-ref ref="STDOUT"/>
        <appender-ref ref="ROLLING"/>
    </root>
</configuration>

The above configuration:

• activates DEBUG traces for all GitBucket code
• outputs the traces on 2 appenders:
  • STDOUT: a console appender printing on stdout by default
  • ROLLING: a file based appender tracing into files stored under /opt/gitbucket/log/
• only INFO (and above severity) logs will be printed on the console due to the filter on the INFO level
• files in /opt/gitbucket/log/ will roll daily or each time the file is over 25M

This configuration is just provided as an example, please follow logback documentation to setup your own log settings.

for Tomcat8/tomcat9

note:

{gitbucket_dir} is the dir that gitbucket is using for it's own files and configurations.

for example it can be /opt/gitbucket/ or /home/tomcat8/.gitbucket or /home/tomcat9/.gitbucket

• edit file /var/lib/tomcat8/conf/catalina.properties for tomcat 8
• edit file /var/lib/tomcat9/conf/catalina.properties for tomcat 9
• put at the end: of the file, in a new line: logback.configurationFile={gitbucket_dir}/logback.xml
• on {gitbucket_dir} create the file logback.xml with the contents above, in the example, and don't forget to give the correct permissions
  • on tomcat8 chown tomcat8:tomcat8 {gitbucket_dir}/logback.xml
  • on tomcat9 chown tomcat9:tomcat9 {gitbucket_dir}/logback.xml
• change the contents, specially the line with <file>/opt/gitbucket/log/gitbucket.log</file> to <file>{gitbucket_dir}/log/gitbucket.log</file>
• create the folder log and give permissions:
  • tomcat8 mkdir -p {gitbucket_dir}/log/ && chown tomcat8:tomcat8 {gitbucket_dir}/log/ -R
    • restart the service with service tomcat8 restart or with systemctl restart tomcat8
  • tomcat9 mkdir -p {gitbucket_dir}/log/ && chown tomcat9:tomcat9 {gitbucket_dir}/log/ -R
    • restart the service with service tomcat9 restart or with systemctl restart tomcat9