Table of Contents

Logging

Logging Overview

Logging is something every automation should do... and people should floss too.

But it really doesn't take much effort to implement logging, and useful logs are invaluable tools for managing change.

You should have Log_ commands in your automations is the simple guidance! At a minimum two when things start and one when things end.

Logging has flexibility to be controlled from code (see below), but if you just want a log file when run your automation, the intention is to handle things for you. All you need to do is set up Project Logging in the Project Explorer and add Log_ commands in strategic places in your automation.

Note that the Log_ command is useful even if you don't want to write a log file. It will display in the Runtime and also can be displayed in external monitoring applications.

Setting up logging

IMPORTANT: Settings made in the logging tab unfortunately get applied the next time you load the project, they do not get applied immediately.

When your project is loaded, the Project Logging tab in the Project Explorer will be enabled.

First set the LogDirectory - this is where your log files will be generated.

Each time your automation runs, a new file will be created. The log file will be named: Log_ + ProjectName + _ + yyyy-MM-dd_HH-mm-ss + .txt

The log file will be a Tab delimited file. Newest entries will be at the bottom of the file.

Optional set log purging. Purging is calculated when the project loads, its not an agent that runs constantly. Note that log purging only purges files that start with Log_ .

Set PurgeLogsAfterNDays to automatically delete old log files in the log directory. The default is 0 which is the log directory is never purged.

When is a new log file name created?

The simple summary, if you set LogDirectory, is as follows but it is well worth understanding the details:

  • Every time you press Run in the IDE or Runtime you will get a new log file
  • Every time you run from a shortcut or command line you will get a new log file

The software (IDE or Runtime) stores an internal logfile property storing the log file name. This property is specific to the currently loaded project. This property is set as described below and retained in memory until the project is closed, or if specifically set using SetLogDirectory. The log file itself will be created (if it doesn't exist) when the first Log_ command is encountered

The logfile property is set:

  • When you click a Run icon in the IDE or Runtime
  • When you run an automation from a command line or shortcut
  • When you use the SetLogDirectory method (either specifying a directory only or a specific file name)
    • If specifying a file name that already exists, entries will be appended to the file
  • If LogDirectory is set, logfile hasn't been set, and you run a Log_ command in VBA

Turning off logging during development/testing

In the IDE Build tab you can temporarily toggle logging off using the Turn Off Logging toggle button.

Log_ Command

To write an entry to the log, use the Log_ method:

Log_(logText As String, [methodName As String],[commit] As Boolean)

Note that commit parameter is a deprecated feature, its harmless

methodName we recommend using the name of the sub routine or function - this way you know exactly where the log entry was generated from.

Log_ "Starting Application","LaunchApplication"

Logging Exceptions

In your error handler use:

On Error GoTo Errh
...
Exit Sub
Errh:
Log_ Err.Description, "RoutineNameHere"
'TODO: Address the problem
...

Err.Description will have a description of the exception - for example a ContentObject timeout, this will tell you the ContentObject that timed out.

Controlling Logging from Code

Logging is designed to be configured, not coded. The below does not alter the configuration, it allows overriding configurations (whether set or not set). Note uou need to call this before executing the first Log_ command since that first command uses whatever is set for configuration or how that configuration has been overridden.

  • Turn off logging

    SetLogDirectory ""

  • Set a Log directory / turn logging on if the project did not have a log directory set) SetLogDirectory "c:\SomeDirHere"

  • Specify a specific log filename

    SetLogDirectory "c:\SomeDirHere\Log_MyLog.txt"

Note that log purging only purges files that start with Log_ .