Real-time DataLogger reference

Available from firmware 2019.6

Sources and data types

The DataLogger can record data from any IN or OUT ports and variables. The following data sources are available:

• Global Data Space IN and OUT ports
  • Type real-time program (C++, IEC 61131-3 and MATLAB®/Simulink®) – task-synchronous mode
  • Type component
  • Global IEC 61131-3 variables

The following data types are supported:

• Elementary data types (according to Supported elementary data types);
  all STRING variables, regardless of their length, are supported and thus belong to the elementary data types.

Schematic overview

Find all details on the attributes in the tables and sections below.

Configuration parameters explained visually

Sampling intervals, publishing intervals, and "write" intervals? Why are there so many parameters for transporting the data?

Here's why this is the best way to log data in a real-time automation environment ‒ explained by Martin Boers, Technical Specialist in the Product Management PLCnext Runtime System at Phoenix Contact: 

 05m:26s     HDTV 720p     English     none

XML configuration file

An XML configuration file for the DataLogger is structured as shown in the following example:

<?xml version="1.0" encoding="utf-8"?>
  <DataLoggerConfigDocument
     xmlns="http://www.phoenixcontact.com/schema/dataloggerconfig"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:schemaLocation="http://www.phoenixcontact.com/schema/dataloggerconfig.xsd">
    <General name="data-logger" samplingInterval="100ms" publishInterval="500ms" bufferCapacity="10"/>
    <Datasink type="db" dst="test.db" rollover="true" maxFiles="3" writeInterval="1000" 
       maxFileSize="4000000" storeChangesOnly="false" tsfmt="Iso8601"/>
    <Variables>
      <Variable name="Arp.Plc.ComponentName/GlobalUint32Var"/>
      <Variable name="Arp.Plc.ComponentName/PrgName.Uint32Var"/>
      <Variable name="Arp.Plc.ComponentName/PrgName.StuctVar.IntElement"/>
      <Variable name="Arp.Plc.ComponentName/PrgName.IntArrayVarElement[1]"/>
    </Variables>
  </DataLoggerConfigDocument>

As you can see in the structure, there are only a few XML elements to be configured.

Within the <DataLoggerConfigDocument> schema, there are always:

• <General>
• <Datasink>
• <Variables>, containing one or more <Variable> elements

Attributes for file-based configuration

Of course, there's a bunch of attributes adding some complexity. See the following tables in which the attributes are grouped by the XML tags they belong to. Where there's much more to explain to an attribute you will find additional information below the tables.

<General>

Attribute	Description
name	Unique name of the logging session. Note: Must not begin with "PCWE_" which is reserved for the triggered Logic Analyzer of PLCnext Engineer.
samplingInterval	Interval during which the data points of a variable are created, e.g. samplingInterval ="50ms".  The default value is500ms. The following suffixes can be used: ms, s, m, h. Note: This attribute will be ignored if a taskContext is also configured.
taskContext	Available from firmware 2021.6 or newer. The name of an ESM task which samples the values of all variables of this session, e.g. taskContext="myTaskName".  The attribute is optional. Note: If it is configured then the samplingInterval attribute will be ignored.
publishInterval	Frequency for forwarding the collected data from the ring buffer to the data sink, e.g. publishInterval="1s". The default value is 500ms. The following suffixes can be used: ms, s, m, h.
bufferCapacity	Configuration of the buffer capacity. Capacity of data sets for the internal buffer memory. The default value is 2.

<Datasink>

In each cycle, the values of all ports of a task are stored in a ring buffer. Therefore, the capacity of the ring buffer determines the maximum number of task cycles that can be recorded before data must be forwarded to the data sink. 

The data to be archived is written to an SQLite database.  For each configured DataLogger instance, a separate SQLite database is created. 
Note: In SQLite3 data bases, a maximum of 996 variables must be obeyed.

