Listener Configuration

   This page describes the data format that you must use to define your Log4Ant build listener configuration. The Log4Ant build listener is a special extension of the builtin <emit:capturelogs> taskset so all of the features and limitations of that component apply to listeners as well. In particular, by default the Log4Ant listener will categorize Ant messages based their associated levels (debug, info, error, etc.). To change this behavior you need to configure the listener explicitly; this page shows you how to do that. For an overview of the <emit:capturelogs> component, read the Log4Ant Overview.

The Minimum

The listener configuration file is a valid JSON formatted text file with a single anonymous root object. This top-level object must define a marker string attribute “type” with the value “Log4Ant.Listener”. If Log4Ant does not find a single root object with this attribute– it will not try to read the the remaining data. If you have multiple listener configuration files, you might find it useful to identify the listener using the optional “id” attribute. Note that this id has no effect on the targeted SLF4J logger. 

{
  "id": "Nightly",
  "type": "Log4Ant.Listener"
}

By default, Log4Ant will automatically include the source message’s enclosing project’s name and target’s name when it determines the receiving Logger. To change this behavior you need to define the optional top-level “includes” string attribute. The format for this string is exactly the same as the same-named attribute for the <emit:capturelogs> taskset. Two examples that define different criteria are shown below: 

{
  "id": "Nightly",
  "type": "Log4Ant.Listener",
  "includes": "none"
}
 
{
  "id": "Nightly",
  "type": "Log4Ant.Listener",
  "includes": "target"
}

Add Default Logger

While Log4Ant will automatically bucket Ant messages based on its associated level, you can tell Log4Ant to pin all messages to a particular SLF4J logger. Doing so will define the parent logger for all messages– regardless of any other mapping criteria. To define the parent logger for all messages, declare an object named “configuration” nested inside the top-level object. The configuration object expects up to four string attributes (all optional): “to”, “wrt”, “level”, and “id”. The format for these strings is the same as the same-named attribute for the <emit:configuration> type. This example shows how to pin all emitted messages to the “JWare.Log4Ant” logger: 

{
  "id": "Nightly",
  "type": "Log4Ant.Listener",
  "configuration" : {
    "to": "JWare.Log4Ant"
  }
}

Add Custom Loggers

Once you’ve defined the minimum configuration, you can fine tune where Log4Ant targets individual messages or groups of messages using a JSON-formatted <emit:mappings> object. You declare your mappings as part of a “mappings” object nested under the top-level object. This mappings object can contain an optional “id” string attribute and a required array “items” of mapping objects as shown below (note that the ‘…’ means “add more items here”, it is not a legitimate part of the syntax): 

{
  "id": "Nightly",
  "type": "Log4Ant.Listener",
  "configuration" : {
    "to": "JWare.Log4Ant"
  },
  "mappings": {
    "id": "Standard",
    "items": [
      {
        "type": "indicator",
        "name": "problems",
        "logger": "Problems"
      },
      {
        "type": "indicator",
        "like": ".*",
        "logger": "FineTrace"
      },
      {
        "type": "target"
        "like": "^(.*)\-[lL]ibrary$",
        "loggermatch": "Libraries\.\1"
      },
      …
    ]
  }
}

Syntax Summary

This section describes the full recognized syntax of the Log4Ant JSON configuration file. In the descriptions ‘<root>’ refers to the top-level anonymous object {…}.

Parameters: <root>

Attribute Description Required
id [string] Identifier for this object. No
type [string] Marker for Log4Ant configuration files; must be defined as “Log4Ant.Listener.” Yes
includes [string] Set the fixture context automatically used to map a message to a logger. Format matches “includes” parameter of the <emit:capturelogs> taskset. No
configuration [object] Logger configuration. See attributes below. No
mappings [object] Message mapping instructions. See attributes below. No

Nested Object: <root>.configuration

Attribute Description Required
id [string] Identifier for this object. No
to [string] Name of the top-level enclosing logger for all emitted messages. No
wrt [string] Dynamic logger that ‘to’ is mapped relative to. No
level [string] The noise level for all messages. No

Nested Object: <root>.mappings

Attribute Description Required
id [string] Identifier for this object. No
items [array] Set of mapping items. See attributes below. Yes

Nested Array: <root>.mappings.items

Attribute Description Required
type [string] The kind of mapping; must be one of: “indicator”, “project”, “target”, “task”, “message”. Yes
null, like,
name, names 		[string] Match criteria. If you use like, the value must be a valid regular expression for your Ant-installed regular expression implementation. Yes, one of these required.
logger,
loggermatch 		[string] Logger name. If you use loggermatch, you must use the regular expression match criteria like and a valid regular expression for your Ant-installed regular expression implementation. Yes, one of these required.

Navigation
Personal Tools