.. highlight:: xml .. index:: Log Tasks .. _log_tasks: Tasks/Commands for Working with DataPower Logs ============================================== .. _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 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 ^^^^^^^^^^^^^^^^^^ .. 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 `_. .. _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! .. _setLogLevel: ``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. 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 .. code-block:: xml