Log message

Prev Next

See also: Server logging

Event action – Abstract

Purpose: The Log message event action generates an entry in a log file of the Lobster Data Platform / Orchestration server or the browser console, depending on the context, if the log level setting provides for this for the Level assigned when the Message was created.

Tooltip

  • Usage: A Message is sent to a logger addressed by Name, which can contain Localization Parameters. Whether a log entry is written depends on the comparison between the Level of the message and the log Level setting for the addressed logger (see manual for details). Depending on the Level, one of the following log files is written:

    • Lobster Data Platform / Orchestration/error.log for the Level FATAL and ERROR.

    • Lobster Data Platform / Orchestration/message.log for all other Levels (except OFF).

  • Parameter:

    • Name: Text value that names the logger to be used.

    • Message: Text body of the message, the placeholder for the Parameter (addressed by index {0}, {1}, etc.).

    • Level: Single selection for the log level (static enumeration) of the Message (default value: DEBUG).

    • Parameter ({0},{1},...): Optional value configurations for text values that are inserted into placeholders in the Message.

  • Note:

    • For each new Name, the server starts a custom logger with the log level INFO, which can be customized via the Server logging menu item.

    • If executed in the client context, the output only affects the browser console and related logging settings.

images/download/attachments/189440346/image-2024-12-4_9-8-14-version-1-modificationdate-1733299694326-api-v2.png

The Log message event action generates an entry in a log file of the Lobster Data Platform / Orchestration server in the server context (in Event handling), provided that the log level setting for the logger addressed by Name provides for this for the Level assigned when the Message was generated.

  • Messages with the Level FATAL or ERROR are always entered in the log file Lobster Data Platform / Orchestration/error.log. In the following table, the relevant cells are shaded light blue.

  • Messages with a different Level are always entered in the log file Lobster Data Platform / Orchestration/message.log. In the following table, the relevant cells are shaded in light red.

The following logic applies to the comparison between the Level of a message and the log level set via the Server logging menu item:

Level → Server logging

↓ Log message

Log Level settings for the logger addressed by 'Name'

OFF

FATAL

ERROR

WARN

INFO*

DEBUG

TRACE

ALL

(OFF)

FATAL

error.log

ERROR

error.log

WARN

message.log

INFO

message.log

DEBUG*

message.log

TRACE, ALL

message.log

*) In this table, the default values for the log level are marked with an asterisk.

Background: Logger and log level

The Name configuration parameter can be used to refer to the name of a predefined logger or to 'name' a custom logger.

  • If a string that refers to a predefined logger is specified as the Name, a decision is made as to whether a log entry is written depending on the log level for this logger, which may have been adjusted by Server logging.

    • If no Name is specified, the Log message event action refers to the logger for its type (de.lobster.scm.actionevent.actor.LogMessageActor).

  • As soon as a Name that is still unknown on the server side is used for the first time when the Log message event action is executed, an additional entry appears in the 'Log information' tab the next time the Server logging view is opened. A log level other than the default (INFO) can be set there for the custom logger.

    â–ºNOTEâ—„

    • If the first mention of the new logger is made via a Log message with a Level below the default value INFO, no log entry is created. However, the logger will still appear in the 'Log information' list.

    • As the log level DEBUG is the default for the Level of a Log message event action, no message is generated if no Level is selected and the Name is still unknown on the server side.

In the client context (Client Workflow, Client workflows), the Log message event action only addresses the browser console, where a message may or may not appear depending on the settings selected for logging.

Configuration

Configuration example:

images/download/attachments/189440346/image-2024-12-4_9-9-40-version-1-modificationdate-1733299780137-api-v2.png

The following excerpt from an error.log of Lobster Data Platform / Orchestration illustrates the effect of the configuration parameters.

images/download/attachments/189440346/image-2024-12-4_9-11-31-version-1-modificationdate-1733299890757-api-v2.png

Configuration parameters

Element

Description

Name

Default value:

(...LogMessageActor)

Text field for direct input

(Press the arrow in the bottom left-hand corner to switch!)

Value configuration whose return value is converted into a String

The Name designates the logger to be used. The Name appears in the log entry as a prefix in front of the Message, highlighted by square brackets: [Name].

In the example (static text): Name

Message

Default value:

null

The Message appears at the end of the log entry. It can contain placeholders for values ({0}, {1}, ...), which are defined via a Parameter (see below).

In the example (static text): Message from {0}with placeholder {0} for the Company of session (see Parameter).

Level

Default value:

DEBUG

Combobox for single selection from the static enumeration 'Log Level' (LogLevel)

The selected Level determines whether a log entry is written and, if so, to which log file. In addition, the internal name of the enumeration value appears between square brackets in the automatically generated header of the log entry.

[ERROR]

Parameter ({0},{1},...)

Default value: null

Repeatable element for value configurations whose return value is converted into a String

Value configurations can optionally be provided for a Parameter, which can be addressed in the Message via its index (ascending from 0) between curly brackets (see note below).

