Logging Preview

Log() is how a script says anything at all. There is no console, no standard output a person will read, and no way to return a value to the caller. Whatever your script wants to tell you, it tells the Connector's log.

Log("something happened");                 // Info level
Log.Trace("very fine detail");
Log.Debug("diagnostic detail");
Log.Info("normal operation");
Log.Warn("something is off but not fatal");
Log.Error("something failed");

Log(msg) on its own writes at Info level. The five named methods let you pick the severity. Each returns true, which is of no consequence; the value exists only so the call is an expression.

The severity names are Warn and Error, not Wrn and Err

Log.Wrn and Log.Err do not exist. Calling one is a TypeError that stops the script, which on a fail closed before handler refuses the transfer. The five valid names are Trace, Debug, Info, Warn and Error.

Which severity to use

Level	Use it for
Trace	Step by step detail you only want while chasing something
Debug	Values and branches taken, useful while a script is new
Info	The things that happened, in the normal case
Warn	Something unexpected that the script handled
Error	Something that failed, including a refusal you want a person to notice

Trace and Debug lines are only kept if the Connector's log level is set to include them. See Settings for the level and for where the log file is written. Info, Warn and Error are kept at the default level.

Logging structured data

Anything you pass is converted to a string, so an object logs as [object Object] unless you serialize it:

Log.Info(JSON.stringify(EventCtx()));

That single line is the fastest way to learn what an event handed your script. See The event context.

Where the lines go

Into the Connector's own service log, on the Connector host. Not to SFTP.cloud, not to the Portal, not to the user's client, and not to the Activity table, which records file operations rather than script output.

Every line the engine writes carries the script id and name alongside your message, so a busy log stays readable when several handlers fire on the same operation. ScriptName() in your own text is still worth it when one script is bound by several handlers.

The Connector also writes each execution's outcome and duration by itself. You do not need to log "script finished".

Never log a credential

The Connector log is an ordinary file that operators read, that support may ask for, and that backup software copies. A password, an API key, a token or a decrypted file's contents put into Log() is in all of those places from then on. Log the fact, not the secret: Log.Info("authorized with the partner API"), never the key you authorized with.

What logging costs

A log call is cheap but not free, and a before handler runs while the user waits. A line per operation is fine. A line per directory entry, on a folder with fifty thousand files, is not.

// Fine.
Log.Info("upload: " + CtxRelPath());

// Think twice: this is one line per entry, on the data path.
entries.forEach(function (e) { Log.Trace(e.Name); });

Guard the expensive ones behind a condition, or drop them to Trace and leave the Connector's log level at Info in production.