pylon Event Logger#

The pylon Event Logger allows you to capture event messages from source applications built against the pylon SDK or the Framegrabber SDK for troubleshooting and performance improvement purposes.

Currently, the Event Logger is supported under Windows 10/11 64-bit and Linux Ubuntu 22.04 64-bit operating systems. It can capture events logged by GigE, USB 3.0, and CoaXPress cameras, however, it has been optimized for use with CoaXPress cameras.

The Event Logger is provided as a supplementary package for use with pylon or integrated into the Framegrabber SDK installer. You can download both from the Basler website.

Overview of the User Interface#

菜单#

Application Menu#

The following commands are available:

• Settings: Allows you to open the Settings dialog.
• Minimize to Tray: Allows you to minimize the Event Logger. The icon below appears in the info tray to show that the Event Logger is still running. Click the icon to restore the Event Logger to full size.
  
• Quit: Allows you to close the Event Logger.

Settings Dialog#

The Settings dialog allows you to configure general settings for the Event Logger:

• Message View: This setting can only be changed in a clean session.
  • Max. number of messages in view: Specify a limit for how many messages are shown in the message view.
• File Settings: These settings can only be changed in a clean session.
  • File name prefix: Prefix for the session folder and log file that are created during a session. You can specify a file name prefix of your choice or leave the default prefix.
  • Stop when file count and size limits are reached: If this option is enabled, capturing is stopped when the specified file count and size limit have been reached. Otherwise, the files will be overwritten when the limits have been reached. This may mean that older data will be lost.
  • Max. write file size [MB]: Specify a maximum log file size in megabytes.
  • Max. supported active file count: Specify a maximum file count.
• Logging Source: These settings can only be changed after capturing has been paused or finished. The Event Logger captures event messages from a source application via the EltAppender, which uses a network connection to transmit the log data to the Event Logger. The EltAppender can be configured via a properties file.
  Any changes you make here become effective when starting capturing.
  • Port: Network port used to connect to the source application. Default is 12320. This needs to be the same port as defined in the properties file of the source application.
  • Host name / IP address: Host name / IP address of the host running the source application from which you want to capture event messages. Default is localhost.
  • Launch profile: Determines which event messages are created by the source application and can be captured by the pylon Event Logger. Refer to the following section to learn more about the different launch profiles.

Launch Profiles#

Behind each launch profile stands a properties file with different default settings regarding the log levels. The log levels define which messages are sent to the pylon Event Logger from the source application.

Clicking the Open Properties File button takes you to the properties file that corresponds to the launch profile you have selected.

The following launch profiles are available:

• User: For this profile, you have to provide your own properties file. To make sure logging works as expected, you have to set the PYLON_LOG_CONFIG environment variable to a valid and well-configured properties file.
• Default: Basler recommends using this launch profile if you want to receive a sufficient set of information but also maintain a good performance.
• Analysis: Captures most log levels. Choose this launch profile if you want to receive comprehensive information about your source application. Keep in mind that this may have an impact on the performance.
• Factory: Logs FATAL, ERROR, and WARN messages. Choose this launch profile to ensure good performance. Keep in mind that this won't give you any information about the log levels NOTICE, INFO, or DEBUG.
• Custom1: Allows you to customize the log levels as desired.
• Custom2: Allows you to customize the log levels as desired.

Capture Menu#

The following commands are available:

• Start: Starts capturing log messages from a running source application.
• Start and Launch Logging Source: Allows you to open the source application from which you want to capture event messages and start capturing with the currently selected launch profile. The source application has to be installed on the same computer as the pylon Event Logger.
• Pause: Pauses capturing of event messages.
• Open: Allows you to open a file with saved event messages. This can be a session file (.pel) or a legacy file (.log or .txt).
• Save: Allows you to save the event messages captured in a text file along with filter settings files and a session in a location of your choice. The default folder name is message file name_current date-current time. For more information, see the Saving Session Data section.
• Clear: Clears the session, i.e., all event messages currently displayed in the message view are deleted.