►NOTE◄ The following special cases must be taken into account when using parameters – similar to the handling for localization entries in Localization:

  • If the Message references a parameter with an index for which no entry exists under Parameter ({0},{1},...), then the reference including the curly brackets appears as plain text (e.g. 'Message from {0}').

  • If the value configuration for a parameter referenced in the Message is either missing or returns 'No value' ($null) at runtime, the plain text 'null' appears instead of the parameter (e.g. 'Message from null').

Examples

Simple use case: Logging the first login of a guest user account as INFO.

When Guest users log on to Lobster Data Platform / Orchestration for the first time, a log entry with the Level INFO should be created with a note stating the ID of the guest user, the Company of session and the Role of session.

The log entry should refer to the Name WELCOME so that a custom logger with this name is created.

Runtime example:

16:49:37 NORMAL [600ms] [T231 /auth/clientEvent/CLIENT_LOGGED_IN [...]] [...] [INFO ] > > > > [WELCOME] Guest user #-8051 from Xflow AG as Querificus

â–ºNOTEâ—„ The 'ID' (id) of the guest user appears here as a negative integer (-8051), as it is taken directly from the return value of the User of session resolver, which differentiates between Guest users and Users via the sign.

Configuration:

The screenshot on the right shows an overview of the configuration for event handling with the Log message event action:

  • The Validating rule uses a With rule to determine whether a guest user who has never logged in is now logging in:

    • The Entity property resolver defines the User of session as a temporary reference object for the rules evaluated below.

    • An AND junction (see Junction) of two rules follows below:

      • The Check type checks whether the reference object is a guest user.

      • The following Entity property rule compares the Object property 'Number of logins' (loginCount) with the static integer 0 to ensure that actions are only executed if the guest user has never logged in.

  • As the only Action on passed rule, a Log message event action is executed, the parameterization of which is explained below.

images/download/attachments/189440346/image-2024-12-4_9-13-9-version-1-modificationdate-1733299988759-api-v2.png

  • The static text WELCOME is entered directly as the Name for the Log message event action.

  • The Message with three placeholders for parameters (see below) is also defined statically via direct input:

    Guest user #{0} from {1} as {2}

    â–ºNOTEâ—„ As the log files mainly contain English content, Localization is not used here (see Value from localization).

  • The Level is defined by selecting INFO in the combobox provided as the default. Technically, a Static enumeration value resolver is used here, which refers to the static enumeration 'Log level' (LogLevel).

  • Three value configurations for the Parameter ({0},{1},...) follow:

    • {0}: The first value configuration reads the Object property id from the return value of the User of session resolver.

    • {1}: The second value configuration reads the 'Name' (address.Name1) field from the address of the company account returned by the Company of session resolver.

    • {2}: The third value configuration reads the 'role name' (roleName) field from the return value of the Role of session resolver.

â–ºNOTEâ—„ For Guest users, unique selections are mandatory for the 'company' (companyId) and 'role' (roleId) fields. However, as the internal field names suggest, the guest user account only references 'Company' and 'Role' without including their detailed data. As the relevant Parameters in the Message are supplied with plain text, access via a Company of session and a Role of session is more efficient here.

images/download/attachments/189440346/image-2024-12-4_9-14-5-version-1-modificationdate-1733300045042-api-v2.png

More complex use case: Dynamically assign level for error.log entry

As with the previous example, when a guest user logs in with a role other than the designated role 'XF_GUEST', not only should the session be terminated, but a Log message should also be written to the error.log.

The Level FATAL ('Super user', 'Super user limited') or ERROR (other roles) should be assigned to the message depending on the role used.

Runtime example:

18:29:02 [596ms] [T1499 /auth/clientEvent/CLIENT_LOGGED_IN [...]] [...] [FATAL] > > > > [WELCOME] Denied access to Guest user -8051 as Super user limited

Configuration:

  • The 'Client logged in' event serves as the triggering event (see Login (Events)).

  • The Validating rule refers to the User of session as a reference object for an AND Junction via the Entity property resolver:

    • The Check type ensures that the login concerns a guest user.

    • In this case, a negated Role rule is evaluated, which is considered passed if a role other than the XF_GUEST role designated for Guest users is considered the Role of session.

  • As the Action on passed rule, two event actions should be executed:

    • The Log message event action ensures that the incident of an 'inappropriate' login as a guest user can be traced in the error.log.

    • The subsequent Abort ensures that the formally legitimate session is terminated immediately in this case.

â–ºNOTEâ—„ Since the logged out user will no longer see an error message triggered by an Abort anyway, the 'Suppress' mode is selected.

images/download/attachments/189440346/image-2024-12-4_9-15-35-version-1-modificationdate-1733300134679-api-v2.png

The Log message event action is configured as shown on the right:

  • The static text WELCOME is input directly as the Name (as above).

  • The Message with two placeholders for parameters is also created via direct input:

    Denied access to Guest user {0} as {1}

  • The Level is defined using a Conditional value that distinguishes between two cases:

    • If a Role rule applies that uses particularly 'powerful' roles as a positive list, the Level 'Fatal' (FATAL) is assigned.

    • Otherwise, the Level 'Error' (ERROR) is assigned.

  • Both Parameters in the Message are supplied with the data from the return values for User of session and Role of session.

images/download/attachments/189440346/image-2024-12-4_9-16-47-version-1-modificationdate-1733300206859-api-v2.png