application-logapplication-log
Appends a record to an application specific log
Home > Books > NetKernel API and Services Reference > Accessor Listing > Utility and System Accessors > application-log

Rate this page:
Really useful
Satisfactory
Not helpful
Confusing
Incorrect
Unsure
Extra comments:


Module

urn:org:ten60:netkernel:ext:sys

The application-log accessor is exported by the urn:org:ten60:netkernel:ext:sys module. Import this module to gain access to the accessor.

Syntax

URI
active:application-log

ArgumentRulesDescription
operandMandatory resource to be serialized to the application log
operatorOptional qualification document
configurationOptional log configuration

Example Usage

DPML

<instr>
  <type>application-log</type>
  <operand>foo.xml</operand>
  <operator>
    <log>
      <severe />
    </log>
  </operator>
</instr>

NetKernel Foundation API

req=context.createSubRequest("active:application-log");
req.addArgument("operand", new StringAspect("shuttle launched") );
context.issueAsyncSubRequest(req);

Purpose

The application-log accessor is used to serialize the operand resource to an application specific log. It is useful for debuging, critical failure reports, or status messages. Log entries created using this accessor are created at the info level by default.

Log entries are written to the console and to a specified log file in XML format as per XMLFormatter javadoc. This file can be viewed using the Log Viewer.

All logging levels are on by default. Logging levels can be set individually for each log using the Logging Levels Tools in the control panel. These settings are persisted between restarts.

Also see the log accessor which is used to write to the NetKernel system log.

Operator Syntax

The application-log accessor takes an optional operator which is an XML fragment used to specify non-default options. Here is an example...

<log>
  <!-- Log the text value contained by the root element -->
  <string />
  <!-- Prepend the parent request of the request that initiated the log -->
  <request />
  <!-- Log this at level 'finest' -->
  <finest />
</log>

If the /log/string element exists then the operand is assumed to be XML and the text of the root element is serialized. If it doesn't exist or there is no operator then the whole operand is serialized to the log.

If the /log/request element exists then the parent request that initiated the log request is prepended as the first line of this log entry.

Optional finest, finer, fine, info, warning, or severe elements set the logging severity. By default the logging level is set to info.

Configuration Syntax

The application-log accessor accepts a configuration argument. If omited the configuration argument defaults to the resource addressed by the uri ffcpl:/etc/LogConfig.xml. The accessor will fail if no configuration argument can be found. Unusually, the configuration is only read once; changes, once accessed, are not detected, and so you must restart to change configuration settings. The configuration resource must be an XML fragment of the form:

<log>
  <name>my-unique-log-name</name>
  <destination>log/my-log-%g.log</destination>
  <limit>131072</limit>
  <count>2</count>
</log>

The name element within the configuration argument is a system unique identifier used to locate logs. The JDK documentation recommends using the full package name of the subsystem. Within NetKernel this could be the URI of the module.

The destination element within the configuration argument is a filesystem path which is used to specify the filename of the log. Optional %g wilcards are permitted as per FileHandler javadoc. The filename may be relative and in which case it will be resolved against the NetKernel basepath as specified in system.xml.

The limit element within the configuration argument specifies the maximum filesize in bytes of a logfile before it will be closed.

The count element within the configuration argument specifies the number of log files to be used in rotation (use %g wildcard to make each one unique.)

How to integrate application specific logs into your application

Application logs are created on demand and require no special registration. Application logs are configured per application by specifying either a specific configuration argument or by creating a configuration resources addressed at ffcpl:/etc/LogConfig.xml. Logging Levels and Log viewing is available via the standard NetKernel control panel however the logs will not appear until the first time they have been accessed by the application after startup.

It is possible to create entrypoints within your application which redirect to the logging levels and log view pages within the control panel specific to your applications log. To do this you will need to create a script which will call the HTTP Redirect accessor with the following addresses. This useful for creating a custom control panel for your application (see Entrypoint System Guide.)
view log[host:port]/ep+name@app_ext_introspect_log?log=[name of log]
configure levels[host:port]/ep+name@app_ext_introspect_loglevel?log=[name of log]

© 2003-2007, 1060 Research Limited. 1060 registered trademark, NetKernel trademark of 1060 Research Limited.