logging_xml » Revisions »
Differences
This shows you the differences between the selected revisions of the page.
| 2011-09-15 | 2011-11-03 | ||
| bug 545 result in session (martin) | 5.0.3 failure tag (martin) | ||
| Line 25: | Line 25: | ||
| The top level ''session'' tag represents one logical session, which may consist of several physical sessions, particularly when connection is lost. Attribute ''name'' refers to name of the logical session. Attribute ''start'' indicates time when the session was initiated ((All timestamps in XML log have XML ''dateTime'' type, where only ''YYYY-MM-DD"T"HH:MM:SS.NNN"Z"'' syntax is used.)). | The top level ''session'' tag represents one logical session, which may consist of several physical sessions, particularly when connection is lost. Attribute ''name'' refers to name of the logical session. Attribute ''start'' indicates time when the session was initiated ((All timestamps in XML log have XML ''dateTime'' type, where only ''YYYY-MM-DD"T"HH:MM:SS.NNN"Z"'' syntax is used.)). | ||
| - | The ''session'' element includes [[logging_xml#elements|child elements]], where each element represents single log entry, i.e. single physical operation with remote file over the logical session. In case the connection is not established, the ''session'' element includes single ''[[logging_xml#result|result]]'' element with the error (&beta_feature). | + | The ''session'' element includes [[logging_xml#elements|child elements]], where each element represents single log entry, i.e. single physical operation with remote file over the logical session. |
| ===== [[operations]] Representing Operations in Log ===== | ===== [[operations]] Representing Operations in Log ===== | ||
| Line 34: | Line 34: | ||
| Note that some logical operations does not have corresponding log element (e.g. [[task_link|creation of symbolic link]]). Such operations are omitted from the XML log. | Note that some logical operations does not have corresponding log element (e.g. [[task_link|creation of symbolic link]]). Such operations are omitted from the XML log. | ||
| - | ===== [[result]] Representing Results/Errors of Operations ===== | + | ===== [[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. | First, note that the XML logging is not intended for detection, if batch of operations (such as script file) succeeded or not. | ||
| Line 41: | Line 44: | ||
| XML log may not include some errors, even if they occur, for two reasons: | 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 operation that failed does not have corresponding log element (see [[logging_xml#operations|above]]). | ||
| - | * The error is not associated with particular physical operation. 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. | + | * 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. | 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 or top level ''session'' element. The ''result'' element has boolean ''success'' attribute. Note that top level ''session'' element includes ''result'' only in case of failure (&beta_feature). | + | Result of an operation is represented by child ''result'' element of respective operation element. The ''result'' element has boolean ''success'' attribute. |
| <code xml> | <code xml> | ||
| Line 62: | Line 65: | ||
| Request code: 3</message> | Request code: 3</message> | ||
| </result> | </result> | ||
| + | </code> | ||
| + | |||
| + | ==== Results/Errors of Operations in the Beta Release ==== | ||
| + | Result of a specific 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> | ||
| + | |||
| + | 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. | ||
| + | |||
| + | Some errors may not be associated with any operation in the XML log. This particularly happens when: | ||
| + | * An error is actually not associated with particular physical operation. Example is invalid script command syntax. | ||
| + | * The particular operation that failed does not have corresponding log element. | ||
| + | |||
| + | ==== Results/Errors of Script in the Beta Release ==== | ||
| + | When the script fails (WinSCP [[scripting#using_scripting|exit code]] is 1), the top level ''session'' element will include one or more ''failure'' elements, each containing one or more ''message'' elements with error message(s). | ||
| + | |||
| + | If the particular error was associated with a physical operation, the error message will be included both in ''result'' child element of the respective operation element and in ''failure'' child element of top level ''session'' element. | ||
| + | |||
| + | <code xml> | ||
| + | <upload> | ||
| + | <filename value="d:\examplefile.txt" /> | ||
| + | <result success="false"> | ||
| + | <message>Cannot create remote file '/home/user/examplefile.txt'.</message> | ||
| + | <message>Permission denied. | ||
| + | Error code: 3 | ||
| + | Error message from server: Permission denied | ||
| + | Request code: 3</message> | ||
| + | </result> | ||
| + | </upload> | ||
| + | <failure> | ||
| + | <message>Cannot create remote file '/home/user/examplefile.txt'.</message> | ||
| + | <message>Permission denied. | ||
| + | Error code: 3 | ||
| + | Error message from server: Permission denied | ||
| + | Request code: 3</message> | ||
| + | </failure> | ||
| </code> | </code> | ||
| Line 287: | Line 341: | ||
| ===== Example ===== | ===== Example ===== | ||
| + | //Note that the ''failure'' element will be included only with the latest beta release.// &beta | ||
| <code xml> | <code xml> | ||
| <?xml version="1.0" encoding="UTF-8"?> | <?xml version="1.0" encoding="UTF-8"?> | ||
| Line 315: | Line 370: | ||
| </result> | </result> | ||
| </rm> | </rm> | ||
| + | <failure> | ||
| + | <message>No such file or directory. | ||
| + | Error code: 2 | ||
| + | Error message from server: No such file | ||
| + | Request code: 13</message> | ||
| + | </failure> | ||
| </session> | </session> | ||
| </code> | </code> | ||