Logging

This section contains a detailed explanation how the log output for Impact Acquire devices is configured and how it works in general.

It is only necessary to understand all the details in this chapter if the default configuration shall be modified e.g. by a script or if a custom configuration shall be created and added to an installation package of an application. Otherwise using DeviceConfigure can be used to set up logging according to an application's needs. How to do this is explained in the manual dealing with the GUI applications of Impact Acquire (e.g. https://www.balluff.com/en-de/online-manuals-mv)

mvDebugFlags.mvd - The Activation Flags For Logging

The key to all *.log-output is a parameter file called mvDebugFlags.mvd. The file itself is an XML file containing sections for each library and each device the user wants to get *.log output from. The first line in this file should be the XML declaration and therefore will look somehow like this:

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>

To form a well formed and valid XML document a root item must be introduced. For this file it will be a tag call DebugWriterList. The simplest structure this file can have therefore will be something like this:

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>
<DebugWriterList>
</DebugWriterList>

Within this root item an arbitrary number of log sections (tag name: DebugWriter ) can be placed. All other XML tags will be ignored.

The D ocument T ype D escription (DTD) for this file therefore can roughly be expressed like this:

<!DOCTYPE DebugWriterList [
  <!ELEMENT DebugWriterList (DebugWriter*)>
  <!ELEMENT DebugWriter (#PCDATA)>
]>

Log Sections

One log section in the *.mvd-file looks more or less like this:

<DebugWriter
  name="mvDeviceManager"
  flags="111111"
  outputmask="110"
  outputfile="STDLOGDIR\mvDeviceManager.xml"
  clearFile="1">
</DebugWriter>

A complete parameter file to define and configure *.log output for a certain module therefore could look like this:

<?xml version="1.0" encoding="ISO-8859-1" standalone="yes" ?>
<DebugWriterList>
  <DebugWriter
    name="mvDeviceManager"
    flags="111111"
    outputmask="110"
    outputfile="STDLOGDIR\mvDeviceManager.xml"
    clearFile="1">
  </DebugWriter>
</DebugWriterList>

The meaning of the individual attributes will be explained in the following sub sections.

The order of appearance of the attributes is not defined and not all attributes are required. The following sample will all be valid *.log-configuration:

<DebugWriterList>
  <DebugWriter
    name="mvVirtualDevice-666"
    flags="111100"
    outputmask="100"
    outputfile="STDLOGDIR/mvVirtualDevice"
    clearFile="1">
  </DebugWriter>
  <DebugWriter
    flags="111100"
    outputmask="100"
    name="mvVirtualDevice-667"
    timestampFormat="relative_ms"
    outputfile="STDLOGDIR/mvVirtualDevice">
  </DebugWriter>
  <DebugWriter
    outputfile="STDLOGDIR/mvVirtualDevice"
    name="mvVirtualDevice-668"
    flags="111100"
    clearFile="1">
  </DebugWriter>
  <DebugWriter
    outputfile="STDLOGDIR/mvVirtualDevice-669"
    name="mvVirtualDevice-669"
    flags="111100"
    clearFile="1"
    stylesheet="none" >
  </DebugWriter>
  <DebugWriter
    outputfile="STDLOGDIR/mvVirtualDevice"
    name="mvVirtualDevice-670"
    flags="111110"
    clearFile="1"
    stylesheet="myStyleSheet.xsl"
    fileFormat="xml" >
  </DebugWriter>
  <DebugWriter
    outputfile="STDLOGDIR/mvVirtualDevice"
    name="mvVirtualDevice-671"
    flags="111100"
    clearFile="1"
    fileFormat="text">
  </DebugWriter>
  <DebugWriter
    flags="111100"
    outputmask="010"
    name="mvVirtualDevice-672">
  </DebugWriter>
</DebugWriterList>

Note

As it can be seen it the sample from above several devices / log configurations can use the same file to send their messages to.

The complete DTD for log configuration files looks like this:

<!DOCTYPE DebugWriterList [
  <!ELEMENT DebugWriterList (DebugWriter*)>
  <!ELEMENT DebugWriter (#PCDATA)>
  <!ATTLIST DebugWriter
    name CDATA #REQUIRED
    flags CDATA #REQUIRED
    outputmask CDATA "010"
    outputfile CDATA #IMPLIED
    clearFile CDATA "1"
    fileFormat (xml | text | mvlog) 'xml'
    timestampFormat (relative_ms | local_ms) 'local_ms'
    stylesheet CDATA "mvIMPACT_acquireLogFile.xsl"
  >
]>

Attribute "name"

The name attribute is the name of the library (without extension) or the device for which *.log-output shall be generated. In this case, it's the mvDeviceManager library. For devices the name will build from the value of the property 'Family' in the device list, a dash ('-') and the current device ID. So e.g. mvVirtualDevice-666 would specify the log-section for a device belonging to the product family group mvVirtualDevice and has been assigned a device ID of 666. In the parameter file the corresponding section would look somehow like this:

<DebugWriter
    name="mvVirtualDevice-666"
    flags="111111"
    outputmask="110"
    outputfile="STDLOGDIR\mvVirtualDevice-666"
    clearFile="1">
</DebugWriter>

Note

This attribute is required.

Attribute "flags"

The flags attribute is a string containing either 0 or 1 for controlling the log output. For most of the flags, 0 means that these *.log-messages will NOT be written to the log output and 1 that the messages will be sent to the log output. For the first digit (the 8th from the right), a 1 means that the time stamp format should be output as a monotonously incremented number of milliseconds after a OS-specific time, like for all versions of Impact Acquire before 2.51, while a 0 means a local time with milliseconds precision.

From right to left the numbers have the following meaning:

• information (these type of messages will only be available in debug builds)
• important information (these type of messages will only be available in debug builds)
• warning
• error
• fatal error
• log message

So something like this:

flags="001110"

will result in messages internally classified as important information (first "1" from the right), warning (second "1" from the right) or error (third "1" from the right) to be sent to the output.

Note

This attribute is required.

Attribute "outputmask"

Log messages can be sent to multiple destinations. where the output will be sent to can be defined by the attribute outputmask. It contains three digits (either "0" or "1") to activate certain destinations. The rightmost digit defines the system's standard output, the digit in the middle the system's standard debug output and the digit on the left a file.

From right to left the flags have the following meaning:

• system standard output
• system debug output
• file

So

outputmask="110"

results in log messages to be sent to the system's standard debug output AND a file while

outputmask="001"

would send the log messages to the system's standard output only.

Note

This attribute is optional. If omitted messages will only be sent to the system debug output

Attribute "outputfile"

If log messages shall be sent to a file, this attribute should contain the name of the output file.

If the name of the output file starts with STDLOGDIR then the file will be created in the same folder where the file mvDebugFlags.mvd is located after the installation.

So

outputfile="STDLOGDIR/mvDeviceManager.xml"

on Windows® will send all log messages to "%PUBLIC%/Documents/Balluff/ImpactAcquire/Logs" (or "%MVIMPACT_ACQUIRE_DATA_DIR%/Logs" which will point to the same folder), while on Linux the log messages can be found in /opt/ImpactAcquire/data/logs.

Once a device has been initialized the name and the full path to the log file can be obtained by reading the value of the property LogFile located in the dmltInfo list.

Note

It is NOT necessary to specify the file extension xml explicitly. If the file name does not end with xml it will be appended automatically. This however implies, that only the XML format is currently supported and later will be the default.

This attribute is optional. If omitted no messages will be sent to a file and no file will be created.

Attribute "clearFile"

Defines if new information is appended at the end of an existing file from a previous session ('0' ), or if a new file shall be created for each session ('1' ) overwriting existing files.

Note

• The term session means the time the device drivers library is in process memory, which might be longer then the time the device is actually initialized. To remove a device driver from process memory, the device manager must be closed.
• Appending to existing files is slow and might produce very large files when used over a long period of time which might affect the overall performance of the system. So using the append feature is an option, but it is NOT recommend. Only use it if necessary! This attribute is optional. If omitted existing files will be overwritten.

Attribute "backupPreviousFile"

Defines if upon creation of a new (clean) log file a backup (using the *.bak extension) of the file from a previous session with the same name shall be created ('1' ), or not ('1' ).

Note

The term session means the time the device drivers library is in process memory, which might be longer then the time the device is actually initialized. To remove a device driver from process memory, the device manager must be closed.

Attribute "fileFormat"

Defines the output format for the log file output. It can be

• text for txt-style output.
  Example text file log entry with local time:

  t="10:44:57.967" td="    160202" procId="     23680" threadId="     26292" df="31":mvPropHandlingLibDone: Overall time this lib was in process memory: 160.20180 

• xml for XML file output with a user definable stylesheet.
  Example xml file log entry with milliseconds timestamp:

  <logmsg ts="20756546" td="13364406" procId="16940" threadId="13824" df="31" msg="LogMsgWriter::~LogMsgWriter: Process 16940 disconnected from logger mvPropHandling." /> 

• mvlog to create log files that can be displayed using mvLogFileViewer.html.
  Example mvlog file log entry with local time:

  <logmsg t="10:42:19.397" td="1048" procId="23680" threadId="26292" df="5" msg="registerDrivers: Detected mvGenTLConsumer.dll(version 2.50.1.3767)." /> 

If this parameter is not present, XML file output will be used. Only in this mode the stylesheet parameter will be taken into account.

Note

This attribute is optional. If omitted the XML format will be used.

Attribute "timestampFormat"

Defines the timestamp format used by the log messages. Valid values for this attribute are

• relative_ms (in this mode the timestamps represent the number of milliseconds since the system has been started (Windows) or since the Unix epoch (01.01.1970))
• local_ms (in this mode the timestamps represent the actual local system time with millisecond precision)

Note

This attribute is optional. If omitted the local system time format will be used.

Attribute "stylesheet"

Defines if a stylesheet shall be embedded into the log-file. If no stylesheet shall be referenced by the resulting log-file this attribute must be set to none. Otherwise the value of this attribute defines the name of the stylesheet file that will later be used to transform the log-file into the desired output format.

Note

This attribute is optional. If omitted, the standard stylesheet mvIMPACT_acquireLogFile.xsl will be embedded in the *.log-file. This stylesheet is part of the installation and will be installed to the same directory as the *.mvd-file.

Locating The File On Windows®

mvDebugFlags.mvd on Windows® will be installed to

• "%PUBLIC%/Documents/Balluff/ImpactAcquire/Logs" or "%MVIMPACT_ACQUIRE_DATA_DIR%/Logs" which will point to the same folder

whenever a device driver is installed. On Windows® this is the one and only location, where this file can be located. Otherwise, no log-files will be created.

Locating The File On Linux

Whenever a Linux driver package is installed, the mvDebugFlags.mvd file will be installed in the folder $MVIMPACT_ACQUIRE_DATA_DIR/logs which is by default /opt/ImpactAcquire/data/logs.

Locating The File On macOS

After installing a local copy of Impact Acquire via script install_local_ImpactAcquire.sh, there already is an environment variable MVIMPACT_ACQUIRE_DATA_DIR which points to a local folder containing the necessary sub-structure for logging, usually at ~/ImpactAcquire_Data. In sub-folder logs, you find the file mvDebugFlags.mvd. Otherwise, copy mvDebugFlags.mvd from the apps folder of Impact Acquire to your work folder. E.g. if you work in /home/workspace and you execute your app from this folder, a copy of mvDebugFlags.mvd must be available there if you want to use logging.

Windows®

Logging During Installation

All installation packages shipped on Windows® platforms internally make use of the MSI (Microsoft Windows® Installer™) technology. Most of the packages therefore will be *.msi files while some packages are distributed as so called bootstrappers which will be *.exe files. In case you ever run into trouble during the installation of a packages before contacting the support team please create a log-file of the installation process. This can be achieved like this:

// for *.msi files
msiexec /i myInstaller.msi /L*v nameOfTheLogFile.log
// for *.exe files
myInstaller.exe /log nameOfTheLogFile.log