..highlight:: xml .. index:: Log Tasks

18. Tasks/Commands for Working with DataPower Logs

.._tailLog:

18.1. tailLog

The tailLog task retrieves log entries from a device and prints them to standard output. The task prints the last 48 lines of the log by default.

You can also use the task to save the contents of the DataPower log file locally.

tailLog is capable of continuously querying the device and identifying new entries based on timestamps. This works similarly to tail -f Unix command.

You can also use tail alias from DPBuddy CLI.

tailLog can check log entries for errors based on regular expressions. When a log entry contains an occurrence of such an expression, tailLog will raise an exception. This allows for using tailLog for monitoring DataPower devices, especially in combination with running tailLog continuously.

You can also pipe Ant running the tailLog target with “grep” to search for specific strings in the log.

18.1.1. Attributes/Options

Name	Description	Required
lines	Number of the most recent log entries to display. “-1” directs the task to print or save all available log entries. Defaults to 48 lines.	No
logTarget	Name of the log target defined on the device. Defaults to “default-log” (DataPower default).	No
domainPatterns	Comma-delimited list of regular expressions specifying domains to get logs from. Log entries from all matching domains are combined together and sorted by their timestamps. Use domainPattern nested elements if there is a need to use commas inside the regexp. Defaults to current domain. The current domain can be specified using dp.domain Ant property or the domain attribute of the task.	No
format	Format string. See the Log Entry Format.	No
failOnError	If set to true, fail whenever an error-level log entry is encountered. Defaults to false.	No
failPatterns	List of comma-delimited regular expression patterns. tailLog will raise exception if it finds one of the patterns in the log entry. Patterns are applied to the entire formatted log entry string containing all fields.	No
follow CLI alias: -f	If set to true, query the device continuously every 3 seconds or according to the interval specified in followInterval. New log entries (determined based on their timestamp) are appended to standard output. Defaults to false.	No
followInterval	Interval in milliseconds used to continuously query the device if follow is set to true. This attribute is ignored if follow is false. Defaults to 3,000 milliseconds.	No
logFile	Local file to which the DataPower log file should be saved.	No
appendTimestamp	When logFile is set, append the timestamp to the local log file name. Defaults to false.	No

18.1.2. Log Entry Format

The tailLog task uses java.text.MessageFormat class to format DataPower log entries for display. The default format is {1,date,yyyy-MM-dd HH:mm:ss} |{2}|{6}|{5} {3}{0}. The format string uses numeric IDs for various log fields. tailLog supports the following fields:

• 0: log message
• 1: timestamp
• 2: severity level. tailLog prints ‘E’ for errors, ‘W’ for warning and ‘I’ for information-level messages.
• 3: DataPower class/object in the format Class (Object)
• 4: transaction ID
• 5: domain name
• 6: category

For example, you can use the following format string to display the domain name:

{5} | {1,date,yyyy-MM-dd HH:mm:ss} |{2}| {0}{3}

18.1.3. where Nested Element

tailLog can filter log entries received from the device so that only the ones matching the criteria specified in the where nested element will be printed.

Note that class names used in where are different from the ones used by export, delConfig, quiesce and other tasks that support nested object elements. The class names used in DataPower logs are different from class names of configuration objects. For example, wsgw is how Web services gateway type is referenced in the logs. The configuration class of the same type is WSGateway.

You can specify multiple where elements within the same task.

Name	Description	Required
class	Regular expression defining classes of log entries. Only log entries with matching classes will be printed. To find out class names, navigate to the object you’d like to print log entries for in WebGUI and click on “View log”. A log message usually starts with the prefix in the format <class>(<object>), e.g., wsgw (testServiceProxy):. If not specified, log entries will be printed regardless of classes.	Yes, unless name was provided.
name	Regular expression defining object names of log entries. Only the log entries with the matching objet names will be printed. If not specified, log entries will be printed regardless of object names.	Yes, unless class was provided.

18.1.4. domainPattern Nested Element

The domainPattern nested element provides an alternative to specifying domain patterns in the domainPatterns attribute. It is useful when a regular expression contains commas, which are used as a delimiter in the domainPatterns attribute.

You can specify multiple domainPattern elements within the same task.

Name	Description	Required
pattern	Get logs from the domains matching this regexp pattern.	Yes

18.1.5. Examples

The following example collects log entries from system logs in the “default” domain and all domains starting with “dev”. It displays the last 100 lines of the combined log.

dpbuddy tail -domainPatterns "dpbuddy-.*, e2e.*"  -lines 100

<dp:tailLog domainPatterns="default, dev.*"  lines="100" />

The following task automatically retrieves new log entries until it encounters |E| or |W| anywhere in a log entry:

dpbuddy tail -f -failPatterns "\|[E|W]\|"

<dp:tailLog failPatterns="\|[E|W]\|" follow="true" >

dpbuddy tail -f | grep  "\|[E|W]\|"

The following example logs only the entries for all Web services gateways starting with “testService” and all XML firewalls.

<dp:tailLog failOnError="false" >
    <where class="wsgw" object="testService.*" />
    <where class="xmlfire.*" />
</dp:tailLog>

You can find more examples under samples in your distribution or online.

18.2. log

log creates a log entry in the DataPower log on the device. Logging a message in the device log can be useful for audit and troubleshooting purposes. For example, you can create a log entry before applying a set of changes to the device.

18.2.1. Attributes/Options

Name	Description	Required
message	Message to log.	This attribute or nested text.
level	Log entry’s severity level, one of the following: EMERG, ALERT, CRITIC, ERROR, WARN, NOTICE, INFO, DEBUG. Defaults to WARN.	No
category	DataPower log category. You can find the list of all categories under the Administration/Miscellaneous/Configure Log Category in WebGUI. Defaults to “all”.	No

18.2.2. Examples

dpbuddy log -level info -category all  -message="Hello from DPBuddy"

<dp:log>
    Hello from DPBuddy!
</dp:log>

18.3. setLogLevel

This task sets the log level of the default log category (“all”). This is equivalent to navigating to “Manage Log Targets”/”Event Subscriptions” in WebGUI and editing the minimum event priority for “all” category.

18.3.1. Attributes/Options

Name	Description	Required
level	Log entry’s severity level, one of the following: EMERG, ALERT, CRITIC, ERROR, WARN, NOTICE, INFO, DEBUG.	Yes

18.3.2. Examples

dpbuddy setLogLevel -level DEBUG

<dp:setLogLevel level="DEBUG" />