“视图”菜单#

The following commands are available:

• Navigation View: Opens/closes the navigation view.
• Activity View: Opens/closes the activity view.

Navigation View#

The navigation view allows you to specify which section of a large data set is loaded into the message view.

This view is mainly required for sessions with extremely large data sets that exceed the limitations of the message view (500000 messages) or if you have configured the message view to show fewer messages but the Event Logger is capturing more than those.

This view also provides a global text search that covers the entire data set. This is in contrast to the search feature, which can only search the messages currently loaded in the message view.

If a search result is found, its binary position is marked in blue in the view and you can move the navigation view's orange search bar to that section.

This allows you to identify interesting spots for analysis in large data sets.

Using the Scroll to End button, you can jump to the end of the messages in your data set:

Activity View#

The activity view shows all event messages displayed in the message view as a graph for the timebase you've chosen. By default, the log levels WARN, ERROR, and UNKNOWN are shown.

You can select/deselect which log levels you want to display as required. If you want to see all entries of all levels, select the ALL check box. The log levels are ranked from UNKNOWN (highest priority) to DEBUG (lowest priority).

Based on the delta time of each message, the timebase determines how the event messages captured are grouped in the activity view. The delta time is in milliseconds. As the activity view can only show a maximum of 1000 items, some options in the Timebase drop-down box may not be available.

Example: You have set a timebase of 1 s and have been capturing for 1000 seconds, i.e., the delta time is 1000. The activity view shows a tick for every second you've been capturing. If you continue capturing, the limit of 1000 ticks will be exceeded and the timebase switches automatically to the next highest option, 15 seconds in this case. At the same time, the 1 second option becomes unavailable.

You can navigate to a message view entry by clicking a graph item with a Count value higher than zero. If more than one log level applies to a specific item (and more than one log level is displayed), clicking that entry takes you to the message item with the highest priority in the message view.

Depending on the timebase selected, several event messages may belong to the same graph item. If this is the case, clicking a graph item will take you to the message that occurred last.

“帮助”菜单#

You can view general information about the Event Logger and access the Basler Product Documentation

工具栏按钮#

图标	功能
	Starts event message capturing.
	Pauses event message capturing. All messages sent from the source application during paused capturing are lost.
	Allows you to open a log file.
	Saves the session data, including all event messages, highlight and display filter settings and to a session folder.
	Clears all messages in the message view.
	Opens/closes the navigation view.
	Opens/closes the activity view.
	Opens the Settings dialog.
	Opens the documentation.

Message View#

The message view is the central area of the Event Logger where event messages are displayed. For each message, the following details are available:

• Timestamp
• Delta Time
• Thread ID
• Source
• Log Level
• Message Info

In the Settings dialog, you can configure how many messages are visible in a range from 5000 to 500000. For data sets with more entries, you can determine the relative position in the data set from which the messages are loaded using the navigation view's orange search bar.

A shortcut menu offers the following options for the currently selected row.

• Set Time Reference: Allows you to specify the currently selected message as a reference. The delta times of all other messages are calculated in reference to this.
• Copy: Copies the content of the currently selected row. To copy only parts of the message, enable text selection by clicking the Select Text button:
  
• Add Display Filter: Creates a display filter based on the table cell, e.g., Timestamp or Log Level that you right-clicked on.
• Add Highlight Filter: Creates a highlight filter based on the table cell, e.g., Timestamp or Log Level that you right-clicked on.
• Show in Activity View: Selects the point in time that the event message occurred in the activity view.

Sidebar Buttons#

The message view has a sidebar that provides a number of tools to manage the message entries.

图标	功能
	Opens/closes the filter bar for display and highlight filters.
	Opens the Display Filter dialog.
	Opens the Highlight Filter dialog.
	Opens/closes the message view search.
	Allows you to go the previous search result.
	Allows you to go the next search result.
	Allows you to go to a specific row in the message view.
	Wraps the text in the Message Info column.
	Allows you to jump to the last message. If you keep autoscrolling enabed and new event messages arrive, the message view will always show the latest messages.
	Allows you to reset the column widths to default.
	Allows you to select text in a column cell to make copying text fragments easier.