Attribute	Description
type	Configuration of the data sink type: db: (SQLite) Database file volatile: RAM only tsdb: time series database, used by the trend chart object of PLCnext Engineer eHMI (for details see Additional sink type...) Note: For a volatile data sink, the maxFileSize attribute must be set.
dst	With file-based configuration, this is the file name and path under which the data sink is to be stored.  If you want to store a data sink at a specific path, you have to create it before configuring the DataLogger session because the DataLogger does not create folders. If no specific path is given it will be placed in the working directory of the firmware which is /opt/plcnext/.  Note: On secure-by-default devices (e.g. AXC F 1252), applications and users cannot write directly to the /opt/plcnext/ directory. If the configuration is made with the PLCnext Engineer interface (available from software version 2020.6), this attribute is set to dst="/opt/plcnext/logs/datalogger/<LogSessionName>.db" where  <LogSessionName> is what you have written into the "Name" field of the interface.
rollover	true: Once the maximum file size is reached, the file is closed and renamed with an index starting from 0 (e.g. database.db.0). Then a new file is created. Every file that has an index is closed and can be copied for evaluation.  The current data is always logged in the database that is defined in the attribute dst. false:  If rollover is set to false and the maximum file size is reached, a configurable amount of the oldest data is deleted before the record proceeds. The amount of data to be deleted is configured with the attribute deleteRatio.
writeInterval	Number of data records the DataLogger collects and writes to the SD card. The default value is 1000. For details read Write intervals. When the data sink or the firmware is closed, all the values that have not yet been transferred are written to the SD card.
maxFileSize	Maximum memory size of the log file in bytes. Note: In case a volatile sink type is used, maxFileSize must be set in proportion to the amount of free space on the device and the number of data sinks to contain, and can never be larger than 150000000 (approximately 150 MB).
maxFiles	Maximum number of rolling files (default value is 1).  The rollover attribute must be set to true. When the maximum number of files is reached, the oldest file will be deleted. The file index of the closed files will be counted up further.  If the maximum number of files is set to 0 (maxFiles="0") the behaviour corresponds to a deactivated rollover (rollover="false"). If the maximum number of files is set to a negative number (e.g. -1) then the file number limitation is deactivated. This results in logging activity until the memory is full. The default value is -1.  Note: When the value for maxFiles is 1, rollover is set to true and the maximum file size is reached, a configurable amount (attribute deleteRatio) of the oldest data in the database is deleted. The deleteRatio is related to the maximum file size that is defined with the attribute maxFileSize.
storeChangesOnly	true: The values are only stored if they change. If a value stays the same, it is defined as NULL in the database. false: The values are always stored, even if they do not change. For details read Recording mode.
deleteRatio	Available from firmware 2020.0 LTS: Percentage of maximum memory size to be deleted for the logging of new data. Default is 30 %. This attribute defines the amount of data that is deleted before new data is written into the database. The old data is deleted when the value that is defined in maxFileSize is reached and the attribute rollover is set to false. The value for deleteRatio must be provided as an unsigned integer value (16 bit). It must be in the range from 1 to 100. The value corresponds to the percentage of old data to be deleted.  Examples: 5 = 5 % of old data is deleted. 30 = 30 % of old data is deleted. Note: For large data sinks (larger than 10 MB) the deleteRatio should be set to a value lower than the default to avoid data loss during the deletion process. E.g., deleting 15 MB (about 30 % of a 50 MB data sink) on an SD card may take so much time that meanwhile the limits of values being buffered and published to the RAM are exceeded. In this case, some data gets lost; you can detect that by an interrupted series of timestamps.
tsfmt	Available from firmware 2020.0 LTS: Configuration of the timestamp format Raw: The timestamp is stored as a 64-bit integer value. Iso8601: The timestamp is stored in the ISO 8601 format with microsecond accuracy (see details at Timestamp). Note: Logging with Iso8601 timestamps is on the expense of performance. In high-performance scenarios, converting the timestamp after logging might a better solution.

<Variables>

Attribute

Description

Variable name

Complete name (URI) of a variable or a port whose values are to be recorded.  Example:  Arp.Plc.ComponentName/PrgName.Uint32Var Note: When using an SQLite3 database sink, a maximum of 996 variables per session must be obeyed.  In case a XML-based configuration tries to add more variables than possible to a session, a notification will be generated and the configuration file is not used to configure a session. In case a RSC-based configuration tries to add more variables than possible to the session, the call to IDataLoggerService::SetVariables will result in a single returned value Error::InvalidConfig.

<TriggerCondition>

Available from firmware version 2020.3

From firmware version 2020.3 on you have the possibility to define trigger conditions for starting a DataLogger session via the XML configuration file. To do this, use the element <TriggerCondition> and the attributes described below.

This element starts a list of <RpnItem> trigger items where one item consists of an attribute type and a text that - depending on the type - either names a variable, a constant, or an operation. The optional attributes postCycles and preCycles can be used to specify the amount of datasets recorded before and after the trigger condition is fulfilled.

<TriggerCondition>

Attribute	Description
postCycles	The postCycles attribute is optional. It defines the number of datasets that are recorded after a trigger event.
preCycles	The preCycles attribute is optional. It defines the number of datasets that are recorded before a trigger event.
taskContext	Name of the task in which the trigger condition is evaluated.
autoReset	Available from firmware version 2026.0 LTS The autoReset attribute is optional. It controls whether data is recorded once when the trigger condition occurs (single shot) or each time the trigger condition occurs (multiple shot). This attribute is of the Boolean data type, so the values true and false are permitted. If the attribute is not specified, it corresponds to the value false (single shot selection). Further information can be found in the following section Single shot/Multiple shot selection.

