Overview

The Log Collection service and the File Retrieval (DimeGetFile) service provide retrieval of trace files and logs.

Log Collection

The Log Collection service provides an API for querying and transferring server and system log files to a FTP server for troubleshooting purposes.

Use the Log Collection WSDL:

https://ServerName:8443/logcollectionservice2/services/LogCollectionPortTypeService?wsdl

Replace ServerName with the Cisco Unified Communications Manager (Unified CM) server name or IP address.

DimeGetFileService

The DimeGetFileService API is used to gather a server and system log file through the standard Direct Internet Message Encapsulation (DIME) protocol.

Use the DimeGetFileService WSDL: https://ServerName:8443/logcollectionservice/services/DimeGetFileService?wsdl.

Replace ServerName with the Cisco Unified CM server name or IP address.

LogCollection

LogCollectionPort listNodeServiceLogs

The listNodeServiceLogs method returns the node names in the cluster and the lists of service names.

listNodeServiceLogs Request Format

<!--LogCollection API - ListNodeServiceLogs - Request-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.cisco.com/ast/soap">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:listNodeServiceLogs>
         <soap:ListRequest></soap:ListRequest>
      </soap:listNodeServiceLogs>
   </soapenv:Body>
</soapenv:Envelope>

The input is a ListRequest handle.

Parameter Description
ListRequest The value can be left blank.

listNodeServiceLogs Response Format

<!--LogCollection API - ListNodeServiceLogs - Response-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:listNodeServiceLogsResponse xmlns:ns1="http://schemas.cisco.com/ast/soap">
         <ns1:listNodeServiceLogsReturn>
            <ns1:name>cucm3</ns1:name>
            <ns1:ServiceLog>
               <ns1:item>Cisco Trust Verification Service</ns1:item>
               <ns1:item>Cisco CallManager Cisco IP Phone Services</ns1:item>
               <ns1:item>Cisco CTIManager</ns1:item>
               <ns1:item>Cisco License Manager</ns1:item>
               <ns1:item>Cisco CDR files on Publisher Processed</ns1:item>
               <ns1:item>SOAP - Diagnostic Portal Database Service</ns1:item>
               <ns1:item>Cisco CDR Agent</ns1:item>
               <ns1:item>Cisco Bulk Provisioning Service</ns1:item>
               <ns1:item>Cisco Messaging Interface</ns1:item>
               <ns1:item>Cisco CallManager</ns1:item>
               ...
               <ns1:item>Cisco Audit Logs</ns1:item>
               <ns1:item>Kerneldump Logs</ns1:item>
               <ns1:item>Cisco ControlCenter CLI</ns1:item>
               <ns1:item>SELinux logs</ns1:item>
               <ns1:item>Cisco Discovery Responder Service</ns1:item>
               <ns1:item>Cisco SSO</ns1:item>
            </ns1:ServiceLog>
            <ns1:SystemLog xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
         </ns1:listNodeServiceLogsReturn>
      </ns1:listNodeServiceLogsResponse>
   </soapenv:Body>
</soapenv:Envelope>

The response is an array of NodeServiceLogList consisting of:

Parameter Description
name The name of the server.
ServiceLog A list of all service logs for each Cisco Unified CM node.
SystemLog The log files available in the system, dependent on the activated Cisco Unifed CM services.

LogCollectionPort selectLogFiles

The selectLogFiles method lists or requests 'push' delivery of service log files based on a selection criteria.

If the JobType element is set to DownloadtoClient, then the service will simply retrieve a list of matching available log files. Note: no files are actually downloaded.

If the JobType element is set to PushtoSFTPServer, then the system will attempt to sign into the SSH-FTP server with the provided credentials and deliver the log files. Before using the PushtoSFTPServer option, make sure the target SSH-FTP server is running and accessible.

The file collection time range can be:

  • Absolute
    • For absolute time range, the following elements must have valid values:
    • ToDate
    • FromDate
    .
  • Relative
    • For relative time range, the following elements must have valid values:
    • RelText
    • RelTime

selectLogFiles Request Format

