Monitoring

Monitoring is a process that detects, diagnoses, remedies and reports an application’s performance and availability to ensure that it meets user expectations. Magnolia provides built-in tools for logging and debugging application behavior. It also supports Java Management Extensions (JMX), a Java technology for managing and monitoring. These mechanisms provide developers, administrators and especially the support team detailed context for application failures.

Log4j 2

Magnolia uses Apache Log4j 2, a Java-based logging utility. It logs events in Magnolia core code as well as any modules that support logging. Logging is configured in three places:

Type Location Description

log4j2.xml

/WEB-INF/config/default

A permanent configuration which persists restarts. In the XML file you can also choose whether you wish to log a Class or package. Any changes made to the file will require a restart of the server.

Log Tools app

Tools menu

A transient configuration which resets after a restart. In the Log Tools app you can choose whether you wish to log a Class or package. Any changes made in the app are active immediately. This tool is useful for ad-hoc debugging of production issues since you don’t need to restart Magnolia to turn it on.

Audit Logging

/server/auditLogging

Audit logging means tracking user activity in the system such as who signed in and what they did. Here you select the actions you want to audit such as login, create, publish and so on.

Debugging your configuration

It is possible to debug the log4j 2 configuration itself. Add the status attribute to the Configuration element of the log4j2.xml configuration file.

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="debug">
...
...

For more information on this topic see Log4j 2 Status Messages.

Loggers

Loggers define what data is logged and how much detail is provided. Think of this as a configuration for the classes and packages you want to log.

Here’s an example from the default log4j2.xml.

<!-- Publishing - additivity is true so logs also go to sub-categories' appenders -->
<Logger name="info.magnolia.publishing" level="INFO" additivity="true">
    <AppenderRef ref="log-publishing"/>
</Logger>

Apps configured in the new App Launcher layout will cause entries to appear in the log. To keep the log tidy, we recommend adjusting your App Launcher layout configuration and removing any apps you don’t use.

Class or package

The choice between logging a single class or the whole package depends on whether the issue is limited to a single class. In the example above we log everything within the package info.magnolia.publishing.

To summarize:

  • To log a specific class, use the fully qualified class name for the XML name attribute in the Logger entry.

  • To log a whole package, use the fully qualified package name for the XML name attribute in the Logger entry.

Level

Magnolia uses the standard log4j logging levels.

Level Description

OFF

The highest possible rank and is intended to turn off logging.

FATAL

Severe errors that cause premature termination. Visible in console.

ERROR

Other runtime errors or unexpected conditions. Visible in console.

WARN

Use of deprecated APIs, poor use of API, almost errors, other runtime situations that are undesirable or unexpected, but not necessarily wrong. Visible in console.

INFO

Interesting runtime events (startup/shutdown). Visible in console, so be conservative and keep to a minimum.

DEBUG

Detailed information on the flow through the system. Written to logs only.

TRACE

More detailed information. Written to logs only.

Pattern Layout

Log4j2’s Pattern Layout is a customizable log message formatter that uses conversion patterns to generate structured log outputs.

The log message is encoded to address CWE 117 (Improper Output Neutralization for Logs), ensuring user-supplied data is properly sanitized so as to prevent log injection attacks.

WEBAPP/src/main/webapp/WEB-INF/config/default/log4j2.xml
<PatternLayout pattern="%d %-5p %-50.50c: %encode{%m}{CRLF}%n"/> (1)
1 Where the pattern matches:
  • %d = the date.

  • %-5p = the priority (p) left justified by 5 characters.

  • %-50.50c: = the name of the logger that published the logging event.

  • %encode{%m}{CRLF}%n = encodes the user message preventing the CRLF characters from the stream.

Appenders

Appenders define where the output is directed. The following appenders are configured by default in log4j2.xml. They write messages to the console and to various log files.

Appender Writes to Notes

console

Console

Default output for DEBUG messages

log-debug

magnolia-debug.log

Default output for DEBUG messages.

log-error

magnolia-error.log

Default output for ERROR messages.

log-publishing

magnolia-publishing.log

Content publishing.

log-bootstrap

bootstrap.log

Bootstrap process.

log-access

magnolia-access.log

System access.

log-audit

magnolia-audit.log

See Audit.

log-form

magnolia-form.log

mail

Sends mail.

Disabled by default.

You can enable it by uncommenting the mail appender XML section commented out by default in this file in your installation: war/WEB-INF/config/default/log4j2.xml.

See the shipped version of the file also here.

