logging_xml » Revisions »

Differences

This shows you the differences between the selected revisions of the page.

logging_xml 2015-02-17 logging_xml 2022-06-16 (current)
Line 4: Line 4:
In many cases you do not have to deal with the %%XML%% log file directly. [[library|WinSCP .NET assembly]] can do it for 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]] Purpose =====
Primary purpose of the XML logging is to provide machine-readable description of automatically performed operations, such as when using [[scripting|scripting]]. Primary purpose of the XML logging is to provide machine-readable description of automatically performed operations, such as when using [[scripting|scripting]].
The %%XML%% logging is useful e.g. to: The %%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; +  * Find a list of files that were actually uploaded/downloaded, when transferring a whole directory or when transferring files matching a mask; 
-  * Get directory listing;+  * Get a directory listing;
  * Record operations done during [[task_synchronize_full|synchronization]].   * Record operations done during [[task_synchronize_full|synchronization]].
-Note that while the %%XML%% logging can be used also for GUI sessions, it does not record a [[transfer_queue|background transfers]].+Note that while the %%XML%% logging can be used also for GUI sessions, it does not record [[transfer_queue|background transfers]].
-===== Using ===== +===== [[using]] Using ===== 
-The %%XML%% logging, being used along with [[scripting|scripting]], is most typically enabled from [[commandline|command-line]], using ''/xmllog'' parameter. It can be enabled in [[ui_pref_logging|preferences]] too.+The %%XML%% logging, being used along with [[scripting|scripting]], is most typically enabled from command-line, using ''[[commandline#logging|/xmllog]]'' parameter. It can be enabled in [[ui_pref_logging|preferences]] too.
An overall format of the %%XML%% log file follows: An overall format of the %%XML%% log file follows:
Line 27: Line 27:
</code> </code>
-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 the %%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 the %%XML%% log have %%XML%% ''dateTime'' type, where only ''%%YYYY-MM-DD"T"HH:MM:SS.NNN"Z"%%'' syntax is used.))
The ''session'' element includes [[#elements|child elements]], where each element represents single log entry, i.e. single physical operation with remote file over the logical session. The ''session'' element includes [[#elements|child elements]], where each element represents single log entry, i.e. single physical operation with remote file over the logical session.
Line 95: Line 95:
<code xml> <code xml>
-<group name="put -preservetime d:\*.txt" start="2012-01-04T14:25:10.204Z">+<group name="put -preservetime d:\*.txt" start="2021-12-03T14:25:10.204Z">
  <upload>   <upload>
    <filename value="d:\readme.txt" />     <filename value="d:\readme.txt" />
    <destination value="/home/user/readme.txt" />     <destination value="/home/user/readme.txt" />
 +    <size value="15345" />
    <result success="true" />     <result success="true" />
  </upload>   </upload>
Line 130: Line 131:
The ''result'' child element is always present. Many other child elements may be absent in case of error. The ''result'' child element is always present. Many other child elements may be absent in case of error.
-==== call ====+==== [[call]] call ====
Execution of arbitrary [[remote_command|remote shell command]] (with [[protocols|SFTP and SCP protocols]]) or execution of a protocol command (with FTP protocol). Execution of arbitrary [[remote_command|remote shell command]] (with [[protocols|SFTP and SCP protocols]]) or execution of a protocol command (with FTP protocol).
Line 156: Line 157:
Associated script commands: ''[[scriptcommand_call|call]]'' Associated script commands: ''[[scriptcommand_call|call]]''
-==== checksum ==== +==== [[checksum]] checksum ==== 
-[[ui_properties#checksum|Calculating a checksum]] of a remote file. &beta_feature+[[ui_properties#checksum|Calculating a checksum]] of a remote file.
Elements: Elements:
Line 177: Line 178:
Associated script commands: ''[[scriptcommand_checksum|checksum]]'' Associated script commands: ''[[scriptcommand_checksum|checksum]]''
-==== chmod ====+==== [[chmod]] chmod ====
[[task_properties|Changing of permissions]] of one (or more) remote file. [[task_properties|Changing of permissions]] of one (or more) remote file.
Line 198: Line 199:
Associated script commands: ''[[scriptcommand_chmod|chmod]]'', ''[[scriptcommand_keepuptodate|keepuptodate]] -permissions'', ''[[scriptcommand_put|put]] -permissions'', ''[[scriptcommand_synchronize|synchronize]] remote|both -permissions'' Associated script commands: ''[[scriptcommand_chmod|chmod]]'', ''[[scriptcommand_keepuptodate|keepuptodate]] -permissions'', ''[[scriptcommand_put|put]] -permissions'', ''[[scriptcommand_synchronize|synchronize]] remote|both -permissions''
-==== download ====+==== [[cp]] cp ==== 
 +[[task_move_duplicate#duplicate|Duplication]] of one remote file or directory. 
 + 
 +Elements: 
 +^ Element                  ^ Description ^ 
 +| ''filename''            | Absolute path to source local file (in ''value'' attribute) | 
 +| ''destination''          | Absolute path to destination remote file (in ''value'' attribute) | 
 + 
 +Example: 
 +<code xml> 
 +<cp> 
 +  <filename value="/home/martin/public_html/about.html" /> 
 +  <destination value="/home/martin/backup/about.html.20171220" /> 
 +  <result success="true" /> 
 +</cp> 
 +</code> 
 + 
 +Associated script commands: ''[[scriptcommand_cp|cp]]'' 
 + 
 +==== [[download]] download ====
[[task_download|Downloading]] of single file. [[task_download|Downloading]] of single file.
Line 205: Line 225:
| ''filename''            | Absolute path to source remote file (in ''value'' attribute) | | ''filename''            | Absolute path to source remote file (in ''value'' attribute) |
| ''destination''          | Absolute path to destination local file (in ''value'' attribute)((File name may differ from name of source file.)) | | ''destination''          | Absolute path to destination local file (in ''value'' attribute)((File name may differ from name of source file.)) |
 +| ''size''                | Number of bytes transferred. |
Example: Example:
Line 211: Line 232:
  <filename value="/home/martin/public_html/about.html" />   <filename value="/home/martin/public_html/about.html" />
  <destination value="d:\www\about.htm" />   <destination value="d:\www\about.htm" />
 +  <size value="55387" />
  <result success="true" />   <result success="true" />
</download> </download>
Line 217: Line 239:
Associated script commands: ''[[scriptcommand_get|get]]'', ''[[scriptcommand_synchronize|synchronize]] local|both'' Associated script commands: ''[[scriptcommand_get|get]]'', ''[[scriptcommand_synchronize|synchronize]] local|both''
-==== ls ====+==== [[ls]] ls ====
Listing of remote directory (only when explicitly requested using ''[[scriptcommand_ls|ls]]'' scripting command). Listing of remote directory (only when explicitly requested using ''[[scriptcommand_ls|ls]]'' scripting command).
Line 230: Line 252:
| ''type''                | Type of file as in Unix ''ls'' command output, e.g. ''d'' for directory (in ''value'' attribute) | | ''type''                | Type of file as in Unix ''ls'' command output, e.g. ''d'' for directory (in ''value'' attribute) |
| ''size''                | Size of file in bytes (in ''value'' attribute) | | ''size''                | Size of file in bytes (in ''value'' attribute) |
-| ''modification''        | Modification timestamp (in ''value'' attribute)((All timestamps in XML log have XML ''dateTime'' type, where only ''%%YYYY-MM-DD"T"HH:MM:SS.NNN"Z"%%'' syntax is used.)) |+| ''modification''        | Modification timestamp (in ''value'' attribute)((All timestamps in the %%XML%% log have %%XML%% ''dateTime'' type, where only ''%%YYYY-MM-DD"T"HH:MM:SS.NNN"Z"%%'' syntax is used.)) |
| ''permissions''          | File permissions in Unix format ''rwxrwxrwx'' (in ''value'' attribute) | | ''permissions''          | File permissions in Unix format ''rwxrwxrwx'' (in ''value'' attribute) |
-| ''owner''                | File owner (in ''value'' attribute) &beta_feature | +| ''owner''                | File owner (in ''value'' attribute) | 
-| ''group''                | File group (in ''value'' attribute) &beta_feature |+| ''group''                | File group (in ''value'' attribute) |
Example: Example:
Line 273: Line 295:
Associated script commands: ''[[scriptcommand_ls|ls]]'' Associated script commands: ''[[scriptcommand_ls|ls]]''
-==== mkdir ====+==== [[mkdir]] mkdir ====
[[task_create_directory|Creating of remote directory]]. [[task_create_directory|Creating of remote directory]].
Line 290: Line 312:
Associated script commands: ''[[scriptcommand_keepuptodate|keepuptodate]]'', ''[[scriptcommand_mkdir|mkdir]]'', ''[[scriptcommand_put|put]]'', ''[[scriptcommand_synchronize|synchronize]] remote|both'' Associated script commands: ''[[scriptcommand_keepuptodate|keepuptodate]]'', ''[[scriptcommand_mkdir|mkdir]]'', ''[[scriptcommand_put|put]]'', ''[[scriptcommand_synchronize|synchronize]] remote|both''
-==== mv ==== +==== [[mv]] mv ==== 
-[[task_move_duplicate#move|Moving]] or of one remote file or directory to different remote directory or [[task_rename|renaming]] of one remote file or directory.+[[task_move_duplicate#move|Moving]] of one remote file or directory to different remote directory or [[task_rename|renaming]] of one remote file or directory.
Elements: Elements:
Line 309: Line 331:
Associated script commands: ''[[scriptcommand_mv|mv]]'' Associated script commands: ''[[scriptcommand_mv|mv]]''
-==== rm ====+==== [[rm]] rm ====
[[task_delete|Deleting]] of one (or more) remote file or directory. [[task_delete|Deleting]] of one (or more) remote file or directory.
Line 328: Line 350:
Associated script commands: ''[[scriptcommand_get|get]] -delete'', ''[[scriptcommand_keepuptodate|keepuptodate]] -delete'', ''[[scriptcommand_rm|rm]]'', ''[[scriptcommand_rmdir|rmdir]]'', ''[[scriptcommand_synchronize|synchronize]] local|both -delete'' Associated script commands: ''[[scriptcommand_get|get]] -delete'', ''[[scriptcommand_keepuptodate|keepuptodate]] -delete'', ''[[scriptcommand_rm|rm]]'', ''[[scriptcommand_rmdir|rmdir]]'', ''[[scriptcommand_synchronize|synchronize]] local|both -delete''
-==== stat ====+==== [[stat]] stat ====
Listing of remote file attributes. Listing of remote file attributes.
Line 352: Line 374:
Associated script commands: ''[[scriptcommand_stat|stat]]'' Associated script commands: ''[[scriptcommand_stat|stat]]''
-==== upload ====+==== [[upload]] upload ====
[[task_upload|Uploading]] of single file. [[task_upload|Uploading]] of single file.
Line 359: Line 381:
| ''filename''            | Absolute path to source local file (in ''value'' attribute) | | ''filename''            | Absolute path to source local file (in ''value'' attribute) |
| ''destination''          | Absolute path to destination remote file (in ''value'' attribute)((File name may differ from name of source file.)) | | ''destination''          | Absolute path to destination remote file (in ''value'' attribute)((File name may differ from name of source file.)) |
 +| ''size''                | Number of bytes transferred. |
Example: Example:
Line 365: Line 388:
  <filename value="d:\www\about.htm" />   <filename value="d:\www\about.htm" />
  <destination value="/home/martin/public_html/about.html" />   <destination value="/home/martin/public_html/about.html" />
 +  <size value="55387" />
  <result success="true" />   <result success="true" />
</upload> </upload>
Line 371: Line 395:
Associated script commands: ''[[scriptcommand_keepuptodate|keepuptodate]]'', ''[[scriptcommand_put|put]]'', ''[[scriptcommand_synchronize|synchronize]] remote|both'' Associated script commands: ''[[scriptcommand_keepuptodate|keepuptodate]]'', ''[[scriptcommand_put|put]]'', ''[[scriptcommand_synchronize|synchronize]] remote|both''
-==== touch ====+==== [[touch]] touch ====
Changing of remote file timestamp. Changing of remote file timestamp.
Line 377: Line 401:
^ Element                  ^ Description ^ ^ Element                  ^ Description ^
| ''filename''            | Absolute path to remote file (in ''value'' attribute) | | ''filename''            | Absolute path to remote file (in ''value'' attribute) |
-| ''modification''        | Modification timestamp (in ''value'' attribute)((All timestamps in XML log have XML ''dateTime'' type, where only ''%%YYYY-MM-DD"T"HH:MM:SS.NNN"Z"%%'' syntax is used.)) |+| ''modification''        | Modification timestamp (in ''value'' attribute)((All timestamps in the %%XML%% log have %%XML%% ''dateTime'' type, where only ''%%YYYY-MM-DD"T"HH:MM:SS.NNN"Z"%%'' syntax is used.)) |
Example: Example:
Line 400: Line 424:
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<session xmlns="http://winscp.net/schema/session/1.0" <session xmlns="http://winscp.net/schema/session/1.0"
-        name="martin@example.com" start="2009-03-02T19:34:57.734Z">+        name="martin@example.com" start="2012-01-04T14:25:53.173Z">
  <group name="put -preservetime -permissions=644 d:\www\about.htm" start="2012-01-04T14:28:45.393Z">   <group name="put -preservetime -permissions=644 d:\www\about.htm" start="2012-01-04T14:28:45.393Z">
    <upload>     <upload>
Line 439: Line 463:
===== [[parse]] Interpreting/Parsing ===== ===== [[parse]] Interpreting/Parsing =====
 +
 +==== General ====
To parse the %%XML%% log, use any %%XML%% parser available. To parse the %%XML%% log, use any %%XML%% parser available.
Line 444: Line 470:
If you want to parse the XML log yourself anyway, see following guides to learn how to do that in different development environments: If you want to parse the XML log yourself anyway, see following guides to learn how to do that in different development environments:
-  * [[guide_automation_advanced|Guide to advanced scripting]] (Windows script host; Java or VB script); +  * [[guide_automation_advanced|*]] (Windows script host; Java or VB script); 
-  * [[guide_dotnet|Guide for using WinSCP from .NET]] (.NET; C# or VB.NET); +  * [[guide_dotnet|*]] (.NET; C# or VB.NET); 
-  * [[guide_interpreting_xml_log|Guide to interpreting XML log for advanced scripting]] (.NET, C#).+  * [[guide_interpreting_xml_log|*]] (.NET, C#). 
 + 
 +==== [[xslt]] Transforming XML Log to Text Output Using XSLT Transformation ==== 
 +You can use XSLT transformation to convert the %%XML%% log to plain text output (or any other format). 
 + 
 +For example to generate a plain text list of successfully downloaded files from the following %%XML%% log (''log.xml''): 
 + 
 +<code xml> 
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<session xmlns="http://winscp.net/schema/session/1.0" name="user@host" start="2021-12-03T06:45:57.008Z"> 
 +  <download> 
 +    <filename value="/path/file1.txt" /> 
 +    <destination value="C:\path\file1.txt" /> 
 +    <size value="2022" /> 
 +    <result success="true" /> 
 +  </download> 
 +  <download> 
 +    <filename value="/path/file2.txt" /> 
 +    <destination value="C:\path\file2.txt" /> 
 +    <size value="5782" /> 
 +    <result success="true" /> 
 +  </download> 
 +</session> 
 +</code> 
 + 
 +use the following %%XSLT%% (''download.xslt''): 
 + 
 +<code xml> 
 +<?xml version="1.0" encoding="UTF-8"?> 
 +<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:winscp="http://winscp.net/schema/session/1.0"> 
 +    <xsl:output method="text" encoding="UTF-8"/> 
 +    <xsl:strip-space elements="*"/> 
 +    <xsl:template match='winscp:download[winscp:result[@success="true"]]/winscp:filename'> 
 +        <xsl:value-of select="@value"/> 
 +        <xsl:text>&#xa;</xsl:text> 
 +    </xsl:template> 
 +</xsl:stylesheet> 
 +</code> 
 + 
 +You can execute it using any %%XSLT%% processor: 
 + 
 +  * Microsoft ''msxsl.exe'' (deprecated, but [[https://web.archive.org/web/20200202112313/https://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=21714|available from Internet Archive]]): \\ <code> 
 +msxsl.exe log.xml download.xslt 
 +</code> 
 +  * [[http://xmlsoft.org/|Libxml2]] ''xsltproc.exe'': \\ <code> 
 +xsltproc.exe download.xslt log.xml 
 +</code> 
 + 
 +The output will be: 
 + 
 +<code> 
 +/path/file1.txt 
 +/path/file2.txt 
 +</code>
 +For a more complex example, see [[script_custom_listing_format_csv#scripting|*]].

Last modified: by martin

Documentation

Support

Associations

Follow Us