Filter reference

Overview

In general DLT-Filter can be used to:

add messages passing the filter to the current view (positive)
remove messages passing the filter from the current view (negative)
mark messages passing the filter with a specific background color (marker).

Additionally they can be used to:

generate events (event) that are used to
- generate a graphical report or
- used for timesync feature to synchronise time stamps between logs.

For generation reports from filters see features: report generation.

When is a DLT message shown in a view?

The rules that determine whether a message is shown are similar to DLT-Viewer:

If no filter is active all messages are shown.
If no positive filter is active all messages are shown that are not filtered out by negative filters.
If any positive filter is active only those messages passing:

any (or) of the positive filters and
are not filtered out by any of the negative filters.

todo: add plantuml chart

Details

Filter match attributes

A filter has the following attributes that determine the matching criteria:

attribute name	expected type	default value	description
`type`	number	none	Mandatory type. Use `0` for positive, `1` for negative, `2` for marker and `3` for event based filter.
`mstp`	number	undefined	Message type. `0` for `TYPE_LOG`, `1`for `TYPE_APP_TRACE`, `2` for `TYPE_NW_TRACE`, `3` for `TYPE_CONTROL`.
`ecu`	string	undefined	ECU identifier / ECU. Up to 4 characters.
`ecuIsRegex`	boolean	no value = 'autodetect'	Optional. See `apidIsRegex`.
`apid`	string	undefined	Application identifier / APID . Up to 4 characters.
`apidIsRegex`	boolean	no value = 'autodetect'	Optional. If provided the apid is treated according to the value as true:regex, false:no regex. If not provided the apid is treated as regex if it contains any special regex characters: `^$*+?()[]{}\|.-\=!<,`
`ctid`	string	undefined	Context identifier / CTID. Up to 4 characters.
`ctidIsRegex`	boolean	no value = 'autodetect'	Optional. See `apidIsRegex`.
`logLevelMin`	number	undefined	Minimum log-level. I.e. log-level of the message has to be >= to match. If specified `mstp`is automatically set to 0. See Log levels for values and examples.
`logLevelMax`	number	undefined	Same as `logLevelMin`but for the maximum log-level, i.e. log-level of the message has to be `<= logLevelMax` to match. See Log levels for values and examples.
`verbose`	boolean	undefined	`verbose` or `non-verbose` messages. Verbose flag is part of the extended header of a DLT msg and defaults to false if the ext. header doesn't exist.
`payload`	string	undefined	String that is searched in the (textual) representation of the message payload. Matches if the string is contained within the payload.
`payloadRegex`	string	undefined	Regular expression that the full (textual) representation of the message payload has to match against. This is in general faster than payload if e.g. `^` for the begin of the text is used. E.g. `^Exception:` is faster than `payload`=`"Exception:"` as the search can be stopped at the first characters already if the payload doesn't start with "Exc..."
`ignoreCasePayload`	boolean	false	Determines whether payload or payloadRegex is using case sensitive (default) or `ignoring case` searches. With payload for case insensitive search both strings are converted to (ascii) upper case first. For regex the "i" option is used (javascript implementation) or (?i) (adlt/rust implementation).

undefined attributes

Undefined attributes are ignored.

all defined attributes need to match

For a message to match all defined attributes have to match (logical and). See not below to negate the match result.

Filter performance

In general all available log messages - which can easily be more than 10 million messages in larger log files - have to be matched against the filters. To speed up the match-comparision it's usually a good practice to specify as many attributes as possible. E.g. typically apid and ctid.

ecu should only be used in cases when you deal with DLT-files that have multiple ECUs logs in the same file. See configs for an alternative way to quickly disable filters not relevant for the current ECU.

For apid and ctid the regular expressions are roughly 6 times slower (e.g. 35ns vs 6ns) and should only be used if necessary.

Payload text checks should use payloadRegex instead of payload except for the cases where you really do want to search simply for substring somewhere in the payload. The amount of necessary steps during regex comparision are nicely shown on pages like regex101.

E.g. to match for messages with

Operation (any name) failed but not Operation (any name) succeeded messages a regex like

^Operation .*? failed (53 steps) is faster than Operation .* failed (70 steps for 3 test strings).

ecu, apid, ctid regular expressions

In general the filter for ecu, apid, ctid expect 4 characters. If less characters are used the regex search is different that the default/non-regex ones: e.g.

version	example	description
default	`"apid":"ECU"`	default/non-regex matches against `apid ECU\0`. So starting with ECU and then (null byte).
`"apidIsRegex":true`	`"apid":"ECU"`	regex matches against 'ECU' within apid. So e.g. "ECU1" or "AECU" or "ECU" all match.
regex	`"apid":"^ECU"`	autodetected regex matches against starting with 'ECU'. So e.g. "ECU" or "ECU1" match but not "AECU".

warning

Especially the payloadRegex consists frequently of characters that need to be escaped in JSON. If using the DLT filter assistant to create filters this is done automatically. If you modify the JSON settings manually please keep this in mind and escape the strings properly. You can use the following code snippet to quickly escape/unescape your string:

Additional filter attributes

Additionaly a filter has the following attributes:

attribute name	expected type	default value	description
`name`	string	-	Optional name for the filter. If not specified an autogenerated name based on the attributes is used, see autogenerated filter name.
`enabled`	boolean	true	If this is set to `false` the filter will never match any message, i.e. is not active.
`not`	boolean	false	Negate the match result expect for `enabled`
`atLoadTime`	boolean	false	This filter is evaluated during initial file opening. This is useful to reduce the load times and size of large DLT-files. Any changes to the filter are only applied after the file is closed and newly opened.
`filterColour`	string or object	undefined	only for `type=2`(MARKER) or `type=0`(POSITIVE): If a string is provided it specifies the border color to be used for the marker. This can be any css color like `red` or hexadecimal color e.g. `#ff0000` (see e.g. w3schools). To set other colors than the border color an object can be used. E.g. `{"backgroundColor":"blue"}`. See decoration options.
`decorationId`	string	undefined	only for `type=2`(MARKER) or `type=0`(POSITIVE). Specifies the "decorationId" to the be used for the marker. (Deprecated. Use `filterColour` object settings).
`timeSyncId`	string	undefined	only in conjunction with `payloadRegex`and `timeSyncPrio`. See Time Sync.
`timeSyncPrio`	number	undefined	only in conjunction with `timeSyncId`.
`reportOptions`	JSON object	undefined	see Report generation.
`configs`	JSON object	undefined	see Configs

Log levels

DLT specifies the following log-levels:

log-level	value
`LOG_FATAL`	`1`
`LOG_ERROR`	`2`
`LOG_WARN`	`3`
`LOG_INFO`	`4`
`LOG_DEBUG`	`5`
`LOG_VERBOSE`	`6`

note

To add all messages with warnings, error or fatal messages use a positive filter with logLevelMax = 3.

To remove all messages with INFO, DEBUG or VERBOSE even from other matching filters add negativefilter with logLevelMin = 4.

How to interpret the autogenerated filter name

The filter name shows the following information:

disabled: if the filter is currently not enabled.
name: the optional name attribute it available
type: + (positive), - (negative), * (marker), @ (event)
(load time): for load time filters
!: for "not" / negate filter
mstp: if specified
>= log-level: if logLevelMin is specified
<= log-level: if logLevelMax is specified
VERB: if filter for verbose msgs is specified
NON-VERB: if filter for non-verbose msgs is specified
ECU:.., APID:..., CTID:...: if specified
payload contains '...': if payload is specified
payload matches '...': if payloadRegex is specified
in .. LCs: if lifecycles is specified (todo see ...)
timeSyncId: ... prio:... : if timeSync is specified.

decoration options

Filter markers can use the full color capabilities provided by the VS-Code API DecorationRenderOptions. Excerpt:

property	description
backgroundColor	Background color (as css color like for string based filterColour)
borderColor	Color of the border (used for string based filterColour). E.g. `"blue"`. Needs to be used with borderWidth and borderStyle together.
borderWidth	With of the border as CSS styling property. E.g. `"1px"`.
borderStyle	Style applied to the border. E.g. `"dotted"`.
color	Color of the text. E.g. `green`.
overviewRulerColor	Color of the decoration in the overview ruler.
overviewRulerLane	Lane to use. Possible values: 2 (center), 7 (full), 1 (left), 4 (right).

The isWholeLine property is automatically applied.

Color theme support

You can provide different settings for light and dark themes, e.g. {"light":{...}, "dark":{...}}.

Overview ruler

If you provide the overviewRulerColor and overviewRulerLane properties the marker is visible in the overview ruler as well!

Example:

"filterColour":{
  "backgroundColor":"yellow",
  "borderColor":"blue",
  "borderWidth":"2px",
  "borderStyle":"dotted",
  "color":"green",
  "overviewRulerLane":1, // left
  "overviewRulerColor":"yellow"
}

Overview​

When is a DLT message shown in a view?​

Details​

Filter match attributes​

Additional filter attributes​

Log levels​

How to interpret the autogenerated filter name​

decoration options​