Difference between revisions of "Debugging"

From wiki.vg
Jump to navigation Jump to search
(Partial rewrite (will expand later))
(Add launcher debug config; make Options section useful)
Line 7: Line 7:
 
{{Warning|If the configuration specified with <code>-Dlog4j.configurationFile</code> cannot be found, the default one will silently be used instead.}}
 
{{Warning|If the configuration specified with <code>-Dlog4j.configurationFile</code> cannot be found, the default one will silently be used instead.}}
  
You can get the default configuration for the game by extracting <code>log4j2.xml</code> from the jar you wish to work with.
+
You can get the default configuration for the game by extracting <code>log4j2.xml</code> from the jar you wish to work with.
  
 
== Options ==
 
== Options ==
  
The main settings that are worth modifying is the value of <code>level</code> in <code>Root</code>, and the list of <code>filter</code>s.  (SOUNDS, NETWORK, NETWORK_PACKETS, PACKET_SENT, PACKET_RECEIVED)
+
There are only a few options that have useful behaviors within the log4j configuration.
 +
 
 +
The main one is <code>level</code> in <code><nowiki><Root></nowiki></code>.  Normally, this is set to <code>info</code>, but it accepts <code>trace</code>, <code>debug</code>, <code>info</code>, <code>warn</code>, <code>error</code>, <code>all</code>, and <code>off</code>.  The lowest level that is actually used by Minecraft is <code>debug</code>, so that one should be used for maximum additional information.
 +
 
 +
The other major option is the list of <code><nowiki><filter></nowiki></code>s.  By default, the game filters out information regarding packets with a <code><nowiki><filter></nowiki></code> that rejects all log messages marked with <code>NETWORK_PACKETS</code>.  You can instead make it so that the filter only accepts <code>NETWORK_PACKETS</code> and rejects everything else, or alternatively you can remove the <code><nowiki><filter></nowiki></code> entirely so that all messages are displayed.  Beyond just <code>NETWORK_PACKETS</code>, there are a few other log markers: <code>SOUNDS</code>, <code>NETWORK</code>, <code>PACKET_SENT</code>, and <code>PACKET_RECEIVED</code>.  <code>NETWORK</code> and <code>NETWORK_PACKETS</code> behave identically; <code>PACKET_SENT</code> and <code>PACKET_RECEIVED</code> can be used to show only one set of the packets; and <code>SOUNDS</code> can be used to emit information about when a sound channel starts and stops (mostly only useful when diagnosing issues where a sound seems to be playing twice).
 +
 
 +
