log

Summit Logging library.

The Summit Logging library allows you to send messages to the application logs. This is primarily intended for debugging and troubleshooting after the fact, and is not intended to function as a form of reporting. Logs will not be kept forever, so if you need a permanent record of every run of your application, this does not provide that facility.

Whenever you call Summit Library functions (channel.say, http.get, email.send, etc.) the platform will log a helpful message, which includes what function was called and what the arguments were. However, sometimes you may want to turn down or disable this, in case you have sensitive arguments (like credit card numbers), and for that reason we allow you to set a logging mode.

By default, this mode is “verbose”, which means we log function names and full argument lists. We also provide a “restricted” mode, which still logs function calls but excludes their arguments. If that’s not enough, there’s a “silent” mode, which logs nothing. We recommend using this mode as little as possible, as turning off logging will make debugging and troubleshooting considerably harder. Additionally, these modes affect our Platform internal logging as well, so when you turn on silent mode, we will not be able to retrieve log information about the specific progress of your call either.

Functions

Name Summary
debug

Log a message at the DEBUG level.

error

Log a message at the ERROR level.

get_logging_mode

Return the current logging mode.

info

Log a message at the INFO level.

restricted_mode

Turn on restricted logging, for sensitive data.

silent_mode

Turn off all automatic logging.

verbose_mode

Turn on maximum logging.

warning

Log a message at the WARNING level.

Functions : log

debug(...)

Log a message at the DEBUG level. These messages will show up in your call logs. We do not recommend logging sensitive data, such as credit card information, with this library. The DEBUG level is the lowest level.

Parameters
Name Type Default Summary

...

string

You can pass any number of strings to this function and they will all be logged in a single entry.

Returns
Type Summary

nil

Usage
local log = require "summit.log"
log.debug("This", "is", "a", "log entry example")
-- This message will appear in the logs for this call.

error(...)

Log a message at the ERROR level. These messages will show up in your call logs. We do not recommend logging sensitive data, such as credit card information, with this library. The ERROR level is the highest level, and is usually reserved only for major problems.

Parameters
Name Type Default Summary

...

string

You can pass any number of strings to this function and they will all be logged in a single entry.

Returns
Type Summary

nil

Usage
local log = require "summit.log"
log.error("This", "is", "a", "log entry example")
-- This message will appear in the logs for this call.

get_logging_mode()

Return the current logging mode. This lets you see the current logging mode in your application. It should always be one of "verbose", "restricted", or "silent". The default for all applications is "verbose", and apps will remain in that mode until you explicitly change it by calling log.restricted_mode or log.silent_mode.

Returns
Type Summary

string or nil

One of "verbose", "restricted", or "silent"; or nil if an error occurred

nil or string

nil if no errors occured, or a string error message if something went wrong

Usage
local log = require "summit.log"
local ret, err = log.get_logging_mode
print(ret, err)  -- prints "verbose", nil

info(...)

Log a message at the INFO level. These messages will show up in your call logs. We do not recommend logging sensitive data, such as credit card information, with this library. The INFO level is the second lowest level available. It is also the level where most automated logging of Summit Library functions occurs.

Parameters
Name Type Default Summary

...

string

You can pass any number of strings to this function and they will all be logged in a single entry.

Returns
Type Summary

nil

Usage
local log = require "summit.log"
log.info("This", "is", "a", "log entry example")
-- This message will appear in the logs for this call.

restricted_mode()

Turn on restricted logging, for sensitive data. This mode will still automatically log all function calls, but it will not log arguments. If you are passing sensitive data in arguments (say, reading back a user’s credit card number), turning on this mode is a good idea.

Returns
Type Summary

nil

Usage
local log = require "summit.log"

-- Turn on restricted mode for logging sensitive data
log.restricted_mode()
channel.say("hello")
-- Log will contain an entry with the message:
-- `Executing command: channel.say(<args hidden>)`

-- After we finish with the sensitive data, we can change the logging
-- mode back to verbose
log.verbose_mode()
channel.say("goodbye")
-- Log will contain an entry with the message:
-- `Executing command: channel.say("goodbye", [])`

silent_mode()

Turn off all automatic logging. This mode will block any automatic logging of Summit library and channel function calls. This mode is only recommended for extremely sensitive applications, as no logging is done of your application’s progress, so any problems or errors will be very difficult if not impossible to troubleshoot.

Returns
Type Summary

nil

Usage
local log = require "summit.log"

-- Turn off all automatic logging
log.silent_mode()
channel.say("hello")
-- Nothing will be logged, not even a record of the function call

-- After we finish with the sensitive data, we can change the
-- logging mode back to verbose
log.verbose_mode()
channel.say("goodbye")
-- Log will contain an entry with the message:
-- `Executing command: channel.say("goodbye", [])`

verbose_mode()

Turn on maximum logging. Automatically log all calls to Summit library functions and channel commands, including arguments lists. This is the default log setting.

Returns
Type Summary

nil

Usage
local log = require "summit.log"
log.verbose_mode()
channel.say("hello")
-- Log will contain an entry with the message:
-- `Executing command: channel.say("hello", [])`

warning(...)

Log a message at the WARNING level. These messages will show up in your call logs. We do not recommend logging sensitive data, such as credit card information, with this library. The WARNING level is the second highest level.

Parameters
Name Type Default Summary

...

string

You can pass any number of strings to this function and they will all be logged in a single entry.

Returns
Type Summary

nil

Usage
local log = require "summit.log"
log.warning("This", "is", "a", "log entry example")
-- This message will appear in the logs for this call.