Skip to main content

Advanced Logging With Processes

Overview​

In this lesson you will learn how to use advanced logging with an application process. This logging gets stored in the database, allowing administrators

  • Time to Complete: 30 minutes

What You Will Learn​

  1. The types of actions available that can be used for logging
  2. When each type of action should be used

Pre-requisites​

Before starting this lesson, you should already be familiar with

  1. How to attach logging configuration to an application
  2. How to connect an application to a database
  3. How to enable purging for database tables
  4. How to find actions and control their inputs
  5. Controlling the flow of an application process
    1. Loops and conditionals
    2. Sleeps and waits
    3. Using events and outcomes to handle exceptions

Instructions​

Enabling Advanced Logging​

Advanced logging is enabled as long as the relevant database table can be updated. Advanced logging uses the same ERROR, WARNING, DEBUG semantics as basic logging. However, logging to the database cannot be restricted as would be done for file logging. Therefore care should be taken to balance providing informative logs versus filling up the storage space allocated to the database.

If you run an application in development mode, then logs may also be copied into the application's file log. This is done purely for convenience, and is controlled at the level of the relevant log action, not the process.

Advanced Logging​

All of the advanced logging stores the log messages in the database. Access these log entries is done from the corresponding admin function in the maintenance application.

Rather use the verbose forms such as ERROR or DEBUG, advanced logging will often use the short form instead.

  • ERROR - 0
  • WARNING - 1
  • INFORMATION - 2
  • DEBUG - 3

Application Process Log​

This is used to produce general logs. These will most often be background tasks that need to report their status.

Task - You will be creating a process that will do the following with WriteApplicationProcessLogAction

  1. Log messages as it progresses
  2. Catch an exception

The inputs for the log message can be any of the following

  • Exception

    • Type: Exception
    • An exception that has been caught during the application flow
    • If the action is provided with another message source the message in the exception will be ignored.

  • enactor.commonUI.logging.LogEntryType

    • Type: Integer
    • Set the enactor level to use for this log
    • This is the numerical format stored in the database

  • enactor.coreUI.MessageBasename

    • Type: String
    • Define the message resource to use for resolving a message

  • enactor.coreUI.MessageId

    • Type: String
    • Define a predefined message to use
    • The predefined message can also accept dynamic data
    • These can be provided as custom inputs to the action

  • enactor.coreUI.Message

    • Type: String
    • Supply a custom message for the log
    • This will always be used if provided

The following help to categorise and identify the nature of the log, which can be used to restrict the logs being viewed.

  • enactor.coreUI.DeviceId

    • Type: String
    • If provided, identifies the device that was executing the function

  • enactor.coreUI.UserId

    • Type: String
    • If provided, identifies the user involved with the function
    • If the function is running in the background this should be the user that initiated the function

  • enactor.commonUI.logging.EntryType

    • Type: String
    • A broad categorisation, this gives a general indication of what function was executing

  • enactor.coreUI.ProcessId

    • Type: String
    • This categorisation provides additional debug information
    • This will normally be the current process, but referring to an entry point process is also acceptable

  • enactor.coreUI.ReferenceId

    • Type: String
    • This categorisation is used to find logs related to a single invocation of a function
  1. Create a new application process called DoApplicationLogs
    1. It should have an initial state called Start
    2. It should have the following process outcomes
      1. Success
      2. Fail
  2. Add a WriteApplicationProcessLogAction called LogProcessStart
    1. Link the StateEntered event from the Start state to the action LogProcessStart
    2. Define the Message to be 'The process has started'
    3. Define the LogEntryType to be '3' (DEBUG)
    4. Define the EntryType to be 'Training Task'
  3. Add a WriteApplicationProcessLogAction called LogProcessEndSuccess
    1. Link the action LogProcessEndSuccess to the End Process Action for outcome Success
    2. Define the Message to be 'The process is ending successfully'
    3. Define the LogEntryType to be '3' (DEBUG)
    4. Define the EntryType to be 'Training Task'
  4. Add actions to load an entity
    1. Use the User entity
    2. Link the load entity action to LogProcessEndSuccess
  5. Update LogProcessEndSuccess to include the loaded entity
    1. Add an input for enactor.coreUI.Entity
    2. Map this from the load action
    3. Update the Message for LogProcessEndSuccess to be 'Loaded user {entity.userId}. Process ending successfully.'
  6. Add a WriteApplicationProcessLogAction called LogEntityLoad
    1. Link action LogProcessStart to LogEntityLoad
    2. Link action LogEntityLoad to the actions to create the user key
    3. Define the Message to be 'Preparing to load user'
    4. Define the LogEntryType to be '2' (WARNING)
    5. Define the EntryType to be 'Training Task'
  7. Add a WriteApplicationProcessLogAction called LogEntityException
    1. Link an Exception link from the load entity action to LogEntityException
    2. Link LogEntityException to the End Process Action for outcome Fail
    3. Define the Message to be 'An exception occurred while loading the user'
    4. Define the LogEntryType to be '0' (ERROR)
    5. Define the EntryType to be 'Training Task'
  8. Execute the process DoApplicationLogs
    1. Go to the maintenance application for Application Process Logs
    2. In the filter Entry Type enter 'Training Task'
    3. Observe that the list is now restricted to logs for this process
Viewing the Application Process Log​

The Application Process Log is normally located at Admin/Logs/ApplicationProcessLog. The Application Process Log tracks a wide variety of information, so numerous filters are available to help narrow down which log entries to view.

The severity of the log is indicated in the column for type.

Activity Log​

This is used to track changes made to entities by users. This log can retain the status from before and after the change, allowing an admin to revert undesired changes. These logs can be produced by a logged in user or the system user.

This log is only relevant when there may be a need to restore the previous state of an entity. This means that only applications intended to be a data management node will normally provide the functionality to access this log.

Viewing the Activity Log​

The Activity Log is normally located at Admin/Logs/ActivityLog. Simple filtering is available.

Each log entry can be viewed in multiple ways, allowing a user to see both the state of the entity before and after the change. This can be the normal view page for that entity, or as XML.

System Event Log​

This is a low level log used by the application itself. Its purpose is to track when the status of the application changes, for instance when it last came online or when a user last logged on. Full details for handling system events is covered in the document "System Events".

System events are, primarily, logged in a centralised manner. A system event will be raised on a client application, such as a POS, and then sent to another application, such as the Estate Manager. This is, of course, reliant upon good network connectivity. If a client application cannot connect it will be unable to forward its system events.

To assist with potential investigations a client application can choose to keep a local copy of the log. To minimise confusion, the local copy is stored in the file system rather than the database. These are normally stored in the application Data home.

Task - Use the following actions to log your custom System Event.

  • CreateSystemEventLogEntryAction
  • SaveEntityToToFile
Viewing the System Event Log​

The System Event Log is normally located at Admin/Logs/SystemEventLog. System events from across the entire estate will be viewable here. These can be filtered to focus on particular types of events or those from a specific device.

System events do not contain any complex information, so all relevant information is presented in the list. For more detail, please refer to document on "System Events".