Example: The log-publication appender is used to log events related to content publishing.

<RollingFile name="sync-log-publishing"
             fileName="${magnolia.logs.dir}/magnolia-publishing.log"
             filePattern="${magnolia.logs.dir}/magnolia-publishing-%i.log"
             append="true">
  <PatternLayout pattern="%-5p %c %d{dd.MM.yyyy HH:mm:ss} -- %encode{%m}{CRLF}%n"/>
  <ThresholdFilter level="ERROR"/>
  <Policies>
    <SizeBasedTriggeringPolicy size="1MB"/>
  </Policies>
  <DefaultRolloverStrategy max="5"/>
</RollingFile>
<Async name="log-publishing">
  <AppenderRef ref="sync-log-publishing"/>
</Async>

It is actually two appenders: log-publishing appender uses the Async class to queue up the messages while the referenced sync-log-publishing appender does the actually writing of the messages to the magnolia-publishing.log file.

All appenders that write to a log file use the RollingFile class. Rolling means that the system takes a backup of the log file when its size reaches a limit set in the SizeBasedTriggeringPolicy

(1 MB by default). The old file is date-stamped and a new file is started in the same directory.

Example: Debugging content publication

This example shows how to log more detail about content publication. It is useful when publication fails and the default INFO messages do not provide enough information to pinpoint the root cause.

Add the Logger to log4j2.xml if not already there:

<!-- Publishing - additivity is true so logs also go to sub-categories' appenders -->
<Logger name="info.magnolia.publishing" level="INFO" additivity="true">
    <AppenderRef ref="log-publishing"/>
</Logger>

Each category references the log-publishing appender which sends output to the magnolia-publication.log file. Since additivity is true, output is also sent to ancestor appenders, in this case the console.

Priority is set at INFO level by default. If more information is needed, this is the detail that needs to be changed.

To change the level to DEBUG:

  1. Stop the Magnolia instance.

  2. Change priority in the three categories to DEBUG.

  3. Save the file.

  4. Start Magnolia.

To test the new configuration, publish some content and view the logged DEBUG messages in the magnolia-publication.log.

Note that by default there is a temp folder called tmp configured in magnolia.properties in the actual webapp. This folder contains various exchange_*.xml.gz files that are stored when debugging is enabled for publication. The location of the files is specified by the magnolia.upload.tmpdir.

Capturing request and response headers

Request and response headers are information passed between a browser and a web server. Headers consist of fields that define the operating parameters of the HTTP transaction. Capturing the headers tells you what records are passed and provides a clue for troubleshooting.

The request header contains details of what the browser wants and what it will accept back from the server. It also contains the type, version and capabilities of the browser so that the server returns compatible data.

Example: Request header

User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/534.50 (KHTML, like Gecko) Version/5.1 Safari/534.50
Accept: text/html,application/xhtml-xml,application/xml;q=0.9,*/*;q=0.8
Referer: http://demopublic.magnolia-cms.com/demo-project.html
Cache-Control: max-age=0

The response header contains the date, size and type of file that the server is sending back to the client and data about the server itself. The header is attached to the files being sent back to the client.

Example: Response header

Date: Thu, 13 Oct 2011 11:09:41 GMT
Content-Encoding: gzip
Connection: Keep-Alive
Content-Length: 3229
Pragma: no-cache
X-Magnolia-Registration: Registered
Last-Modified: Thu, 13 Oct 2011 11:01:26 GMT
Server: Apache/2.2.14 (Ubuntu)
Vary: Accept-Encoding
Content-Type: text/html;charset=UTF-8
Cache-Control: no-cache, no-store, must-revalidate, max-age=0
Keep-Alive: timeout=15, max=100
Expires: Thu, 01 Jan 1970 00:00:00 GMT

Browser extensions

To capture the headers, you can use a browser extension or plugin that displays headers for the currently open page. A plugin’s advantage over a Websites is that you can also use it for sites that only exist in your local environment or intranet.

To view headers in Developer Tools:

  1. Open Developer Tools.

  2. Go to Network.

  3. Reload the page.

  4. Select the page in the list.

  5. Go to Headers tab.

Command line tools

Any Unix-like system likely has these command line tools already installed.

  • cURL
    $ curl --head <url>

  • wget
    $ wget --server-response <url>

Applications

Rich client applications:

Websites

A header-sniffing website can report headers for a site that resides on the public Internet. These tools do not work for a site that exists only in your local environment.

Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the Performance tuning guide docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules