Logging in Aspire 2.0

Logging within Aspire is multi-featured:

  • The Aspire Application and components within the application can log messages to a number of different log writers:
    • UI
      • Components keep the last n messages in memory and can report these back via the status page
    • File
      • Components log at various levels to a component specific file with is rotated when it reaches a certain size, or daily
    • Console
      • Components log at various levels to the console
    • OSGI
      • Components log messages are sent to the OSGI loging service
  • The writers and the severity above which log messages are written can be configured at a system level via the settings.xml file
  • The writers for a specific component and the severity above which log messages are written can be configured via the component configuration, overriding the system wide settings.
  • The severity above which log messages are written for a specific component may be controlled via the component's debug interface
  • The severity above which log messages are written may be controlled on a system wide basis via the application's debug interface
  • The log may be rotated on demand while the component is running.
  • You may set the base directory for files from the file log writer by setting an environment variable
    • $ASPIRE_LOG_DIR

Log message severity

The Aspire application and components running inside it can log at four different severity levels:

  • DEBUG
  • INFO
  • WARN
  • ERROR

The severity of any given message will be set by the component developer, but the logging configuration will allow the system administrator to control what severity of message is logged and to where.

Log message severity filters

The Aspire application and components running inside it can filter log messages at five different levels:

  • NONE
    • No messages will be logged by this component
  • DEBUG
    • Debug messages and above will be logged by this component
  • INFO
    • Only information messages and above will be logged by this component
  • WARN
    • Only warning messages and above will be logged by this component
  • ERROR
    • Only error messages and above will be logged by this component

Log writers

There are four types of log writer:

  • UI
    • Components keep the last n messages in memory and can report these back via the status page
    • Default severity filter: INFO
  • Console
    • Components log at various levels to the console
    • Default severity filter: INFO
  • File
    • Components log at various levels to a component specific file with is rotated when it reaches a certain size, or daily
    • Default severity filter: INFO
  • OSGI
    • Components log messages are sent to the OSGI loging service
    • Default severity filter: NONE (ie no messages will be sent)

When you configure a writer (either in the settings.xml or for an individual component) you optionally specify a severity filter. If you don't specify the severity filter, the default (see above) will be used. Only log messages with a severity equal to or above the filter will be logged.

If you specify no log writers in the settings.xml file, Aspire will create a UI, CONSOLE and FILE writer for the application.

If you specify no log writers in the configuration of a component, the component will mirror the log writers used for the application.

UI writer

The UI writer is used to report the messages back to the administrator via the debug console status page. You may alter the number of messages kept at the UI by setting the keep attribute of the writer (default 1000). The default severity filter is INFO

 <log><writer type="UI" keep="1000" severity="INFO"/></log>

Console writer

The console writer is used to report the messages back to the administrator via the console. The default severity filter is INFO

 <log><writer type="CONSOLE" severity="INFO"/></log>

File writer

The file writer is used to log message to files. The file will be rotated when it reaches a certain size (default 10Mb) or daily. You may alter the maximum size of the file by setting the maxSize attribute or the filename used by setting the filename attribute of the writer. The default file name is <component-name>/<name>.log. If you use a relative filename, the file will be created under the Aspire log directory (defaults to $ASPIRE_HOME/log, but may be set via the $ASPIRE_LOG_DIR environment variable. The default severity filter is INFO

 <log><writer type="FILE" maxSize="10Mb" filename="myApplication/myPath/myComponent.log" severity="INFO"/></log>

OSGI writer

The OSGI writer is used to send messages to the Felix OSGI logger service. The default severity filter is INFO

 <log><writer type="OSGI" severity="NONE"/></log>

System severity filters

System severity filters allow you to control the entire system logging from the settings.xml file. System sevevity filters are set on log writer types, allowing all loggers of a particular type to to filter messages at a particular severity. There are six system severity filters:

  • NONE
    • No messages will be logged by the application or components
  • COMPONENT
    • Individual components will choose which severity filter to use
  • DEBUG
    • Debug messages and above will be logged by application or components
  • INFO
    • Only informtion messages and above will be logged by application or components
  • WARN
    • Only warning messages and above will be logged by application or components
  • ERROR
    • Only error messages and above will be logged by application or components

NOTE: setting a system severity filter for particular writer type will not add that writer type. However, if that writer type is configured (anywhere in the system), it will use that filter.

Controlling the log via the debug UI

Displaying the log

You can view the content of the UI log writer via the Aspire debug console. To view the log, visit the component's (or Application's) status page and click on the view link next to the Log: label.

LogViewLink.png

The content of the UI log writer will be displayed:

LogDisplay.png

NOTE: A UI log writer is always configured, regardless of whether or not you added one to the settings.xml or component configuration.

Controlling severity filters

You can control the level of logging via the Aspire debug console. To control the logging, visit the component's (or Application's) status page and click on the settings link next to the Log: label.

LogSettingsLink.png