Status Bar#

You can view the following information in the status bar:

• Event Logger status

  状态	含义
  Capturing	Event Logger is currently capturing messages.
  Paused	Capturing has been paused.
  Opened	A log file has been loaded.
  Cleared	The previous session has been cleared.
  Saving	Messages are being saved to file.
  打开	A log file is being loaded.
  Loading	A different section of a large log file is being into the message view.
  Searching	A search is in progress.
  Filtering	Messages are being filtered.

• Number of messages (filtered/total)

• Number of messages that match the log level ERROR
• Currently selected launch profile
  You can change the current profile during capturing by clicking it and selecting a different profile.
  

You can also open the notifications view from the status bar.

If the info icon is blue, there are notifications to read. To open the notification view, click the info icon:

Using the pylon Event Logger#

You can capture event messages from applications running on the same computer as the Event Logger or on a different host computer in your network. For this, the Event Logger uses the EltAppender, which transmits the log data from the source application to the Event Logger via a network connection. The EltAppender can be configured via a properties file.

After you have downloaded and installed the supplementary package, the Event Logger is available in the Tools menu of the pylon Viewer. For this to work correctly, the pylon Viewer must be started in an environment in which the PYLON_LOG_CONFIG environment variable already points to a valid properties file.

To use the pylon Event Logger with the Framegrabber SDK, select it during the Framegrabber SDK installation.

Capturing Event Messages#

There are two ways to configure the EltAppender and to start capturing event messages.

• Automatic configuration of the EltAppender

  1. In the Capture menu, select Start and Launch Logging Source.
  2. In the Open dialog, select the executable of the source application from which you want to capture event messages and click Run.
     The application is opened and capturing starts immediately.

• Manual configuration of the EltAppender

  1. Deploy your source application on the host where you want to execute it.
  2. If the host is a remote computer, copy the properties file containing the logger configuration to the remote computer on which the source application is deployed.
     The properties file is located in your user directory in this folder: .pylonEventLogger
     If the Event Logger and the source application are deployed on the same computer, this isn't necessary.
  3. On the computer that runs the source application, set the environment variable PYLON_LOG_CONFIG to point to the properties file containing the logger configuration.
  4. Start the Event Logger on the computer on which you want to receive the event messages.
  5. If the host is a remote computer, open the Settings dialog and change the Port and Host name / IP address settings to the details of the remote computer that hosts the source application.
     If the Event Logger and the source application are deployed on the same computer, this isn't necessary.
  6. Start capturing by clicking Capture > Start.
  7. Start the source application you deployed in the first step.
     The Event Logger connects to your source application and starts capturing event messages.

After starting the capturing, the Event Logger creates a folder in your user directory named .pylonEventLogger. For every capture session, the Event Logger creates a folder here which contains a log file with all event messages captured in that session. The default folder name is FileNamePrefix_current date-current time. You can configure file and folder name prefixes and other general settings in the Settings dialog.

Saving Session Data#

If you want to preserve your session information, e.g., for later use or to share it with others, you can save your session.

To save your session:

1. 单击工具栏中的 Save button in the toolbar:
   

2. Select the folder in which you want to save your session.
   A folder with the name FileNamePrefix_current date-current time is created. This contains the following files:

   • FileNamePrefix[n].txt: Log file n with all event messages captured
   • displayFilterData.json: Contains the display filter settings
   • highlightFilterData.json: Contains the highlight filter settings
   • FileNamePrefix.pel: Session file that contains the list of filters used, the log files created, and version compatibility information

By opening the .pel file from the folder, you can recreate your session, complete with filters and all messages captured. To share the session, simply send the folder with all its contents to the desired recipient.

Filtering Event Messages#