<!--LogCollection API - SelectLogFiles - Request-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.cisco.com/ast/soap">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:selectLogFiles>
         <soap:FileSelectionCriteria>
            <soap:ServiceLogs>
               <soap:item>Cisco AMC Service</soap:item>
               <soap:item>Event Viewer-Application Log</soap:item>
            </soap:ServiceLogs>
            <soap:SystemLogs>
               <soap:item></soap:item>
            </soap:SystemLogs>
            <soap:SearchStr></soap:SearchStr>
            <soap:Frequency>OnDemand</soap:Frequency>
            <soap:JobType>PushtoSFTPServer</soap:JobType>
            <soap:ToDate>08/23/14 11:59 PM</soap:ToDate>
            <soap:FromDate>08/22/14 12:00 AM</soap:FromDate>
            <soap:TimeZone>Client: (GMT-0:0) Greenwich Mean Time</soap:TimeZone>
            <soap:RelText>None</soap:RelText>
            <soap:RelTime>0</soap:RelTime>
            <soap:Port>22</soap:Port>
            <soap:IPAddress>your-server.server.com</soap:IPAddress>
            <soap:UserName>username</soap:UserName>
            <soap:Password>password</soap:Password>
            <soap:ZipInfo>true</soap:ZipInfo>
            <soap:RemoteFolder>/tmp</soap:RemoteFolder>
         </soap:FileSelectionCriteria>
      </soap:selectLogFiles>
   </soapenv:Body>
</soapenv:Envelope>

The selectLogFiles request takes a FileSelectionCriteria object as input.

FileSelectionCriteria consists of (all elements are required, though some may be empty):

Parameter Description
ServiceLogs The names of the service logs. A list of values can be found by using listNodeServiceLogs.
SystemLogs The names of system logs. A list of values can be found by using listNodeServiceLogs.
SearchStr A non-null string used to perform the log file search.
Frequency The log collection frequency:
  • OnDemand
  • Daily
  • Weekly
  • Monthly
JobType The collection type:
  • DownloadtoClient - retrieve (only) the list of matching logs
  • PushtoSFTPServer - deliver the logs to the specified SSH-FTP server. The following elements must have valid values:
    • Port
    • IPAddress
    • UserName
    • Password
    • ZipInfo
    • RemoteFolder
ToDate The end date for log collection. The format is mm/yy/dd hh:mm AM/PM.
FromDate The start date for file collection, required if absolute time range is used. The format is mm/yy/dd hh:mm AM/PM.
TimeZone The time zone value. A complete listing of values is available in the Unified CM Administration UI in the Date/Time Group Configuration settings. The format is Client: (GMT ±n) Name of the time zone, where n is the offset time of the specified time zone and GMT. For example:
  • Client:(GMT-0:0) Greenwich Mean Time
  • Client:(GMT-8:0) Pacific Standard Time
RelText The file collection time range. The available options are:
  • None
  • Minutes
  • Hours
  • Weeks
  • Months
  • Days
RelTime The file collection time value, from the specified time up to present with the available range 1 to 100. For example, if RelText = Day and RelTime = 1, then all files modified in the previous day are collected.
Port The port number of the SFTP or FTP server.
IPAddress The IP address of the SFTP or FTP server.
UserName The username of the service administrator for the SFTP or FTP server.
Password The password of the service administrator for the SFTP or FTP server.
ZipInfo Indicates whether to compress the files during collection, applicable only with PushtoSFTPServer. The available options are:
  • true: The files are compressed
  • false: The files are not compressed
Only false is supported.
RemoteFolder The remote SSH-FTP server folder where the files will be uploaded.

selectLogFiles Response Format

<!--LogCollection API - SelectLogFiles - Response-->
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Body>
      <ns1:selectLogFilesResponse xmlns:ns1="http://schemas.cisco.com/ast/soap">
         <ns1:ResultSet>
            <ns1:SchemaFileSelectionResult>
               <ns1:Node>
                  <ns1:name>your-server.server.com</ns1:name>
                  <ns1:ServiceList>
                     <ns1:ServiceLogs>
                        <ns1:name xsi:nil="1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>
                        <ns1:SetOfFiles>
                           <ns1:File>
                              <ns1:name>AlternateSyslog</ns1:name>
                              <ns1:absolutepath>/var/log/active/syslog/AlternateSyslog</ns1:absolutepath>
                              <ns1:filesize>1844320</ns1:filesize>
                              <ns1:modifiedDate>Wed Oct 01 18:05:01 CDT 2014</ns1:modifiedDate>
                           </ns1:File>
                           <ns1:File>
                              <ns1:name>amc00043.log</ns1:name>
                              <ns1:absolutepath>/var/log/active/cm/trace/amc/log4j/amc00043.log</ns1:absolutepath>
                              <ns1:filesize>1048589</ns1:filesize>
                              <ns1:modifiedDate>Tue Sep 30 22:13:44 CDT 2014</ns1:modifiedDate>
                           </ns1:File>
                        </ns1:SetOfFiles>
                     </ns1:ServiceLogs>
                  </ns1:ServiceList>
               </ns1:Node>
            </ns1:SchemaFileSelectionResult>
         </ns1:ResultSet>
      </ns1:selectLogFilesResponse>
   </soapenv:Body>
