logging_xml » Revisions »

Differences

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

logging_xml 2014-10-15 logging_xml 2024-12-02 (current)
Line 1: Line 1:
====== XML Logging ====== ====== XML Logging ======
-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]]. An %%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 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]].
-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 ===== 
-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.
-Overall format of the XML log file follows:+An overall format of the %%XML%% log file follows:
<code xml> <code xml>
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 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.
===== [[operations]] Representing Operations in Log ===== ===== [[operations]] 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.+Every entry in the %%XML%% log represents single physical operation over the session. Typically this would be an operation with remote file.
Single logical operation (in [[scripting|scripting]] or GUI) may actually involve multiple physical operations, each represented with separate log element. For example [[task_upload|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. Single logical operation (in [[scripting|scripting]] or GUI) may actually involve multiple physical operations, each represented with separate log element. For example [[task_upload|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. [[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 ===== ===== [[result]] Representing Results/Errors =====
Line 60: Line 60:
</code> </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.+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: Some errors may not be associated with any operation in the XML log. This particularly happens when:
Line 92: Line 92:
===== [[group]] Grouping Operations for Commands ===== ===== [[group]] Grouping Operations for Commands =====
-When using XML logging together with [[scripting|scripting]], [[#elements|operations]] and [[#result_script|failures]] belonging to the same command can be grouped using parent ''group'' element:+When using the %%XML%% logging together with [[scripting|scripting]], [[#elements|operations]] and [[#result_script|failures]] belonging to the same command can be grouped using parent ''group'' element:
<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]]''
-==== chmod ====+==== [[checksum]] checksum ==== 
 +[[ui_properties#checksum|Calculating a checksum]] of a remote file.  
 + 
 +Elements: 
 +^ Element                  ^ Description ^ 
 +| ''filename''            | Absolute path to a remote file (in ''value'' attribute) | 
 +| ''algorithm''            | Name of a checksum algorithm used (in ''value'' attribute) | 
 +| ''checksum''            | Hex dump of a calculated checksum (in ''value'' attribute) | 
 + 
 +Example: 
 +<code xml> 
 +<checksum> 
 +  <filename value="/home/martin/public_html/index.html" /> 
 +  <algorithm value="sha-1" /> 
 +  <checksum value="bb4dfa9b51d3f6c99b5ec6c12ebf9cade79f43c4" /> 
 +  <result success="true" /> 
 +</checksum> 
 +</code> 
 + 
 +Associated script commands: ''[[scriptcommand_checksum|checksum]]'' 
 + 
 +==== [[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 162: Line 184:
^ Element                  ^ Description ^ ^ Element                  ^ Description ^
| ''filename''            | Absolute path to remote file (in ''value'' attribute) | | ''filename''            | Absolute path to remote file (in ''value'' attribute) |
-| ''permissions''          | Permissions in Unix format ''rwxrwxrwx'' |+| ''permissions''          | Permissions in Unix format ''rwxrwxrwx'' (in ''value'' attribute) |
With [[scp|SCP protocol]] optional boolean attribute ''recursive'' indicates, if permissions were changed recursively with single operation. With [[scp|SCP protocol]] optional boolean attribute ''recursive'' indicates, if permissions were changed recursively with single operation.
Line 177: 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 184: 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 190: 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 196: 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 209: 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) |
 +| ''group''                | File group (in ''value'' attribute) |
Example: Example:
Line 250: 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 267: 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 286: 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 305: 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 329: 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 336: 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 342: 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 348: 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 354: 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 368: Line 415:
===== Schema ===== ===== Schema =====
-XML schema for the XML log is available at:+An %%XML%% schema for the %%XML%% log is available at:
http://winscp.net/schema/session/1.0 http://winscp.net/schema/session/1.0
Line 377: 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 416: Line 463:
===== [[parse]] Interpreting/Parsing ===== ===== [[parse]] Interpreting/Parsing =====
-To parse the XML log, use any XML parser available. 
-If possible, using [[library|WinSCP .NET assembly]] is the preferred approach, which hides away the XML log file from your application.+==== General ==== 
 +To parse the %%XML%% log, use any %%XML%% parser available. 
 + 
 +If possible, using [[library|WinSCP .NET assembly]] is the preferred approach, which hides away the %%XML%% log file from your application.
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: 
 + 
 +  * .NET [[dotnet>system.xml.xsl.xslcompiledtransform|''XslCompiledTransform'' class]], e.g. from PowerShell: \\ <code powershell> 
 +$xslt = New-Object System.Xml.Xsl.XslCompiledTransform 
 +$xslt.Load("download.xslt") 
 +$xslt.Transform("log.xml", "download.txt")</code> 
 +  * [[https://gitlab.gnome.org/GNOME/libxml2/-/wikis/home|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