You will be presented with a pop-up from where you can control the logging:

LogSettings.png

The pop-up will show the configured log writers and the severity filter currently set. If you wish to set the severity level for a specific log writer, select the desired value from the drop-down and press the set button on the right of the drop-down.

If you wish to set the severity levels for all log writers, select the desired value for each writer from the drop-downs and then press the set button in the row labelled all.

If you wish to set all configured log writers to debug, press the debug button in the row labelled all.

Controlling system severity filters

When the settings pop-up is accessed via the Application's status page in the Aspire debug console, you are also able to set the system severity filters. The Application's settings popup contains a second pane:

LogAppSettings.png

If you wish to set the system severity level for a specific log writer, select the desired value from the drop-down and press the set button on the right of the drop-down.

If you wish to set the system severity levels for all log writers, select the desired value for each writer from the drop-downs and then press the set button in the row labelled all.

You can also set all system severity levels to debug or component using the buttons in the row labelled all

Rotating the log writers

You can rotate the log writers via the settings pop-up. Click the rotate link to the right of the pop-up. Rotating the writers has the following effect:

  • UI
    • The messages stored in the UI are cleared
  • Console
    • No effect
  • File
    • The current file is closed and renamed with a timestamp on the end. A new file is opened
  • OSGI
    • No effect

The debug flag

The <debug> flag is still supported with in component configurations and is now supported in the setting file. Setting the debug flag to true will turn all the severity filters for configured log writers to debug

Example component configurations

Configuration to log INFO and above to the UI and FILE writers, WARN and above to the CONSOLE and ERR and above to OSGI:

<component name="MyHTTPFeeder" factoryName="aspire-http-feeder" subType="default">
  <log>
    <writer type="UI" severity="INFO"/>
    <writer type="FILE" severity="INFO"/>
    <writer type="CONSOLE" severity="WARN"/>
    <writer type="OSGI" severity="ERROR"/>
  </log>
  <branches>
    <branch event="onPublish" pipelineManager="ProcessPipelineManager"/>
  </branches>
</component>

Configuration to log DEBUG and above to the FILE writer, INFO and above to the FILE & CONSOLE:

<component name="MyHTTPFeeder" factoryName="aspire-http-feeder" subType="default">
  <log>
    <writer type="UI" severity="INFO"/>
    <writer type="FILE" severity="DEBUG"/>
    <writer type="CONSOLE" severity="INFO"/>
  </log>
  <branches>
    <branch event="onPublish" pipelineManager="ProcessPipelineManager"/>
  </branches>
</component>

Configuration to log DEBUG and above to the FILE writer, INFO and above to the FILE & CONSOLE and nothing to OSGI:

<component name="MyHTTPFeeder" factoryName="aspire-http-feeder" subType="default">
  <log>
    <writer type="UI" severity="INFO"/>
    <writer type="FILE" severity="DEBUG"/>
    <writer type="CONSOLE" severity="INFO"/>
    <writer type="OSGI" severity="NONE"/>
  </log>
  <branches>
    <branch event="onPublish" pipelineManager="ProcessPipelineManager"/>
  </branches>
</component>

NOTE: configuring an OSGI writer with a filter of NONE is subtly different to not configuring an OSGI writer. If the writer is configured, it can be turned on later via the debug console (either by setting the severity filters for the component or by changing the system severity filters for the application). You cannot add a log writer once Aspire is running.

Example settings.xml configuration

Configuration to turn on debugging:

<settings>
  <debug>true</debug>
  <!--OSGI properties -->
  <configAdmin>
  .
  .
  .
</settings>

Configuration to INFO and above to UI & FILE, WARN and above to CONSOLE and ERROR to OSGI and allow individual components to choose their own level of logging:

<settings>
  <log>
    <writer severity="INFO" type="UI"/>
    <writer severity="INFO" type="FILE"/>
    <writer severity="WARN" type="CONSOLE"/>
    <writer severity="ERROR" type="OSGI"/>
  </log>
  <!--OSGI properties -->
  <configAdmin>
  .
  .
  .
</settings>

Configuration to as above, but to override components to use INFO and above to FILE and NONE to OSGI:

<settings>
  <log>
    <writer severity="INFO" type="UI"/>
    <writer severity="INFO" type="FILE"/>
    <writer severity="WARN" type="CONSOLE"/>
    <writer severity="ERROR" type="OSGI"/>
    <system>
      <filter severity="INFO" type="FILE"/>
      <filter severity="NONE" type="OSGI"/>
    </system>
  </log>
  <!--OSGI properties -->
  <configAdmin>
  .
  .
  .
</settings>

Configuration to allow components to define their own loggers, but to override to send only ERRORs to the CONSOLE

<settings>
  <log>
    <system>
      <filter severity="ERROR" type="CONSOLE"/>
    </system>
  </log>
  <!--OSGI properties -->
  <configAdmin>
  .
  .
  .
</settings>