Log Tailing and Log Targets¶

`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.

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

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}

`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.

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.

`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

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.

`syslogTarget`¶

Creates or updates a syslog log target. By default, the target is created using the target configuration file packaged with the DPBuddy distribution. A custom configuration can be provided using the targetConfigFile attribute. This configuration could be created by exporting a logging target object from DataPower. You can use “${}” variable for any text value in the configuration file to create a templetized configuration. Variables can be defined in dpbuddy config file (dpbuddy.conf).

Attributes/Options¶

Name	Description	Required
name	Name of the log target.	Yes
remoteHost	Syslog server’s host name.	Yes
remotePort	Syslog server’s port. Defaults to 514.	No
localIdentifier	Local identifier for syslog.	No
localAddress	Local address (host alias) reported in log entries.	No
levelInfo	List of category/level pairs in HOCON format, e.g., “all:notice, mgmt:info”. Acceptable levels include: emerg, alert, critic, error, warn, notice, info, debug. You can view a complete list of categories in WebGUI.	Yes
disabled	Create target in the disabled state. Defaults to `false`.	No
feedbackDetection	Turn on feedback detection. Defaults to `false`.	No
timestampFormat	Timestamp format (syslog, zulu, Numeric). Defaults to `syslog`.	No
comments	Comments.	No

Examples¶

dpbuddy syslogTarget -domain test -name syslog-trg -remoteHost syslog-server -remotePort 123 -localIdentifier "dp7-qa--test" -localAddress dp-qa -levelInfo "all:info, mgmt:info"

`soapLogTarget`¶

Creates or updates a SOAP/HTTP log target. By default, the target is created using the target configuration file packaged with the DPBuddy distribution. A custom configuration can be provided using the targetConfigFile attribute. This configuration could be created by exporting a logging target object from DataPower. You can use “${}” variable for any text value in the configuration file to create a templetized configuration. Variables can be defined in dpbuddy config file (dpbuddy.conf).

Attributes/Options¶

Name	Description	Required
name	Name of the log target.	Yes
remoteUrl	URL of the server the log entries will be sent to.	Yes
localAddress	Local address (host alias) reported in log entries.	No
levelInfo	List of category/level pairs in HOCON format, e.g., “all:notice, mgmt:info”. Acceptable levels include: emerg, alert, critic, error, warn, notice, info, debug. You can view a complete list of categories in WebGUI.	Yes
disabled	Create target in the disabled state. Defaults to `false`.	No
feedbackDetection	Turn on feedback detection. Defaults to `false`.	No
timestampFormat	Timestamp format (syslog, zulu, Numeric). Defaults to `syslog`.	No
comments	Comments.	No

Examples¶

dpbuddy soapLogTarget -name soap-trg -remoteUrl "http://soap-backend" -localAddress dp-qa -levelInfo "all:info, mgmt:info" -disabled

`fileLogTarget`¶

Creates or updates a file log target. By default, the target is created using the target configuration file packaged with the DPBuddy distribution. A custom configuration can be provided using the targetConfigFile attribute. This configuration could be created by exporting a logging target object from DataPower. You can use “${}” variable for any text value in the configuration file to create a templetized configuration. Variables can be defined in dpbuddy config file (dpbuddy.conf).

Attributes/Options¶

Name	Description	Required
name	Name of the log target.	Yes
fileName	Destination configuration: file name.	Yes
numberOfRotations	Number of rotations, defaults to 3.	No
logSize	Log size in KB, defaults to 4096 KB.	No
levelInfo	List of category/level pairs in HOCON format, e.g., “all:notice, mgmt:info”. Acceptable levels include: emerg, alert, critic, error, warn, notice, info, debug. You can view a complete list of categories in WebGUI.	Yes
disabled	Create target in the disabled state. Defaults to `false`.	No
feedbackDetection	Turn on feedback detection. Defaults to `false`.	No
timestampFormat	Timestamp format (syslog, zulu, Numeric). Defaults to `syslog`.	No
comments	Comments.	No

Examples¶

dpbuddy fileLogTarget -name file-trg -fileName log-file -logSize 2048 -rotations 3 -levelInfo "all:info, mgmt:info" -comments "file based log target" -save

`updateLogLevel`/`updateLogTargetLevel`¶

This task updates/sets log category and log level (“Event Subscriptions” screen in WebGUI) for one or multiple log targets.

Attributes/Options¶

Name	Description	Required
namePattern CLI alias: name	Only the targets whose name matched this regexp will be updated.	Yes
levelInfo	List of category/level pairs in HOCON format, e.g., “all:notice, mgmt:info”. If a category for a matching target doesn’t exist, it will be added. The existing categories are not deleted even if they are not in the list. Acceptable levels include: emerg, alert, critic, error, warn, notice, info, debug. You can view a complete list of categories in WebGUI.	Yes
dryRun	If set to `true`, do not apply any changes, only print matching objects. Defaults to `false`.	No

Name

Description

Required

namePattern

CLI alias: name

Only the targets whose name matched this regexp will be updated.

Yes

levelInfo

List of category/level pairs in HOCON format, e.g., “all:notice, mgmt:info”. If a category for a matching target doesn’t exist, it will be added. The existing categories are not deleted even if they are not in the list.

Acceptable levels include: emerg, alert, critic, error, warn, notice, info, debug.

You can view a complete list of categories in WebGUI.

Yes

dryRun

If set to true, do not apply any changes, only print matching objects.

Defaults to false.

Examples¶

dpbuddy updateLogLevel -domain test -name "syslg.*" -levelInfo "all:notice, mgmt:info"

`setLogLevel`¶

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

Note that this task can only update the default log target and “all” log category. For all other needs, use updateLogTargetLevel

Attributes/Options¶

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

Name

Description

Required

level

Log entry’s severity level, one of the following:

EMERG, ALERT, CRITIC, ERROR, WARN, NOTICE, INFO, DEBUG.

Yes

Examples¶

dpbuddy setLogLevel -level DEBUG -domain test

<dp:setLogLevel level="DEBUG" />

`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.

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

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.

Examples¶

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

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

Log Tailing and Log Targets¶

tailLog¶

Attributes/Options¶

Log Entry Format¶

where Nested Element¶

domainPattern Nested Element¶

Examples¶

syslogTarget¶

Attributes/Options¶

Examples¶

soapLogTarget¶

Attributes/Options¶

Examples¶

fileLogTarget¶

Attributes/Options¶

Examples¶

updateLogLevel/updateLogTargetLevel¶

Attributes/Options¶

Examples¶

setLogLevel¶

Attributes/Options¶

Examples¶

log¶

Attributes/Options¶

Examples¶

`tailLog`¶

`where` Nested Element¶

`domainPattern` Nested Element¶

`syslogTarget`¶

`soapLogTarget`¶

`fileLogTarget`¶

`updateLogLevel`/`updateLogTargetLevel`¶

`setLogLevel`¶

`log`¶