One other note: by default, log4j overwrites old logs if there are more than 7 for a day (see [https://bugs.mojang.com/browse/MC-100524 MC-100524]).  You can disable this "feature" by adding a <code><nowiki><DefaultRolloverStrategy max="1000"/></nowiki></code> to the <code><nowiki><RollingRandomAccessFile></nowiki></code>, which makes the maximum 1000 files in a day (which is much less likely to be hit - 1000 is used over something larger because at larger numbers there starts to be a performance hit).
  
 
== Sample configs ==
 
== Sample configs ==
Line 83: Line 89:
 
                 <OnStartupTriggeringPolicy />
 
                 <OnStartupTriggeringPolicy />
 
             </Policies>
 
             </Policies>
 +
            <DefaultRolloverStrategy max="1000"/>
 
         </RollingRandomAccessFile>
 
         </RollingRandomAccessFile>
 
     </Appenders>
 
     </Appenders>
Line 118: Line 125:
 
                 <OnStartupTriggeringPolicy />
 
                 <OnStartupTriggeringPolicy />
 
             </Policies>
 
             </Policies>
 +
            <DefaultRolloverStrategy max="1000"/>
 
         </RollingRandomAccessFile>
 
         </RollingRandomAccessFile>
 
     </Appenders>
 
     </Appenders>
Line 129: Line 137:
 
</Configuration>
 
</Configuration>
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
</div>
 +
 +
=== Launcher session information ===
 +
 +
''Applies to: Launcher.jar''
 +
 +
By enabling debug launching on the launcher jar, you can view connections to the [[Mojang API]] - helpful if you want to see a sample connection to each endpoint for your own account.
 +
 +
Note that this configuration ''may'' not work if you invoke the normal launcher EXE/JAR - instead, use it on the <code>launcher.jar</code> located in <code>%appdata%\.minecraft</code>.
 +
 +
<div class="mw-collapsible mw-collapsed" style="border: 1px solid #aaa;">
 +
Config:
 +
<syntaxhighlight lang="xml" class="mw-collapsible-content">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<Configuration status="WARN" packages="com.mojang">
 +
    <Appenders>
 +
        <Console name="SysOut" target="SYSTEM_OUT">
 +
            <PatternLayout pattern="[%d{HH:mm:ss} %level]: %msg%n" />
 +
        </Console>
 +
        <Queue name="DevelopmentConsole">
 +
            <PatternLayout pattern="[%d{HH:mm:ss} %level]: %msg%n" />
 +
        </Queue>
 +
        <Async name="Async">
 +
            <AppenderRef ref="SysOut"/>
 +
            <AppenderRef ref="DevelopmentConsole"/>
 +
        </Async>
 +
    </Appenders>
 +
    <Loggers>
 +
        <Root level="debug">
 +
            <AppenderRef ref="Async"/>
 +
        </Root>
 +
    </Loggers>
 +
</Configuration>
 +
 
</div>
 
</div>

Revision as of 15:35, 2 November 2016

The Notchian client and server (and additionally the launcher) can generate additional log information that what is normally displayed, some of which is extremely helpful for debugging. This can be done by specifying a custom Log4j configuration by supplying a -Dlog4j.configurationFile=fullpathtoconfigfile.xml argument to the game:

Warning.png If the configuration specified with -Dlog4j.configurationFile cannot be found, the default one will silently be used instead.

You can get the default configuration for the game by extracting log4j2.xml from the jar you wish to work with.

Options

There are only a few options that have useful behaviors within the log4j configuration.

The main one is level in <Root>. Normally, this is set to info, but it accepts trace, debug, info, warn, error, all, and off. The lowest level that is actually used by Minecraft is debug, so that one should be used for maximum additional information.

The other major option is the list of <filter>s. By default, the game filters out information regarding packets with a <filter> that rejects all log messages marked with NETWORK_PACKETS. You can instead make it so that the filter only accepts NETWORK_PACKETS and rejects everything else, or alternatively you can remove the <filter> entirely so that all messages are displayed. Beyond just NETWORK_PACKETS, there are a few other log markers: SOUNDS, NETWORK, PACKET_SENT, and PACKET_RECEIVED. NETWORK and NETWORK_PACKETS behave identically; PACKET_SENT and PACKET_RECEIVED can be used to show only one set of the packets; and SOUNDS can be used to emit information about when a sound channel starts and stops (mostly only useful when diagnosing issues where a sound seems to be playing twice).

One other note: by default, log4j overwrites old logs if there are more than 7 for a day (see MC-100524). You can disable this "feature" by adding a <DefaultRolloverStrategy max="1000"/> to the <RollingRandomAccessFile>, which makes the maximum 1000 files in a day (which is much less likely to be hit - 1000 is used over something larger because at larger numbers there starts to be a performance hit).

Sample configs

Network packets only

Applies to: vanilla client and server

Produces logs of all packets sent to and from the server/client, and nothing else (this also disables logging of normal content, including chat). Unfortunately, since the Netty rewrite (Minecraft 1.7) only packet IDs and classes are logged, and not their contents; however, this information may still be helpful.

Warning.png Packet IDs are shown in decimal in logs; they are not in hexadecimal.

Config:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="com.mojang.util">
    <Appenders>
        <Console name="SysOut" target="SYSTEM_OUT">
            <PatternLayout pattern="[%d{HH:mm:ss}] [%t/%level]: %msg%n" />
        </Console>
        <Queue name="ServerGuiConsole">
            <PatternLayout pattern="[%d{HH:mm:ss} %level]: %msg%n" />
        </Queue>
        <RollingRandomAccessFile name="File" fileName="logs/latest.log" filePattern="logs/%d{yyyy-MM-dd}-%i.log.gz">
            <PatternLayout pattern="[%d{HH:mm:ss}] [%t/%level]: %msg%n" />
            <Policies>
                <TimeBasedTriggeringPolicy />
                <OnStartupTriggeringPolicy />
            </Policies>
            <DefaultRolloverStrategy max="1000"/>
        </RollingRandomAccessFile>
    </Appenders>
    <Loggers>
        <Root level="debug">
            <filters>
                <MarkerFilter marker="NETWORK_PACKETS" onMatch="ACCEPT" onMismatch="DENY" />
            </filters>
            <AppenderRef ref="SysOut"/>
            <AppenderRef ref="File"/>
            <AppenderRef ref="ServerGuiConsole"/>
        </Root>
    </Loggers> 
</Configuration>

All debug information

Applies to: vanilla client and server

You can log even more information if you want. This will print normal log messages (such as chat), but also network packets, sounds starting/stopping playing (client only), some authentication requests, and other miscellaneous information.

Config:

<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="com.mojang.util">
    <Appenders>
        <Console name="SysOut" target="SYSTEM_OUT">
            <PatternLayout pattern="[%d{HH:mm:ss}] [%t/%level]: %msg%n" />
        </Console>
        <Queue name="ServerGuiConsole">
            <PatternLayout pattern="[%d{HH:mm:ss} %level]: %msg%n" />
        </Queue>
        <RollingRandomAccessFile name="File" fileName="logs/latest.log" filePattern="logs/%d{yyyy-MM-dd}-%i.log.gz">
            <PatternLayout pattern="[%d{HH:mm:ss}] [%t/%level]: %msg%n" />
            <Policies>
                <TimeBasedTriggeringPolicy />
                <OnStartupTriggeringPolicy />
            </Policies>
            <DefaultRolloverStrategy max="1000"/>
        </RollingRandomAccessFile>
    </Appenders>
    <Loggers>
        <Root level="debug">
            <AppenderRef ref="SysOut"/>
            <AppenderRef ref="File"/>
            <AppenderRef ref="ServerGuiConsole"/>
        </Root>
    </Loggers>
</Configuration>

All debug information on CraftBukkit/Spigot

Applies to: CraftBukkit servers and servers that derive from CraftBukkit

Because CraftBukkit uses slightly different console output (and has no server GUI), the configuration needs to be slightly tweaked to display correctly. However, doing this will also display the remapped packet class names.

Config:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="net.minecraft,com.mojang">
    <Appenders>
        <Console name="WINDOWS_COMPAT" target="SYSTEM_OUT"></Console>
        <Queue name="TerminalConsole">
            <PatternLayout pattern="[%d{HH:mm:ss} %level]: %msg%n" />
        </Queue>
        <RollingRandomAccessFile name="File" fileName="logs/latest.log" filePattern="logs/%d{yyyy-MM-dd}-%i.log.gz">
            <PatternLayout pattern="[%d{HH:mm:ss}] [%t/%level]: %msg%n" />
            <Policies>
                <TimeBasedTriggeringPolicy />
                <OnStartupTriggeringPolicy />
            </Policies>
            <DefaultRolloverStrategy max="1000"/>
        </RollingRandomAccessFile>
    </Appenders>
    <Loggers>
        <Root level="debug">
            <AppenderRef ref="WINDOWS_COMPAT"/>
            <AppenderRef ref="File"/>
            <AppenderRef ref="TerminalConsole"/>
        </Root>
    </Loggers>
</Configuration>

Launcher session information

Applies to: Launcher.jar

By enabling debug launching on the launcher jar, you can view connections to the Mojang API - helpful if you want to see a sample connection to each endpoint for your own account.

Note that this configuration may not work if you invoke the normal launcher EXE/JAR - instead, use it on the launcher.jar located in %appdata%\.minecraft.

Config: <syntaxhighlight lang="xml" class="mw-collapsible-content"> <?xml version="1.0" encoding="UTF-8"?> <Configuration status="WARN" packages="com.mojang">

   <Appenders>
       <Console name="SysOut" target="SYSTEM_OUT">
           <PatternLayout pattern="[%d{HH:mm:ss} %level]: %msg%n" />
       </Console>
       <Queue name="DevelopmentConsole">
           <PatternLayout pattern="[%d{HH:mm:ss} %level]: %msg%n" />
       </Queue>
       <Async name="Async">
           <AppenderRef ref="SysOut"/>
           <AppenderRef ref="DevelopmentConsole"/>
       </Async>
   </Appenders>
   <Loggers>
       <Root level="debug">
           <AppenderRef ref="Async"/>
       </Root>
   </Loggers>

</Configuration>