</soapenv:Envelope>

The selectLogFiles method returns a FileSelectionResult object containing the list of matching file names and their location on the server. The FileSelectionResult object consists of:

Parameter Description
name The name of the node.
SetOfFiles Log file information

Log file information contains:

Paramter Description
name Name of the log file
absolutepath The absolute path to the log file on the system, such as /var/log/active/syslog/AlternateSyslog
filesize The size of the log file
modifiedDate Date the log file was last modified

DimeGetFile

DimeGetFileService getOneFile

DIME is a specification that allows you to send requests and receive responses via HTTP. The getOneFile method specifies a single file to retrieve. The file is returned by DIME encapsulation. The response includes the entire file in DIME encapsulation.

getOneFile Request Format

<!--DIME Get File - getOneFile API Request-->
<soapenv:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.cisco.com/ast/soap/">
   <soapenv:Header/>
   <soapenv:Body>
      <soap:GetOneFile soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
         <FileName>/var/log/active/syslog/messages</FileName>
      </soap:GetOneFile>
   </soapenv:Body>
</soapenv:Envelope>
Parameter Description
FileName The absolute file name of the file to be collected from the server. For example, /var/log/active/tomcat/logs/ccmservice/ccmservice00010.log. The selectLogFiles response returns the absolute file name in the absolutepath value.

getOneFile Response Format

<!--DIME Get File - getOneFile API Response-->
Content-Type: text/xml; charset=UTF-8
Content-Transfer-Encoding: binary
Content-Id: <80DB2208357F8BD76EE58C1967C79E0D>

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <soapenv:Body>
        <ns1:GetOneFileResponse soapenv:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:ns1="http://schemas.cisco.com/ast/soap/">
            <DataHandler href="cid:BC0EDD33C6D0C7A1F6286E3691F95332" xsi:type="ns2:DataHandler" xmlns:ns2="DimeGetFileService"/>
        </ns1:GetOneFileResponse>
    </soapenv:Body>
</soapenv:Envelope>

Content-Type: application/octet-stream
Content-Transfer-Encoding: binary
Content-Id: <BC0EDD33C6D0C7A1F6286E3691F95332>

Mar  5 04:01:01 cucm3 rsyslogd: [origin software="rsyslogd" swVersion="5.8.10" x-pid="7982" x-info="http://www.rsyslog.com"] rsyslogd was HUPed
Mar  5 04:01:01 cucm3 rsyslogd: [origin software="rsyslogd" swVersion="5.8.10" x-pid="7982" x-info="http://www.rsyslog.com"] rsyslogd was HUPed
Mar  5 04:01:02 cucm3 rsyslogd: [origin software="rsyslogd" swVersion="5.8.10" x-pid="7982" x-info="http://www.rsyslog.com"] rsyslogd was HUPed
Mar  5 04:01:02 cucm3 rsyslogd: [origin software="rsyslogd" swVersion="5.8.10" x-pid="7982" x-info="http://www.rsyslog.com"] rsyslogd was HUPed
Mar  5 04:01:02 cucm3 rsyslogd: [origin software="rsyslogd" swVersion="5.8.10" x-pid="7982" x-info="http://www.rsyslog.com"] rsyslogd was HUPed
Mar  5 04:01:02 cucm3 rsyslogd: [origin software="rsyslogd" swVersion="5.8.10" x-pid="7982" x-info="http://www.rsyslog.com"] rsyslogd was HUPed
Mar  5 04:01:03 cucm3 rsyslogd: [origin software="rsyslogd" swVersion="5.8.10" x-pid="7982" x-info="http://www.rsyslog.com"] rsyslogd was HUPed
Mar  5 04:01:03 cucm3 logrotate: ALERT exited abnormally with [1]
Mar  5 04:01:06 cucm3 ntpRunningStatus.sh: Response from 'ntpdate -q': server 172.20.132.241, stratum 0, offset 0.000000, delay 0.00000#012 5 Mar 04:01:06 ntpdate[6412]: no server suitable for synchronization found.

The return value specifies the file name, but the file name has a temporary file name. After the file is downloaded, replace the file name with the actual file name from the server.

Parameter Description
DataHandler A temporary file name. The string following cid is the temporary file name.
XML