About Logging Agent for Windows and Linux

Overview

The Zebra Logging Agent is a utility that will log scanner related events to a command prompt window and/or text file. The events that can be logged through the Logging Agent are defined in the file "Logging-Agent-Confg.xml" and their properties can be changed depending on need. The Logging Agent accesses scanner devices through the Zebra CoreScanner Service for Windows or Linux which must first be installed and running.

Logging Agent bundled with Windows and Linux SDKs.

  1. The Logging Agent allows a 3rd party management console, like Microsoft’s SCCM, to track scanner information including the scanner’s health by parsing a Logging Agent generated log file.
  2. The Logging Agent will output a log file, one file per scanner/host.
  3. The Logging Agent is configurable and can document one or all of the following information:

    1. Asset information
    2. Statistics for example battery charge level or UPCs scanned
    3. Firmware failures and or firmware success
    4. Parameter value(s) changed. Achieved by tracking parameter 616 (config file name changed to "Modified")
    5. Scanned barcode data (all scanned items)
    6. Scan avoidance for MP7000
  4. The logging agent can have its output stored locally on its host PC or output to a network shared folder.

Supported Windows Operating Systems

Logging Agent for Windows support the following Windows versions.

  • Windows 7 32bit
  • Windows 7 64bit
  • Windows 8.1 32bit
  • Windows 8.1 64bit
  • Windows 10 32bit
  • Windows 10 64bit

Supported Linux Distributions

Logging Agent for Linux support the following Linux distributions.

  • Ubuntu 16.04 32bit
  • Ubuntu 16.04 64bit
  • Ubuntu 18.04 64bit
  • Ubuntu 20.04 64bit
  • Debian 9.5 32bit
  • Debian 9.5 64bit
  • CentOS 8.1 64bit
  • SLES 15 64bit

How to Configure Logging Agent

"Logging-Agent-Confg.xml" file is used by the Logging Agent to configure the logging formats and what to log.

XML File


<config>
    <settings>
        <spd_log>
            <!--There could be multiple sinks with different settings defined here. -->
            <sinks>
                <!-- rotating_file_sink_mt: When the max file size is reached, close the file, rename it, and create a new file. Both the max file size and the max number of files are configurable in the constructor.-->
                <sink type="rotating_file_sink_mt" name="rotating_file_sink_mt">
                    <!-- Name of the Log file. %h - Host name , %H - Host ID (Physical address of the first MAC), %u - User name without domain (Ex. AAA) and %U - User name with domain (Ex. AAA@zebra.com. Domain in @ format)-->
                    <property key="log_file_name" value="LogAgent-%h.log" />
                    <!-- This is where the log files will be saved. The path should be valid in order for Logging Agent to create the logs. Logging Agent will not create directories. -->
                    <!--This value can be a network location as well. Eg: value="\\10.225.123.31\Temp\logging-agent-logs"-->
                    <property key="log_file_path" value="logs" />
                    <!-- Max file size in Kilo Bytes (considering 1KB = 1024B). Minimum size is 5KB and if any value less is defined, will be defaulted to the minimum value. -->
                    <property key="max_file_size" value="5120" />
                    <!-- Max file count. The minimum is 1 and anything less or invalid value will be defaulted to 1. -->
                    <property key="max_file_count" value="5" />
                    <!-- Pattern of the single log entry. Please refer https://github.com/gabime/spdlog/wiki/3.-Custom-formatting for more information. -->
                    <property key="log_pattern" value="[%Y-%m-%d %H:%M:%S] %v" />
                    <!-- Log level to be recorded.  2 = INFO, 3 = WARNING, 4 = ERROR, 5 = CRITICAL 6 = LOG_OFF, 0,1 = TRACE,DEBUG (Works only with debug build) -->
                    <property key="log_level" value="2" />
                </sink>
                <sink type="stdout_color_sink_mt" name="stdout_color_sink_mt">
                    <!-- Pattern of the single log entry. Please refer https://github.com/gabime/spdlog/wiki/3.-Custom-formatting for more information. -->
                    <property key="log_pattern" value="[%Y-%m-%d %H:%M:%S] %v" />
                    <!-- Log level to be recorded.  2 = INFO, 3 = WARNING, 4 = ERROR, 5 = CRITICAL 6 = LOG_OFF, 0,1 = TRACE,DEBUG (Works only with debug build) -->
                    <property key="log_level" value="2" />
                </sink>
            </sinks>
        </spd_log>
        <!--There could be multiple log elements here. Eg: statistics, health, device-check -->
        <log-elements>
            <!-- Configure how the statistics are logged -->
            <get-statistics enabled="true">
                <group model=".*" serial=".*" schedule="0/20 * * * * *">
                    <!-- Max value for a period is ~ 596,523‬ hrs  -->
                    <!-- These scanner attributes will be retrieved from the scanner and their values will be logged. This could have multiple attributes defined here -->
                    <scanner-attribute-ids>15109,15839,15011</scanner-attribute-ids>
                </group>
            </get-statistics>
            <check-health enabled="true">
                <group model=".*" serial=".*" schedule="0/30 * * * * *">
                    <!-- Max value for a period is ~ 596,523‬ hrs  -->
                    <scanner-attribute-ids>15015</scanner-attribute-ids>
                </group>
            </check-health>
            <on-agent-start-up enabled="true">
                <!-- check-model="true" check-serial="true" check-config-name="true"> -->
                <group model=".*" serial=".*">
                    <scanner-attribute-ids>534,533</scanner-attribute-ids>
                </group>
            </on-agent-start-up>
            <on-system-shutdown enabled="true" />
            <!-- Used to enable/disable log entries on device attach-->
            <on-attach enabled="true">
                <!-- check-model="true" check-serial="true" check-config-name="true"> -->
                <group model=".*" serial=".*">
                    <scanner-attribute-ids>534,533</scanner-attribute-ids>
                </group>
            </on-attach>
            <!-- Used to enable/disable log entries on device detach -->
            <on-detach enabled="true" />
            <!-- Used to enable/disable log entries on barcode events -->
            <on-barcode enabled="true" />
            <!-- Used to enable/disable log entries on firmware download events -->
            <on-firmware-download-start enabled="true" />
            <on-firmware-download-progress enabled="true" />
            <on-firmware-download-end enabled="true" />
            <on-firmware-download-error enabled="true" />
        </log-elements>
    </settings>
</config>      

Tag Description

Table 1 XML Tags Description

XML Tag Description
spd_log

Contains spd log configurations.

This can be used to customize the log pattern, log file name, log file path, maximum log files count and maximum log file size.

Log file path can be given a network location to save log files.

  • Eg: <property key="log_file_path" value="\\10.225.123.31\Temp\logging-agent-logs" />
  • NOTE: On Linux systems first mount the shared folder to current system. Then give the path of that location of the current system.

Log file name can be customized to have system information when combined with the following options,

  • %h - Host name
  • %H - Host ID (Physical address of the first MAC)
  • %u - User name without domain (Ex. AAA)
  • %U - User name with domain (Ex. AAA@zebra.com. Domain in @ format)

Eg: . The log file will be named as LogAgent-hostname-username.log. The host name and the username will differ based on the user.

More sinks can be defined as per the need.

Refer spd log documentation for more information on this area. https://github.com/gabime/spdlog

log-elements

This describe the elements to log. The supported sub tags are,

  • get-statistics – options for statistics logging
  • check-health – options for health logging
  • on-agent-start-up – options for logging logging agent start up
  • on-system-shutdown– options for logging system shutdown events
  • on-attach – options for logging on a device attach
  • on-detach - options for logging on a device detach
  • on-barcode - options for logging on a barcode read
  • on-firmware-download-start - enable/disable firmware download start event logging
  • on-firmware-download-progress - enable/disable firmware download in progress events logging
  • on-firmware-download-end - enable/disable firmware download end event logging
  • on-firmware-download-error – enable/disable firmware download error logging

All these log elements can either be enabled or disabled using the attribute “enabled” in the tag.

get-statistics This contains options for statistics logging. The supported sub-tags are group tags.
check-health This contains options for health logging. The supported sub-tags are group tags.
on-agent-start Occurs when the application is restarted.
on-agent-shutdown logs when the logging agent is shutdown or when a system reboot is requested
on-attach Occurs when a device is attached to the system.
on-detach Occurs when a device is detached from the system.
on-barcode Occurs on a barcode read.
on-firmware-download-start Occurs on a firmware download start event.
on-firmware-download-progress Occurs when a firmware download is in progress.
on-firmware-download-end Occurs on a successful firmware download end event.
on-firmware-download-error Occurs on a firmware download error event.
group

The group tag is used to define a filter for scanners and to set up interval of occurrence. The supported attributes are,

  • Model – specify the model. Wild cards are supported (Eg: model = "DS*")
  • Serial – specify the serial number. Wild cards are supported (Eg: serial = "14075010502573")
  • Schedule – specify the time interval in cron job format. For more information refer link https://www.freeformatter.com/cron-expression-generator-quartz.html (Eg: schedule = “0 0 0/8 * * *” – Log every 8 hours)

A group may contain additional scanner-attribute-ids tag to include additional data in the log file.


Run the Logging Agent

Run as a background process (Windows).

  1. Double-click "logging-agent.exe" or
  2. Run on the command prompt without any parameters. Eg: Path\to\the\executable>logging-agent.exe)

Run as an application via the command prompt (Windows).

  1. Run on the command prompt as,

    1. Path\to\the\executable > logging-agent.exe --show, OR
    2. Path\to\the\executable > logging-agent.exe -s
  2. Please note that double-dash in first case, and single-dash in the second case.
  3. To display the help test run the executable with "--help" or "-h"

Run as a daemon in the background (Linux).

  1. Open a terminal and go to the directory where you extracted logging-agent files.
  2. Run "sudo ./logging-agent". ( before that you may need to run "sudo chmod a+x logging-agent")

Run as an application in the foreground (Linux).

  1. Open a terminal and go to the directory where you extracted logging-agent files.
  2. Run "sudo ./logging-agent -s" or "sudo ./logging-agent --show". (before that you may need to run "sudo chmod a+x logging-agent")
  3. Please note that double-dash in first case, and single-dash in the second case.
  4. To display the help test run the executable with "--help" or "-h"

Log Files

The log files created by the logging agent will be written to the path specified in the configuration xml in as a text file. If the application is run with the user command prompt displayed, the logs will be printed to the command prompt as well.

If needed more sinks can be defined in the configuration xml file, to write logs to more locations.


Version History

Please refer Barcode Scanner SDK for Windows and Linux release notes for more details.