<RpnItem>

List of trigger items. A trigger item can be a variable, a constant or an operation.

Attribute	Description
Variable	The attribute type Variable is used to define a single variable as a trigger condition item. It must contain the complete name (URI) of a variable or a port whose values are to be considered. Example: Arp.Plc.ComponentName/PrgName.Uint32Var
Constant	The attribute type Constant is used to define a constant as a trigger condition item. The item must contain the value of the constant, e.g. 5.
Operation	The attribute is used to define an operation. The following values are valid for the Operation attribute: None - No trigger condition, so recording starts immediately Equals - Starts recording if Variable/Constant 1 is equal to Variable/Constant 2 NotEqual - Start recording if Variable/Constant1 is not equal to Variable/Constant2 GreaterThan - Start recording if Variable/Constant1 is greater than Variable/Constant2 GreaterEqual - Start recording if Variable/Constant1 is greater than or equal to Variable/Constant2 LessThan - Start recording if Variable/Constant1 is less than Variable/Constant2 LessEqual - Start recording if Variable/Constant1 is less or equal to Variable/Constant2 Modified - Start recording when a modification of the Variable/Constant1 is detected RisingEdge - Start recording when a positive (rising) edge of the Variable/Constant1 is detected FallingEdge - Start recording when a negative (falling) edge of the Variable/Constant1 is detected And - Start recording if TriggerCondition 1 and TriggerCondition 2 is true Or - Start recording if TriggerCondition 1 or TriggerCondition 2 is true Not - Logical not

Example

For the configuration, the mathematical Reverse Polish Notation (RPN) is used: Both operands come first, the operator is written as a postfix. For details, check the following example to this trigger condition set: (Variable a > Variable b) & (Variable c > Variable d). For better readability, in this example "a", "b", "c", and "d" are used instead of the complete names (URIs) of the variables or ports.

<TriggerCondition postCycles="200" preCycles="100" taskContext="Cyclic100">
    <RpnItem type="Variable">a</RpnItem>
    <RpnItem type="Variable">b</RpnItem>
    <RpnItem type="Operation">GreaterThan</RpnItem>
    <RpnItem type="Variable">c</RpnItem>
    <RpnItem type="Variable">d</RpnItem>
    <RpnItem type="Operation">GreaterThan</RpnItem>
    <RpmItem type="Operation">And</RpnItem>
</TriggerCondition>

Single shot or multiple shot selection

Available from firmware release and PLCnext Engineer version 2026.0 LTS

If a DataLogger session records data under trigger conditions, PLCnext Engineer offers an additional checkbox to select or deselect the Single Shot option from firmware 2026.0 LTS. This checkbox corresponds to the XML attribute autoReset that is described above. If it is selected, the data is recorded only once (single shot), if it is not selected, the data is recorded each time the trigger condition occurs (multiple shot). 

The Single Shot option is enabled by default and a DataLogger session is activated only once when the trigger condition becomes true. To start the DataLogger session every time the trigger condition occurs, you must deactivate the Single Shot option. This selection is available from firmware version 2026.0 LTS.

You can perform the configuration in PLCnext Engineer by clicking on the PLCnext node in the PLANT area and opening the DataLogger Sessions editor. To enable the Single Shot checkbox, you must first activate the Trigger Condition checkbox and select a task in the Task Context field. 

Note: After the trigger condition becomes true, the DataLogger waits for one publishing interval before checking the trigger condition again. If the trigger condition remains true or is reactivated immediately after a previous trigger, it may not be detected until the publishing interval has elapsed. During that waiting period post-cycle data may be missed (not logged).

To avoid that, the publishing interval should be set shorter than the lowest task interval of the variables being logged. This ensures that the trigger condition is evaluated more frequently than the data changes, increasing the chance of detecting consecutive trigger activations and capturing all post-cycle data.

Database layout

The database files are saved as *.db files.

Depending on your configuration, a database table can consist of the following columns:

• Timestamp (text):
  Timestamp for the logged variable value (see details below at Timestamp).
• ConsistentDataSeries (integer):
  This index shows if there is a inconsistency in the logged data (see details below at ConsistentDataSeries).
• One column for each variable that is configured for data logging. The column name consists of the task name, a slash, and the variable name (see details above at <Variables>).
• optional: Task/Variable_change_count (datatype according to the variable):
  In case of storeChangesOnly="true" (for details see Recording_mode), this column serves as change counter. If configured, there is a change counter for every configured variable.

 

containing the logged values

