PaperMC / PaperMC/docs

Add logging documentation

Open
#580 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

dev guide good first issue
Dominant language
MDX
Stars
73
Forks
280
Avg merge
20h 52m
Merged PRs (30d)
4

Description

Three main things should be documented around logging:

  1. What are the differences between loggers (System.out (not a logger!!), java.util.Logger, slf4j logger, component logger)
  2. Correct logging usage in Paper plugins (make sure to say that logging more is better than less! Use the correct logging levels, keep debug logging in, and, again, do not use System.out!).
  3. Adding a custom log4j2.xml for your plugin for more robust logging of your plugin-internal logging. A.e. putting logs from your own plugin into /plugins/<pluginname>/logs to easier log sharing for plugin specific issues.

Should also link to the log4j2 documentation: https://logging.apache.org/log4j/2.x/

Example log4j2.xml
<?xml version="1.0" encoding="UTF-8" ?>
<Configuration>
    <Appenders>
        <RollingRandomAccessFile name="YourPlugin" 
                                 fileName="plugins/YourPlugin/logs/latest.log"
                                 filePattern="plugins/YourPlugin/logs/%d{yyyy-MM-dd}-%i.log.gz">
            <PatternLayout>
                <LoggerNamePatternSelector defaultPattern="[%d{HH:mm:ss}] [%t/%level]: [%logger] %stripAnsi{%msg}%n%xEx{full}" />
            </PatternLayout>
            <Policies>
                <TimeBasedTriggeringPolicy/>
                <OnStartupTriggeringPolicy/>
            </Policies>
            <DefaultRolloverStrategy max="5"/>
        </RollingRandomAccessFile>
    </Appenders>
    <Loggers>
        <Root level="INFO"/>
        <Logger name="your.package.name" level="DEBUG" additivity="false">
            <AppenderRef ref="YourPluginFile"/>
        </Logger>
    </Loggers>
</Configuration>
Example: Registering the logger inside your plugin. (A nice use of the bootstrapper, too!)
// PluginBoostrap.java

public PluginBootstrap() {
    final URL configUrl = getClass().getResource("/log4j2.xml");
    if (configUrl != null) {
        Configurator.initialize("YourPlugin", configUrl.toExternalForm());
    }
    else {
        LOGGER.error("Failed to find log4j2.xml!");
    }
}

Furthermore, one should note on the usage of markers and how to add them to your log4j2.xml.
Reference documentation for marker filters: https://logging.apache.org/log4j/2.x/manual/filters.html.

<Logger name="your.package.name" level="DEBUG" additivity="false">
    <AppenderRef ref="YourPluginFile">
        <MarkerFilter marker="PluginMarker" onMatch="DENY" onMismatch="NEUTRAL"/>
    </AppenderRef>
</Logger>

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the documentation area for Paper plugins and use the issue's PluginBootstrap.java and log4j2.xml examples as the reference material. Document logger differences, recommended logging levels and markers, plugin-specific log files, and link the referenced Log4j documentation. Done means all three logging topics, both external links, and the examples are clearly covered.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.