This is an old revision of the document!
XML Logging
XML logging is one of the WinSCP log formats. XML log includes structured records describing operations done by WinSCP over session. The log format is protocol independent.
Advertisement
Purpose
Primary purpose of the XML logging is to provide machine-readable description of automatically performed operations, such as when using scripting.
XML logging is useful e.g. to:
- Find a list of files that were actually uploaded/downloaded, when transferring whole directory or files matching a mask;
- Get directory listing;
- Record operations done during synchronization.
The XML logging is not intended for detection, if batch of operations (such as script file) succeeded or not1. See below.
Using
XML logging is mostly useful with logging to file only. Overall format of the XML log file follows:
<?xml version="1.0" encoding="UTF-8"?> <session xmlns="http://winscp.net/schema/session/1.0" name="martin@example.com" start="2009-03-02T19:34:57.734Z"> <!-- operations --> </session>
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 initiated2.
The session
element includes child elements, where each element represents single log entry, i.e. single physical operation with remote file over the logical session.
Advertisement
Representing Operations in Log
Every entry in XML log represents single physical operation over the session. Typically this would be an operation with remote file.
Single logical operation (in scripting or GUI) may actually involve multiple physical operations, each represented with separate log element. For example upload of file (e.g. using put
scripting command) may be represented by up to three elements, upload
for actual upload, touch
for preserving timestamp and chmod
for preserving permissions.
Note that some logical operations does not have corresponding log element (e.g. creation of symbolic link). Such operations are omitted from the XML log.
Representing Results/Errors of Operations
First, note that the XML logging is not intended for detection, if batch of operations (such as script file) succeeded or not1.
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 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.
<result success="true" />
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:
<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>
Elements
All operation elements below have result
child element in addition to listed child elements.
The result
child element is always present. Many other child elements may be absent in case of error.
Advertisement
upload
Upload of single file.
Elements:
Element | Description |
---|---|
filename |
Absolute path to source local file (in value attribute) |
destination |
Absolute path to destination remote file (in value attribute)3 |
Example:
<upload> <filename value="d:\www\about.htm" /> <destination value="/home/martin/public_html/about.html" /> <result success="true" /> </upload>
Associated script commands: keepuptodate
, put
, synchronize remote|both