Note: When evaluating a database, always check to which table each database record belongs.

If a session is configured to be recorded in a pre-existing database file then its the tables might not match the previously logged set of variables. Such a situation may occur, for example, when the DataLogger configuration is changed by means of PLCnext Engineer and then downloaded to the PLC. This is because the To match the current setting, columns are added to the reused tables or additional tables are created in the database.

 

Evaluating a DataLogger database

To evaluate the recorded data, you need to copy the *.db files to your PC and use a suitable software tool to open the *.db files (e.g. DB Browser for SQLite). The file system of the controller is accessed via the SFTP protocol. Use a suitable SFTP client software for accessing, e.g., WinSCP. 

The default path for the database files on your controller is /opt/plcnext. (Note: On secure-by-default devices, e.g. AXC F 1252, applications and users cannot write directly to the /opt/plcnext/ directory.)

Time stamp

The DataLogger provides a time stamp for each value of a port. Only one time stamp is generated for ports from the same task because this time stamp is identical for all the values of the task. Time resolution has a precision of 100 ns.

• Firmware 2019.6 to 2019.9 :
  The time stamp is always displayed as raw 64 bit integer value.
• From firmware 2020.0 LTS:
  It is possible to configure the format of the time stamp inside the database. It can be displayed as ISO 8601 or as raw 64 bit integer value.

Despite the format, all time stamps are reported using the UTC timezone. The implementation and internal representation complies to the Microsoft® .NET DateTime class, see the documentation of the DateTime.ToBinary method on docs.microsoft.com. 

The time stamp is created in the task cycle via the system time of the controller. It is set at the start of the task (task executing event) and maps exactly the cycle time of the task, so that the values of the following task cycles are always one interval apart.

Write intervals

The write interval defines the period at which the DataLogger flushes the volatile data sink (SQLite database) residing in RAM to a persistent storage medium, such as an internal or external SD card. The appropriate setting depends on the application, the volume of data, and the system requirements.

When configuring the write interval, the following aspects should be considered:

• Writing to the SD card too frequently is not recommended because: 
  • each write operation introduces additional CPU overhead.
  • frequent write access may accelerate wear of the SD card and reduce its service life.

• Writing to the SD card too infrequently is also not recommended because:
  • the amount of data written during each write operation becomes very large.
  • if the data sink reaches the maxFileSize then older data is deleted, which may result in data loss.

Therefore, there is always a trade-off between the frequency of write operations and the batch size of each individual write operation.

Note: If the value of the attribute writeInterval is low, the required high number of write operations to the SD card might cause performance problems and loss of data. If there is a loss of data it will be displayed in the database in the ConsistentDataSeries column (for details see Data consistency check). Phoenix Contact recommends to create a volatile type of database (stored in RAM only) in case a very short writeInterval is necessary.

Data consistency check

If recording gaps caused by performance problems or memory overflow occur this information will be saved in the data sink. If there is a loss of data it will be displayed in the database in the ConsistentDataSeries column. Note: Phoenix Contact recommends the evaluation of the ConsistentDataSeries flag to ensure that the data is consistent. If ConsistentDataSeries=0 is stated in other rows than row 1, an inconsistency has occurred during recording.

This column can contain the values 0 or 1:

• Value 0:
  If the value is 0 a data gap occurred during the recording of the preceding data series. The first data series always has the value 0 because there is no preceding data series for referencing.
• Value 1: 
  If the value is 1 the data is recorded without a gap related to the preceding data series. Therefore the data series tagged with a 1 is consistent to the preceding data series. 

Example

Example from a database with an indicated data gapShow example with an indicated data gap

Recording mode

The recording mode is set by the attribute storeChangesOnly. There are two recording modes available:

• Endless mode
  The DataLogger records the data in endless mode. All the ports and variables configured for recording are recorded without interruption (storeChangesOnly="false"). 
• Save on change
  The DataLogger only records the data when they change. If the value stays the same it is displayed in the data base with a NULL (storeChangesOnly="true"). 

Examples

Show example with storeChangesOnly="false"Show example with storeChangesOnly="false"

Show example with storeChangesOnly="true"Show example with storeChangesOnly="true"

Show example with storeChangesOnly="true" and variables from different tasksShow example with storeChangesOnly="true" and variables from different tasks

Note: In these examples the time stamp is displayed in a readable format.

In a *.db file generated by the DataLogger, the time stamp is UTC of type Arp::DateTime. It is displayed as a 64-bit value in the database. The implementation and internal representation complies to the .NET DateTime class. Refer to the documentation of DateTime struct at https://docs.microsoft.com to convert the time stamp into a readable format.

 

 

• Published/reviewed: 2026-11-09  ✍  Revision 103 •