You can use different filter criteria to reduce the number of event messages displayed or to highlight event messages for improved visibility.

All filters configured are shown in the filter bar where they can be toggled on and off.

Configuring Filters#

The easiest method to create and configure a filter is to right-click a cell in the message view and select the desired filter type. Filter key, operation, and filter value are taken automatically from the cell you clicked.

Example: If you only want to see messages captured at a certain point in time, right-click a timestamp. In the shortcut menu, select Add Display Filter. The Display Filter dialog opens with all the information already filled in. Now, you just have to enable the filter by selecting the check box. The result looks like this:

If desired, you can edit the filter by adding children and logical operators.

All filter settings are stored in a .json file in the session folder. If you just want to keep the filter settings without going to the session folder, you can export them as well by clicking Export in the Display Filter or Highlight Filter dialogs. When importing settings, make sure to select correct type of .json file. You can only import highlight filter settings in the Highlight Filter dialog and only import display filter settings in the Display Filter dialog.

To configure filters manually:

1. In the sidebar, click the Display Filter or Highlight Filter button.
   The filter configuration dialog opens.
2. Configure the first filter criterion, by specifying filter key, operation, and filter value.
   To enter the filter value, click in the text field. The filter value is case-sensitive.
3. If you're configuring a highlight filter, select a color for your filter.
   To change the default color, click the color swatch and select a color in the color dialog.
4. If desired, add a child by clicking the Add Child button next to the criterion.
   
   This creates a filter group with the first criterion already added. By clicking the group name, you can change the name of the group.
   1. Add another filter criterion by clicking Add Item and specify filter key, operation, and filter value.
      
   2. Select the desired operator.
5. Enable the filter by selecting the corresponding check box.

The following screenshot shows a highlight filter group that highlights event messages of INFO and NOTICE log levels.

搜索功能#

The search feature allows you to execute plain text and query-based searches. Event messages that contain the search string are formatted in bold.

You can navigate to the next/previous search result relative to currently selected row by using the arrow buttons on the sidebar. If the search field has the focus, you can also use F3/Shift+F3 to step through the results.

The last 10 searches are saved in the search history and can be rerun from there.

The total number of search results as well as the index of the current result are displayed at the right end of the search bar.

The search feature provides autocompletion for a number of keywords. Keywords are case-sensitive regardless of whether you have chosen the case-insensitive search mode.

The following keywords are available: NOTICE, INFO, WARN, DEBUG, ERROR, Timestamp, ThreadID, Source, LogLevel, MessageInfo, Entity, side_down, related_to

Query-Based Searches#

In a query-based search, you can search across all columns the message view using logical, numerical, and string-based operations.

The query search becomes available automatically if the text input starts with a backslash (\). For every text input, the validator checks whether the input can be parsed. If the input can be parsed, the search text turns green. Otherwise, the text is underlined and red. Once you have a valid input expression, start the search by pressing Enter.

示例#

To search for event messages with log level DEBUG or a thread ID that is not 12:

\(LogLevel == Debug) || (ThreadId != "12")

To search for event messages with a log level that contains the letters "de" and whose thread IDs start with 1 and end with 2:

\(LogLevel ? de) && (ThreadId ^ 1) && (ThreadId $ 2)

Advanced Usage#

Properties File#

After starting the capturing, the Event Logger creates a folder in your user directory named .pylonEventLogger. This contains the following properties files:

• profileAnalysis.x.x.x.properties
• profileCustom1.x.x.x.properties
• profileCustom2.x.x.x.properties
• profileDefault.x.x.x.properties
• profileFactory.x.x.x.properties

x.x.x indicates the version of the Event Logger.

These files can be used to change the behavior of the source application. They contain explanations about which settings you can change. For example, you can specify the log levels for which the source application sends messages. This allows you to prevent the Event Logger from getting inundated with irrelevant event messages.

Command-Line Interface#

In addition to using the GUI tool of the Event Logger, the following command line options are available: