Skip to main content

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:

  1. If no filter is active all messages are shown.
  2. If no positive filter is active all messages are shown that are not filtered out by negative filters.
  3. 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 nameexpected typedefault valuedescription
typenumbernoneMandatory type. Use 0 for positive, 1 for negative, 2 for marker and 3 for event based filter.
mstpnumberundefinedMessage type. 0 for TYPE_LOG, 1for TYPE_APP_TRACE, 2 for TYPE_NW_TRACE, 3 for TYPE_CONTROL.
ecustringundefinedECU identifier / ECU. Up to 4 characters.
ecuIsRegexbooleanno value = 'autodetect'Optional. See apidIsRegex.
apidstringundefinedApplication identifier / APID . Up to 4 characters.
apidIsRegexbooleanno 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: ^$*+?()[]{}|.-\=!<,
ctidstringundefinedContext identifier / CTID. Up to 4 characters.
ctidIsRegexbooleanno value = 'autodetect'Optional. See apidIsRegex.
logLevelMinnumberundefinedMinimum log-level. I.e. log-level of the message has to be >= to match. If specified mstpis automatically set to 0. See Log levels for values and examples.
logLevelMaxnumberundefinedSame as logLevelMinbut 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.
verbosebooleanundefinedverbose 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.
payloadstringundefinedString that is searched in the (textual) representation of the message payload. Matches if the string is contained within the payload.
payloadRegexstringundefinedRegular 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..."
ignoreCasePayloadbooleanfalseDetermines 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.

versionexampledescription
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 nameexpected typedefault valuedescription
namestring-Optional name for the filter. If not specified an autogenerated name based on the attributes is used, see autogenerated filter name.
enabledbooleantrueIf this is set to false the filter will never match any message, i.e. is not active.
notbooleanfalseNegate the match result expect for enabled
atLoadTimebooleanfalseThis 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.
filterColourstring or objectundefinedonly 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.
decorationIdstringundefinedonly for type=2(MARKER) or type=0(POSITIVE). Specifies the "decorationId" to the be used for the marker. (Deprecated. Use filterColour object settings).
timeSyncIdstringundefinedonly in conjunction with payloadRegexand timeSyncPrio. See Time Sync.
timeSyncPrionumberundefinedonly in conjunction with timeSyncId.
reportOptionsJSON objectundefinedsee Report generation.
configsJSON objectundefinedsee Configs

Log levels

DLT specifies the following log-levels:

log-levelvalue
LOG_FATAL1
LOG_ERROR2
LOG_WARN3
LOG_INFO4
LOG_DEBUG5
LOG_VERBOSE6
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:

propertydescription
backgroundColorBackground color (as css color like for string based filterColour)
borderColorColor of the border (used for string based filterColour). E.g. "blue". Needs to be used with borderWidth and borderStyle together.
borderWidthWith of the border as CSS styling property. E.g. "1px".
borderStyleStyle applied to the border. E.g. "dotted".
colorColor of the text. E.g. green.
overviewRulerColorColor of the decoration in the overview ruler.
overviewRulerLaneLane 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"
}