logging_xml » Revisions »
Differences
This shows you the differences between the selected revisions of the page.
| 2012-08-03 | 2012-09-24 | ||
| removed duplicate slash (martin) | 5.1 is stable (martin) | ||
| Line 2: | Line 2: | ||
| XML logging is one of the WinSCP [[logging|log formats]]. XML log includes structured records describing operations done by WinSCP over session. The log format is protocol independent. | XML logging is one of the WinSCP [[logging|log formats]]. XML log includes structured records describing operations done by WinSCP over session. The log format is protocol independent. | ||
| - | In many cases you do not have to deal with the XML log file directly. [[library|WinSCP .NET assembly]] can do it fo you. | + | In many cases you do not have to deal with the XML log file directly. [[library|WinSCP .NET assembly]] can do it for you. |
| ===== Purpose ===== | ===== Purpose ===== | ||
| Line 11: | Line 11: | ||
| * Get directory listing; | * Get directory listing; | ||
| * Record operations done during [[task_synchronize_full|synchronization]]. | * Record operations done during [[task_synchronize_full|synchronization]]. | ||
| - | |||
| - | The XML logging is not intended for detection, if batch of operations (such as script file) succeeded or not. See [[logging_xml#result|below]]. //Note that this limitation is no longer true in the latest beta release.// &beta | ||
| ===== Using ===== | ===== Using ===== | ||
| Line 39: | Line 37: | ||
| ===== [[result]] Representing Results/Errors ===== | ===== [[result]] Representing Results/Errors ===== | ||
| - | //Representing of results/errors in XML log has been greatly improved (and modified) in the latest beta release. For that reason documentation for both stale and beta releases is available here.// &beta | ||
| - | |||
| - | ==== In the Stable Release ==== | ||
| - | First, note that the XML logging is not intended for detection, if batch of operations (such as script file) succeeded or not. | ||
| - | |||
| - | When checking for outcome of batch execution, you need check positively for presence of operations you have executed. Absence of errors does not indicate success. Note, when using scripting, checking WinSCP [[scripting#using_scripting|exit code]] is the only ultimate way to detect errors. | ||
| - | |||
| - | XML log may not include some errors, even if they occur, for two reasons: | ||
| - | * The operation that failed does not have corresponding log element (see [[logging_xml#operations|above]]). | ||
| - | * The error is not associated with particular physical operation. Simple example is authentication failure. More treacherous example is failure to list remote directory, to find list of files it contains, while downloading the directory. This error occurs during download operation, which is logged. But as download of individual files is logged only, the error is not associated with download of any particular file. So it will be absent from the XML log. | ||
| - | |||
| - | With some protocols, each of the physical operations are performed individually. With some protocols, set of operations may be performed in atomic form. This may prevent mapping error to specific operation. In this case the error may be associated with more operations, resulting in its duplication in the XML log. | ||
| - | |||
| - | Result of an operation is represented by child ''result'' element of respective operation element. The ''result'' element has boolean ''success'' attribute. | ||
| - | |||
| - | <code xml> | ||
| - | <result success="true" /> | ||
| - | </code> | ||
| - | |||
| - | If ''success'' is ''false'', ''result'' element will typically include one or more ''message'' elements with error message(s). The error message is free text, that may be language-, protocol- or even server-specific. So you should not try to process it automatically. | ||
| - | |||
| - | The following example is from English version, connected with SFTP protocol to OpenSSH server: | ||
| - | <code xml> | ||
| - | <result success="false"> | ||
| - | <message>Cannot open remote file '/home/user/examplefile.txt'.</message> | ||
| - | <message>No such file or directory. | ||
| - | Error code: 2 | ||
| - | Error message from server: No such file | ||
| - | Request code: 3</message> | ||
| - | </result> | ||
| - | </code> | ||
| - | ==== Results/Errors of Operations in the Beta Release ==== | + | ==== Results/Errors of Operations ==== |
| Result of a specific operation is represented by child ''result'' element of respective operation element. The ''result'' element has boolean ''success'' attribute. | Result of a specific operation is represented by child ''result'' element of respective operation element. The ''result'' element has boolean ''success'' attribute. | ||
| Line 97: | Line 64: | ||
| * The particular operation that failed does not have corresponding log element. | * The particular operation that failed does not have corresponding log element. | ||
| - | ==== [[result_script]] Results/Errors of Script in the Beta Release ==== | + | ==== [[result_script]] Results/Errors of Script ==== |
| When the script fails (WinSCP [[scripting#using_scripting|exit code]] is 1), the top level ''session'' element or ''group'' element (when [[logging_xml#group|grouping]] is enabled) will include one or more ''failure'' elements, each containing one or more ''message'' elements with error message(s). | When the script fails (WinSCP [[scripting#using_scripting|exit code]] is 1), the top level ''session'' element or ''group'' element (when [[logging_xml#group|grouping]] is enabled) will include one or more ''failure'' elements, each containing one or more ''message'' elements with error message(s). | ||
| Line 123: | Line 90: | ||
| ===== [[group]] Grouping Operations for Commands ===== | ===== [[group]] Grouping Operations for Commands ===== | ||
| - | &beta_feature | ||
| - | |||
| When using XML logging together with [[scripting|scripting]], [[logging_xml#elements|operations]] and [[logging_xml#result_script|failures]] belonging to the same command can be groupped using parent ''group'' element: | When using XML logging together with [[scripting|scripting]], [[logging_xml#elements|operations]] and [[logging_xml#result_script|failures]] belonging to the same command can be groupped using parent ''group'' element: | ||
| Line 340: | Line 305: | ||
| ==== stat ==== | ==== stat ==== | ||
| Listing of remote file attributes. | Listing of remote file attributes. | ||
| - | |||
| - | &beta_feature | ||
| Elements: | Elements: | ||
| Line 407: | Line 370: | ||
| ===== Example ===== | ===== Example ===== | ||
| - | //Note that the ''failure'' element will be included only with the latest beta release and ''group'' elements will be included only with the latest beta release and, if enabled only.// &beta | + | //Note that the ''group'' elements will be included, if enabled only.// |
| <code xml> | <code xml> | ||
| <?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | ||