ShareScan

1. ShareScan Tracing in ShareScan 5.0----------------------------------Analyzing ShareScan trace filesReference and Training material for ShareScan Technical Support and Technical Consultants

2. Topics covered • Tracing principles and background in ShareScan • Enabling tracing / settings ---------------------------------------------------- • Analyzing the exported trace files • TraceViewer tool • Filtering in TraceViewer • Sample filter set walkthrough

3. Introduction • ShareScan core tracing includes – these are all separate type of sources, and possible to filter for them when the trace is opened in the TraceViewer • ShareScan Manager • ShareScan Agent • ScanStation application • WebClient trace (web-based devices – KM, Xerox, ScanFront, HP, simulator) • Administration Console (important when troubleshooting device addition problems) • Connector tracing(has been in separate files in 4.x)

4. What is behind the scenes? .NET service (Manager, Agent) ShareScanTraceUtil.dll .NET Trace collector / listener .NET application (ScanStation, AdminConsole) ShareScanTraceUtil.dll .NET Trace collector / listener Tomcat Service (WebClient) TCP/IP (local) NIF tracing service TCP/IP (local) Unmanaged modules (some connectors) NIFTrace0000.binNIFTrace0001.binNIFTrace0002.binNIFTrace0003.binNIFTrace0004.bin MyTracing.bin Ricoh, Canon MEAP MyTracing.txt

5. Where are these files? Normally they are not needed. You will not be able to find them in Windows Explorer. Use dir /s NIF*.bin command in the below folders In pre-Vista systems they are underC:\Documents and Settings\ On Vista, Win2k8 and Win7 they underC:\Windows\

6. What if tracing service is NOT running? • No ShareScan core functionality is affected • (Obviously) no tracing is possible • The configuration of tracing is not possible (error messages in the Admin Console when saving Tracing service settings / export / etc) • There is one known bug in the NIF tracing service – this causes the service to stop when there is a trace record > 1MByte -> in case of huge number of licenses this can happen. Will be fixed in 5.5 • Normally, performance is not significantly affected, when tracing is enabled. Certainly by default, tracing should be turned off

7. Enable tracing • In Admin Console – Services tab – Tracing Service

8. Settings of the Tracing Service • Configured – enables / disables core tracing • Verbose – enables verbose – this is always REQUIRED in case of any tracing is needed (troubleshooting) • File Size (KB) – size of the internal trace storage – it is NOT the size of the exported TXT format trace! – Must be set to 10000 (10 MB) or above to get sufficient amount of trace • Enabled for all devices – per device control is possible – if enabled, tracing will be performed for all devices • Enabled for all Connector Profiles – per connector/profile control is possible – if enabled, all of the connector tracing will be enabled

9. How to trace a reproducible issue? • Make sure the File Size is set to at least 10 MB • Make sure you have anough disk space (on the drive that is used for internal trace file storage – see slide #5) • Make sure Verbose is enabled • Delete trace files (by using the Delete Trace Files button) before reproducing the issue • Export the trace file to BIN format shortly after reproducing the issue

10. How to trace a randomly occuring or intermittent issue? • Make sure the File Size is set to at least 10 MB • Make sure Verbose is enabled • If the issue is device (or model) specific, make sure tracing service is enabled only for that device • If the issue is connector specific, make sure tracing is enabled only for that connector / profile • Exit the Administration Console when not in use • Try to export the traces ASAP after the issue occured (because the trace files are rolled over to not to exceed the limit specified)

11. Trace export: TXT versus BIN • As both exported from the same internal source, the same information is contained • Both of them is zippable (very well, approx to 10%!) • Development prefers BIN format as it is filterable with the TraceViewer tool – it will be discussed later • TXT is there mostly for the customers to see there is no security / privacy violation happens when sending it out

12. Activity Monitor (exported) It is useful (mostly to see when the issue occured), but it is NOT enough (not replacing any tracing)

13. Some more options to control core tracing • The ShareScan .NET executables (services and applications) have a *.exe.config file (ShareScanManager.exe.config, ShareScanAdminConsole.exe.config, ShareScanAgent.exe.config) • These contain a section like this <switches> <add name="ManagerSwitch" value="Verbose" /> <add name="MgrClientSwitch" value="Verbose" /> <add name="NetworkingSwitch" value="Verbose" /> can be changed to <add name="ImagingSwitch" value="Verbose" /> value=“Information" <add name="CommonSwitch" value="Verbose" /> to reduce the amount <add name="SDKSwitch" value="Verbose" /> <add name="DatabaseSwitch" value="Verbose" /> <add name="LicenseSwitch" value="Verbose" /> can be changed to <add name="ConnectorSwitch" value="Verbose" />value=“Information" <add name="OutputCreatorSwitch" value="Verbose" />to reduce the amount <add name="IDServiceSwitch" value="Verbose" /> <add name="SystemFormsManagerSwitch" value="Verbose" /> </switches> • Restart of the application / service is required to have this in effect!

14. Using the standard .NET file writer • NOT recommended for general use • If, for some reason the NIF Trasing Service is not able run, the following configuration option can be used: • (In the same *.exe.config files mentioned on previous slide) <system.diagnostics> <trace autoflush="true" indentsize="4">         <listeners>           <add name="SHARESCAN_fileListener"type="System.Diagnostics.TextWriterTraceListener" initializeData="ManagerListener.log" />         </listeners>       </trace> . . .

15. Client (device) tracing • Web based devices (Tomcat) – done via the core tracing (NIF) as discussed earlier • Canon MEAP and Ricoh – these devices has a right-click menu option (“Retrieve Trace file”) in the Administration Console • Verbose / non verbose state is determined by the core tracing setting. (Admin Console / Tracing Service) • These trace files are plain text files (zippable!) • Developer level tracing – handled separately on-demand, not part of this discussion

16. Advanced Ricoh device tracing • This method is useful when issues occure at JAR startup or shutdown or when there is an exception error message is shown on the device screen • Create a string registry value under HKEY_LOCAL_MACHINE\SOFTWARE\Nuance\ShareScan\ShareScanManager named as ‘writetoconsole ‘ (w/o quotes) • Set it’s value to ‘true’ (w/o quotes) • Restart ShareScan Manager service • After reproducing the issue on the device, collect the trace file by executing the following command line command:rsh DEVICE_IP mmesg_auto 125 > <LOG_FILEPATH> e.g.rsh 10.140.26.214 mmesg_auto 125 > C:\LOG_FILE.TXT • Note: with this method, the collected trace file will contain information only from the time where the above command above is issued. • To stop tracing, just hit Ctrl+C on the keyboard • The RSH application can be downloaded from the following wesite:http://www.ccs.neu.edu/home/bchafy/rsh_vista.html Just copy the rsh.exe from the zip to a folder that is on the PATH (e.g. C:\Windows)

17. Connector tracing • All basic connector tracing is included in the core (NIF) trace • Some of the connectors have extra tracing options, (Exchange, Worksite, eDocs) these have a file called <connectorName>Store.xml (e.g. ExchangeMailStore.xml)This file is in the following folder:<Application Folder>\Nuance\ShareScan\Connectors\<ConnectorName>\Data\ e.g. C:\ProgramData\Nuance\ShareScan\Connectors\ExchangeMail\Data\ or C:\Documents and Settings\All Users\Application Data\Nuance\ShareScan\Connectors\ExchangeMail\Data depending on the OS

18. Connector tracing • It must contain a special entry (it can happen that the file does not exist, as it contains optional settings only): - <ConnectorNode> - <Item Key="Groups.AllUsers" Type="Nuance.ConnectorStore.UserNode"> - <UserNode> -<Item Key="MAPIServer.EnableLogging" Type="System.Boolean"> <boolean>true</boolean> </Item> </UserNode> </Item> </ConnectorNode> • This setting causes the connector to write more verbose logs to the core trace system (NIF) – no separate file is generated

19. Tomcat logging • The Web Client tracing is redirected to the core (NIF) tracing. Some Apache / Tomcat specific logs are still stored at Program Files\Apache Software Foundation\Tomcat 5.5\logs. Some of them can be relevant when there is a Tomcat installation or startup problem. Most typical problem is the absence / incorrect version of the Java runtime (e.g. a Java runtime or other application installation happened on the same machine and/or changed the system configuration). • The Web Client logs are stored also under Files\Apache Software Foundation\Tomcat 5.5\logs – in the future this will be eliminated. Currently it can be useful if the NIF tracing is not available for some reason.

20. ScanStation tracing • Core tracing via NIF (turn on / off in Admin Console) Special tracing (for scanning) • eCopy Driver for ScanStation (for Xerox) • Data source • Web trace (EIP) • RSD (Recognita Scanner Driver) logging

21. eCopy driver for ScanStation DS • Xerox only • Can be configured by editing the driver configuration file. It is under c:\ProgramData\Nuance\ShareScan\Xerox Driver for ScanStation or c:\Documents and Setting\All Users\Application Data\Nuance\ShareScan\Xerox Driver for ScanStationOpen the config.xml file and modify <tracing mode="0" /> to <tracing mode="2" />The trace file is called “tracing.log” and it is written in the same directory • Please do not forget to turn off tracing when you have successfully generated the necessary logfiles, because logging can have significant performance impact

22. eCopy driver for ScanStation web trace • Xerox only, traces the EIP related communication with the Xerox device • Find the actions.jsp file under c:\Program Files\Apache Software Foundation\Tomcat 5.5\webapps\eCopy-Xerox • Open the file and modify line 14 from boolean debugMode = false;boolean debugMode = true; • Restart Apache service • Please do not forget to turn off tracing when you have successfully generated the necessary logfiles, because logging can have significant performance impact

23. Special ScanStation tracing to file • In some exceptional cases when NIF tracing is not on / available, tracing can be enabled separately: • c:\ProgramData\Nuance\ShareScan\ScanStation Client\Config.xml<LOGGING fileName="scanstation.log" writeToFile="true" writeToConsole="false" Verbose="true" />

24. RSD tracing • In some of the cases the application log is not enough to investigate a problem. In case of scanner driver related issues we also need RSD logs. • You can turn on logging in the Scanner.ini. • Close the ScanStation application • You can find Scanner.ini in c:\ProgramData\Nuance\ShareScan\ScanStation Clientif you use Windows 7 and Vista or in c:\Documents and Settings\All Users\Application Data\Nuance\ShareScan\ScanStation Clientif you use Windows XP.

25. RSD tracing – scanner.ini Open Scanner.ini and • find [RSD] section and remove the “_” character from the beginning of “_LogLevel=127” to turn RSD loggin on, • find [Wizard] section and remove the “_” character from the beginning of “_LogLevel=127” to turn Wizard logging on, • find [ISIS] section and remove the “_” character from the beginning of “_LogLevel=127” to turn ISIS logging on, • find [TWAIN] section and remove the “_” character from the beginning of “_LogLevel=127” to turn TWAIN logging on. Start the ScanStation application and try to reproduce the bug you are investigating. Close the application to make sure, that log files are written and closed properly.

26. RSD tracing – trace files The folder of the trace files are specified in the scanner.ini file, like this example illustrates: [RSD] LogFileU=C:\ProgramData\Nuance\ShareScan\ScanStation Client\RnRSDu.LOG • Find all files with .log extension in that folder and send them to the developer or contact person or attach them to the bug entry • After creating the log files do not forget to write the “_” characters back to scanner.ini file else the application will keep writing trace files and it may have a performance impact

27. Q&A

28. Analyzing the exported trace files • As the TXT and BIN format contains the same, it is possible to walkthrough / search the TXT file for the same, but the recommended way is to use the TraceViewer (TV) tool (with the BIN format) • TV can be ‘installed’ by simply unzipping the package to anywhere on a PC (ShareScan is NOT required) • TV is a resource (memory / display) intensive application (WPF), it may run slowly on older PCs with small amount of memory • It is also included in the installed ShareScan\Tools folder

29. TraceViewer • The UI is unusual a bit – please use the tooltips provided (on the popup dialogs of the application) Menu button Exit button Search control

30. Menu items – opening / collecting Open trace file. The appearing dialog is able to handle the recently used file list (history) too Run in trace listener mode. If the NIF Tracing Service is stopped, then the TraceViewer is able to collect and display all the (core) traces on the fly. (No export etc is required). Can be useful when troubleshooting some configuration issue, used with some filtering (see later) Information about the currently open trace file Color / theme selector – dark is not recommended on most of the displays Like the middle button, but the TraceViewer can be on a remote machine. Mostly for development puposes. Exits the TraceViewer application

31. Open trace file dialog You need to click the small triangle to drop down the folder / file list History (previously opened trace files) Remove the selected file from the list

32. Menu items - filtering Saving filtered records. When sending traces to development it is not recommended to use it. However, if there is a set of records showing a problem clearly, it is a help for development to have the filtered version too Filtering – creation, editing and selection of filters. Filters determine what is displayed from the whole binary tracing. Configuration option what data items of the records are displayed on the main list Short help to filter creation Highlighting – enables the setup of ‘highlight filters’ to ease the recognition of different events in the trace list

33. Filter management dialog • Purpose of filters: • Display filtering (show only the records you want to see) • Record highlighting Filters can be created with SQL-like queries (simpler ones) Edit selected filter Create new filter Remove selected filter Or filters can be created in C# (more complex ones)

34. Filter editing dialog Filter name – use a descriptive name SQL-like query editor or C# editor window Filter type selector radio buttons Filter syntax check button. Note: a filter CAN fail runtime even if it is syntactically correct! Example: … threadname = ‘watcherThread’ -> can fail if threadName is NULL Help for SQL or C# filter creation – necessary to use to create proper filter conditions

35. Fields can be used in filters traceid – the ID can be shown on the beginning of every trace record. Example: SELECT * where traceid > 26850800 eventtype – can be one of the following values:‘critical’, ‘error’, ‘ warning’, ‘information’, ‘verbose’SELECT * where eventtype = ‘error’(filters for records having type ‘error’) source – internal category name of the trace record (Networking, Database, IDService, Manager, MgrClient, Imaging, etc) – its hard to specify which one you’re interested in, but there are categories that can be omitted in general (Networking, Database)

36. Fields continued… message, data– textual part of the trace record. In general you can use equality or ‘like’ type conditions:SELECT * where message like 'Data received:' or message like 'Processing image:‘(filters for records containing the above strings) datetime – timestamp in the format MM/dd/yyyy hh:mm:ssExample: SELECT * where datetime > DATE[09/29/2011 15:44:42] (filters records having timestamp after the included date-time)

37. Fields continued… threadid – ID of the thread. As in ShareScan the “main processing” of a client is related to a single thread, it can be useful to filter to a single thread ID (e.g. when having a trace file of a multi-device environment). procname – name of the process from where the tracing happens. This can be an important filtering conditions as multiple processes (applications, services) perform tracing to the same trace output. Most probably one would filter for the process name ‘ShareScanManager’. Example:SELECT * where procname = 'ShareScanManager'

38. Fields continued + C# filters threadname – Name of the thread the tracing happens from. In case of some models the thread name is descriptive and it is useful to filter for it. Make sure you check for null before comparison, as this field is nullable. Example:namespace akarmi{public class Filter : ITraceFilterPeer   {      /*If the function returns with false, the record disappears from the record set.*/publicboolFilterRecord(ITraceRecord record)      {         // Deafult trace filter, displays all records.         return (record.Message.Contains("<COSTRECOVERY>") ||          record.Message.Contains("ECOPY_LOCK") ||          (record.ThreadName != null && record.ThreadName.Contains( "eCopy Cost Recovery Service Thread"))) ;      }      /*The function returns with the final record set.*/public IEnumerable<ITraceRecord> FilterRecordSet(IEnumerable<ITraceRecord> records, Func<ITraceRecord> recordGenerator)      {         // Deafult trace filter, transfer records without modification.         return records;      }   }}

39. Usage of filters – best practices • (Create and) select the filter that enables the displaying of all the records you’re interested in (but filters out everything you don’t want to see at all). Example: enable Manager tracing records except the Networking messages and the Licensing messages – because only a single display filter can be selected. Example: C# filterreturn record.ProcName.StartsWith("ShareScanManager") &&  !record.Source.StartsWith("Network")  &&  !record.Source.StartsWith("Database"); • Add highlight filters for ALL of the records you’re interested in – then you’ll be able to scan through the trace records and visually ‘filter’ what you’re interested in

40. Using pre-fabricated (sample) filters • Development has a set of filters that can be used (and modified) by support / TCs • These can be delivered in a ZIP file, that needs to be extracted to the following folder:C:\Users\<user_name>\AppData\Local\Nuance\NIFTraceView\1\Filterse.g. C:\Users\john_smith\AppData\Local\Nuance\NIFTraceView\1\Filters • Next time TraceViewer starts, the new filters will be available

41. Sample filters from dev vol. #1 • ManagerAndNotNetworkingAndDBDisplays only the Manager traces except the Networking and Database access trace messages • ClientServerCommunicationDisplays / highlights the XML messages between the Manager and the client • ConnectorClickDisplays / highlights the XML messages representing the connector button click • CreateOutputCreatorClientDisplays / highlights the trace records that is about the usage of the Output Creator worker process • NextButtonClickDisplays / highlights the XML messages representing the “Next” button click • PagePulledInDisplays / highlights the XML messages representing the page scan events

42. Sample filter / highlight set By using the previous set:

43. Online demo of filtering / tracing

44. Thank you for your attention!