Logging

This page documents the logging configuration

Configuration file fields

This section is autogenerated from the Rule Schema file.


File log.file

File split size (1 to 512 MB) log.file.split_size

Log file split size in MB. When the file split size is reached a new file is created and the logging continues. Closed log files can be pushed to a server if network is available. Small split sizes may reduce performance.

Type

Default

Minimum

Maximum

integer

50

1

512

File split time period (0 to 86400 seconds, 0 = disable) log.file.split_time_period

Log file split time period in seconds relative to midnight (00:00:00). When a split time is reached a new file is created and the logging continues. Closed log files can be pushed to a server if network is available. Small split time periods may reduce performance.

Type

Default

Minimum

Maximum

Multiple of

integer

0

0

86400

10

File split time offset (0 to 86400 seconds) log.file.split_time_offset

Log file split time offset in seconds. This value offsets the split_time_period relative to midnight (00:00:00). The set value shall be less than the split_time_period value.

Type

Default

Minimum

Maximum

Multiple of

integer

0

0

86400

10

Cyclic logging log.file.cyclic

With cycling logging mode enabled the oldest log file is deleted when the memory card becomes full, allowing the logging to continue.

Type

Default

Options

integer

1

Disable: 0 Enable: 1


Compression log.compression

Level log.compression.level

Window size used during optional compression. Larger window sizes yield potentially better compression rates, but may reduce logging performance. Compressed log files need to be decompressed prior to processing.

Type

Default

Options

integer

0

Disable: 0 256 bytes window: 256 512 bytes window: 512 1024 bytes window: 1024


Encryption log.encryption

State log.encryption.state

Optional log file encryption. Encrypted log files need to be decrypted prior to processing. Decryption requires your encryption password in plain form - if this is lost, the encrypted data cannot be recovered.

Type

Default

Options

integer

0

Disable: 0 Enable: 1


Error Frames log.error_frames

State log.error_frames.state

Specify whether to record error frames. Enabling this can negatively impact performance, as a potentially large number of additional frames may be recorded.

Type

Default

Options

integer

0

Disable: 0 Enable: 1


Configuration explained

This section contains additional information and examples.

File split

File splitting can be based on file size or file size and time:

  • split_time_period = 0: Split based on size only

  • split_time_period > 0: Split based on both size and time - whichever is reached first

Limits

The file system limits should be considered when configuring the split size and time:

  • SD-card size

  • Max 1024 sessions

  • Max 256 splits (log files) in each session

Above limits result in a maximum of 1024*256=262144 log files if fully utilised.

If the session count limit is reached, the logger will either:

  • Stop logging if cyclic logging is disabled1

  • Delete the oldest session if cyclic logging is enabled

If SD-card becomes full (no more space), the logger will either:

  • Stop logging if cyclic logging is disabled1

  • Delete the oldest split file from the oldest session if cyclic logging is enabled

Limit examples

In most cases the SD-card size limit is reached before the session limit. However, some configurations may cause the session count limit to be reached first. Below follows a range of log split configuration examples and the resulting utilization (Util.) of the SD-card space. Configurations resulting in partial utilization are marked in bold2.

8GB SD-card, varying split size, fixed split time:

Card [GB]

Rate [Msg/s]

Split size [MB]

Split time [s]

Total [days]

Util. [GB]

8

10

1

3600

276.2

8.0

8

100

1

3600

27.6

8.0

8

1000

1

3600

2.8

8.0

8

10

10

3600

276.2

8.0

8

100

10

3600

27.6

8.0

8

1000

10

3600

2.8

8.0

8

10

100

3600

276.2

8.0

8

100

100

3600

27.6

8.0

8

1000

100

3600

2.8

8.0

32GB SD-card, varying split size, fixed split time:

Card [GB]

Rate [Msg/s]

Split size [MB]

Split time [s]

Total [days]

Util. [GB]

32

10

1

3600

1104.7

32.0

32

100

1

3600

110.5

32.0

32

1000

1

3600

11.0

32.0

32

10

10

3600

1104.7

32.0

32

100

10

3600

110.5

32.0

32

1000

10

3600

11.0

32.0

32

10

100

3600

1104.7

32.0

32

100

100

3600

110.5

32.0

32

1000

100

3600

11.0

32.0

8GB SD-card, fixed split size, varying split time:

Card [GB]

Rate [Msg/s]

Split size [MB]

Split time [s]

Total [days]

Util. [GB]

8

10

512

10

30.3

0.9

8

100

512

10

27.6

8.0

8

1000

512

10

2.8

8.0

8

10

512

60

182.0

5.3

8

100

512

60

27.6

8.0

8

1000

512

60

2.8

8.0

8

10

512

300

276.2

8.0

8

100

512

300

27.6

8.0

8

1000

512

300

2.8

8.0

32GB SD-card, fixed split size, varying split time:

Card [GB]

Rate [Msg/s]

Split size [MB]

Split time [s]

Total [days]

Util. [GB]

32

10

512

10

30.3

0.9

32

100

512

10

30.3

8.8

32

1000

512

10

11.0

32.0

32

10

512

60

182.0

5.3

32

100

512

60

110.5

32.0

32

1000

512

60

11.0

32.0

32

10

512

300

910.2

26.4

32

100

512

300

110.5

32.0

32

1000

512

300

11.0

32.0


Compression

Log files can be compressed on the device during logging using a variant of the LZSS algorithm based on heatshrink. Compressed files will have *.MFC as file extension. A high window size improves compression rates, but may cause message loss on very busy networks.

The table below lists results for J1939 and OBD data with different window size configurations3:

Window size (bytes)

J1939 % (range)

OBD % (range)

256

49.7 (47.1-51.4)

32.0 (30.3-32.8)

512

49.5 (46.3-51.6)

30.2 (29.6-31.1)

1024

41.4 (38.9-45.5)

30.0 (29.6-30.8)

Decompression can be done using an implementation of LZSS or using the tools provided with the CANedge.

Note

The split size set in split_size considers the size of the compressed data. I.e. if the split size is 10 MB, the resulting file sizes become 10 MB regardless if compression is used or not.


Encryption

Log files can stored as encrypted (AES-GCM) *.MFE files.

Note

It is recommended to use a 40+ character password for proper encryption

Decryption can be done using an implementation of the PBKDF2 algorithm or using the tools provided with the CANedge.


Error Frames

Enabling error frames will log errors across all interfaces, both CAN and LIN. Note that this can decrease the performance of the device due to the added logging load.

For more information on logging of CAN-bus errors, see CAN errors.


1(1,2)

Logging resumes if files are offloaded via a network connection

2

The examples are based on a common CAN-bus data frame with 11-bit identifier and 8 data bytes, stored in uncompressed format with no power cycles.

3

Compressed size in percentage of original. Lower is better.