Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Logging in ScriptCode

Available logging methods

In the ScriptCode environment, the object Logger, which allows logging events and data from the script.

All arguments passed to methods Logger.<method>() are treated by default as sensitive data, i.e. potentially containing sensitive data, and will be hidden in nonsensitive logs.

Available logging methods:

function callService(context) {
    Logger.info('COMPLETE TASK EXECUTED [arg1={}, arg2={}]', 'arg1', 'arg2');
    Logger.debug('COMPLETE TASK EXECUTED [arg1={}, arg2={}]', 'arg1', 'arg2');
    Logger.warn('COMPLETE TASK EXECUTED [arg1={}, arg2={}]', 'arg1', 'arg2');
    Logger.error('COMPLETE TASK EXECUTED [arg1={}, arg2={}]', 'arg1', 'arg2');
    Logger.trace('COMPLETE TASK EXECUTED [arg1={}, arg2={}]', 'arg1', 'arg2');
}

Choosing the logging level

In ScriptCode, primarily use the level INFO. The most important errors and exceptions are logged automatically by the platform mechanisms.

Level

Principle of use in ScriptCode

INFO

Default logging level. Use for diagnostic and business information needed to trace the script's execution.

WARN

Use only in justified cases. Intended for significant and unusual situations requiring analysis.

ERROR

Do not use in ScriptCode. Errors requiring logging at the level ERROR are handled and logged by the platform.

DEBUG, TRACE

Use for detailed diagnostics during development. These logs are not available in test and production environments.

INFO - default logging level

Use the level INFO to log information needed to analyze the script flow, e.g. execution of an important business step or taking a specific logic path.

You can use Logger.info(), when an additional entry really helps diagnostics. However, remember not to duplicate data logged automatically by the platform and not to add excessive information.

WARN - used only in justified cases

Level WARN use only for significant and unusual situations that should be noticed and analyzed.

Entries WARN are visible in production environments and are subject to analysis, so do not use this level as the default way of logging errors in the script.

If the situation is a standard part of business logic or the entry serves only to diagnose the script's operation, use INFO.

If you are not sure whether the situation requires using WARN, use INFO.

ERROR - do not use in ScriptCode

Entries ERROR indicate serious system operation errors and can cause an alarm situation and a notification to the support line in the production environment.

Errors requiring logging at the level ERROR are handled and logged by the platform mechanisms.

Business exceptions

In ScriptCode, trigger business errors using platform mechanisms: Business errors.

If the script throws a business exception, the platform automatically logs its occurrence at the level WARN. Do not additionally log the same event with Logger.warn() nor Logger.error().

Logging in try/catch blocks

In try/catch use primarily the level INFO.

Use the level WARN use only when the caught situation is significant and unusual enough to require later analysis.

Data logged by default

Platform Eximee automatically logs and treats as sensitive the following elements of the ScriptCode environment:

  • data input forms (input),

  • data output (output),

  • content requests (request) sent to external services, e.g. via REST API,

  • content responses (response) received from those services.

This data is not printed in nonsensitive logs in a way that allows its actual content to be read. It is replaced with the markers _SENSITIVE_DATA_START_ ... _SENSITIVE_DATA_STOP_ or #hashed#, depending on the application type and execution context.

Sensitive and nonsensitive logging

If we want some of the data to be printed in nonsensitive logs without masking, we need to use the method nonsensitive(), which marks the passed argument as nonsensitive.

Example:

In this example:

  • arg1 will be written to the log in plain form,

  • arg2 will be hidden (replaced with a sensitive data marker).

Use nonsensitive() only when you are sure that the passed value does not contain sensitive data. If you are unsure, leave the value as sensitive.

Log format

Examples of log formats for different Eximee platform applications are shown below.

Application process-handlers

Application webforms

Best practices

  • For logging in ScriptCode, use only the object Logger.

  • By default, use the level INFO.

  • Use the level WARN use very rarely and only for significant, unusual situations requiring analysis.

  • Do not use Logger.error() - errors at the level ERROR are logged by the platform.

  • Do not log input, output, request, or response data again if the platform is already logging them.

  • Do not log business exceptions again.

  • Use nonsensitive() only for data that you are sure is not sensitive.

  • Avoid logging entire objects, large data structures, and information that is not needed for diagnostics.

PreviousIntroduction to ScriptCode
NextScripts (ScriptService)

Last updated

Was this helpful?