.. highlight:: xml .. index:: Log Tasks .. _log_tasks: Log and Log Target-Related Commands =================================== .. _tailLog: ``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 checkOld 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 ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 :ref:`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: 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. .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 (), 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. .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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. .. code-block:: bat dpbuddy tail -domainPatterns "dpbuddy-.*, e2e.*" -lines 100 .. code-block:: xml The following task automatically retrieves new log entries until it encounters ``|E|`` or ``|W|`` anywhere in a log entry: .. code-block:: bat dpbuddy tail -f -failPatterns "\|[E|W]\|" .. code-block:: xml .. code-block:: bat 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. .. code-block:: xml You can find more examples under ``samples`` in your distribution or `online `_. .. _syslogTarget: ``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 :ref:`dpbuddy config file (dpbuddy.conf) `. Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 ^^^^^^^^ .. code-block:: bat 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: ``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 :ref:`dpbuddy config file (dpbuddy.conf) `. Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 ^^^^^^^^ .. code-block:: bat dpbuddy soapLogTarget -name soap-trg -remoteUrl "http://soap-backend" -localAddress dp-qa -levelInfo "all:info, mgmt:info" -disabled .. _fileLogTarget: ``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 :ref:`dpbuddy config file (dpbuddy.conf) `. Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 ^^^^^^^^ .. code-block:: bat dpbuddy fileLogTarget -name file-trg -fileName log-file -logSize 2048 -rotations 3 -levelInfo "all:info, mgmt:info" -comments "file based log target" -save .. _updateLogTargetLevel: ``updateLogLevel``/``updateLogTargetLevel`` ------------------------------------------- This task updates/sets log category and log level ("Event Subscriptions" screen in WebGUI) for one or multiple log targets. Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 Examples ^^^^^^^^ .. code-block:: bat dpbuddy updateLogLevel -domain test -name "syslg.*" -levelInfo "all:notice, mgmt:info" .. _setLogLevel: ``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 :ref:`updateLogTargetLevel ` Attributes/Options ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - Name - Description - Required * - level - Log entry's severity level, one of the following: EMERG, ALERT, CRITIC, ERROR, WARN, NOTICE, INFO, DEBUG. - Yes Examples ^^^^^^^^ .. code-block:: bat dpbuddy setLogLevel -level DEBUG -domain test .. code-block:: xml .. _log: ``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 ^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 20 80 8 :header-rows: 1 * - 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 Examples ^^^^^^^^ .. code-block:: bat dpbuddy log -level info -category all -message="Hello from DPBuddy" .. code-block:: xml Hello from DPBuddy!