Helper logger

The Logger helper provides an API for managing how debug messages are logged in an application. It provides the following features:

• Sends log output to console, a file, or a field.
• Optionally logs libURL messages, put statements with no target, log messages in LiveCode Builder modules, and messages logged using the appLogMsg command.
• Allows regex patterns to be defined for replacing content in libURL messages. This allows you to remove sensitive data if need be.

Contents

• Activate the logger framework helper
• Configuring Logging
• Logging your own messages
• API

Activate the Logger framework helper

To add the Logger helper to your application add it under the helpers section of the app.yml file:

# app.yml

helpers:
  1:
    folder: ./helpers
  2:
    filename: {{FRAMEWORK}}/helpers/logger

Configuring Logging

You configure the Logger helper by specifying two settings:

1. Which types of messages you would like to log.
2. Where you would like messages to be logged.

Specifying which types of messages to log

You can specify which categories of messages will be logged. The categories are developer, network, msg, and extensions.

Category	Description
developer	messages logged with appLogMsg
network	messages logged by libURL
msg	put messages with no target
extensions	log messages from LiveCode builder extensions.

There are two commands you can use to configure the types of messages to log:

• appSetLogTypes pTypes: Pass in a comma-delimted list of types of messages to log.
• appAddLogType pType: Specify that a specific type of message should be logged.

You can also remove a type of message from logging by calling appRemoveLogType pType. appGetLogTypes() returns a CR-delimited list of types that are being logged.

# Only log developer and internet log messages
appSetLogTypes "developer,network"

Specifying where to log messages

Call appSetLogTarget pTarget to specify where messages should be logged to. Set the target to console, <filename>, or the long id of a field. If the value is empty then messages will be discarded without logging them anywhere.

Examples:

appSetLogTarget "console"
appSetLogTarget specialFolderPath("desktop") & "/log_file.txt"
sppSetLogTarget the long id of field "Log" of me

You can check where log messages are being sent using the appGetLogTarget() function.

Logging your own messages

Call appLogMsg pMsg to log messages. Calls to appLogMsg can be added to your code to help troubleshoot issues in your application when it is running on a user's computer. Logging can be turned off by default but you provide a way for user's to turn logging on. When the user turns logging on in your application than all appLogMsg handler calls when add troubleshooting information to the log file.

Filtering network traffic

Logging internet traffic can be useful when troubleshooting certain issues. You or your customers may have sensitive information the is passing through libURL. libURL log messages will run the regex filters specified using appSetNetworkTrafficLogFilters on any data prior to adding the data to the log. Use this feature to remove the sensitive data before it is ever stored in your log files.

Example:

# Remove username/password from url
put ":\/\/[^:]*:([^@]*)@" & tab & "://USERNAME:PASSWORD@" into tFilter
appSetNetworkTrafficLogFilters tFilter

You can see what the current filters are by calling the appGetNetworkTrafficLogFilters() function.

API

• appAddLogType
• appGetLogTarget
• appGetLogTypes
• appGetNetworkTrafficLogFilters
• appLogMsg

• appRemoveLogType
• appSetLogTarget
• appSetLogTypes
• appSetNetworkTrafficLogFilters

appAddLogType

Type: command

Syntax: appAddLogType <pType>

Summary: Start logging a specific message type.

Returns: Empty

Parameters:

Name	Description
pType	developer, network, msg, extensions.

appGetLogTarget

Type: function

Syntax: appGetLogTarget()

Summary: Returns the current target where log messages are sent.

Returns: empty, console, , or field reference

appGetLogTypes

Type: function

Syntax: appGetLogTypes()

Summary: Returns the types of messages that are being logged.

Returns: Comma-delimited list

appGetNetworkTrafficLogFilters

Type: function

Syntax: appGetNetworkTrafficLogFilters()

Summary: Returns the list of filters that are being applied to libURL messages.

appLogMsg

Type: command

Syntax: appLogMsg <pMsg>

Summary: Logs a message. The message is of type developer.

Returns: Error message

Parameters:

Name	Description
pMsg	The message to log.

appRemoveLogType

Type: command

Syntax: appRemoveLogType <pType>

Summary: Stop logging a specific message type.

Returns: Empty

Parameters:

Name	Description
pType	developer, network, msg, extensions.

appSetLogTarget

Type: command

Syntax: appSetLogTarget <pTarget>

Summary: Sets the field where log messages will be sent.

Returns: Empty

Parameters:

Name	Description
pTarget	console, , or field reference (e.g. ).

Description:

You can target the "console", a file, or a field. "console" writes the log message to stdout.

appSetLogTypes

Type: command

Syntax: appSetLogTypes <pTypes>

Summary: Set the type of messages to log.

Returns: Empty

Parameters:

Name	Description
pTypes	A comma-delimited list of types to log. developer, network, msg, extensions.

Description:

Use this command to filter the types of messages that are logged.

developer: Any message logged using appLogMsg. network: Messages logged by libURL. msg: Any put statements that do not have a target. E.g. put "testing" extensions: Messages logged by an extension using the log command in LiveCode Builder.

appSetNetworkTrafficLogFilters

Type: command

Syntax: appSetNetworkTrafficLogFilters <pFilters>

Summary: Registers regex filters that will be appliedd to libURL messages that are logged.

Returns: Empty

Parameters:

Name	Description
pFilters	A CR-delimited list of filters to apply to libURL messages. Each line is a tab-delimited list where item 1 is a regex pattern and item 2 is the value to use as a replacement.

Description:

You can set network traffic log filters to remove sensitive data from logs that you generate.