logging

The logging library provides Python-style logging functionality, compatible with the basic Python logging interface. It uses the paularlott/logger library under the hood with slog integration. Reach for it instead of print() whenever a script’s output needs levels, structured output, or to flow through the embedder’s own logging pipeline.

Available Functions

Constants

Functions

getLogger(name=None)

Create and return a logger object with the specified name. The name is used as the group name in the underlying logger and is displayed as a nested group in log output, e.g. [scriptling.componentName].

Parameters:

• name (str, optional): Logger name. Default: None (uses "scriptling").

Returns: Logger: an object with debug(), info(), warning(), warn(), error(), and critical() methods.

import logging

logger = logging.getLogger("myApp")

logger.debug("debug message")
logger.info("info message")
logger.warning("warn message")
logger.error("error message")
logger.critical("critical message")

debug(msg)

Log a debug message using the default (module-level) logger.

Parameters:

• msg (str): Message to log.

Returns: bool: always True.

import logging

logging.debug("Starting up")

info(msg)

Log an info message using the default logger.

Parameters:

• msg (str): Message to log.

Returns: bool: always True.

import logging

logging.info("This is an info message")

warning(msg)

Log a warning message using the default logger.

Parameters:

• msg (str): Message to log.

Returns: bool: always True.

import logging

logging.warning("Watch out!")

warn(msg)

Alias for warning(), provided for Python compatibility.

Parameters:

• msg (str): Message to log.

Returns: bool: always True.

import logging

logging.warn("Watch out!")

error(msg)

Log an error message using the default logger.

Parameters:

• msg (str): Message to log.

Returns: bool: always True.

import logging

logging.error("Something went wrong")

critical(msg)

Log a critical message using the default logger. Critical messages are mapped to the error level in the underlying Go logger (there is no separate critical level).

Parameters:

• msg (str): Message to log.

Returns: bool: always True.

import logging

logging.critical("Unrecoverable failure")

Environment Isolation

Each Scriptling environment gets its own logger instance:

• Multiple environments can have different loggers without interfering with each other.
• Loggers can have different output destinations, levels, and formats.
• The logger instance is tied to the environment it was registered with.

// Environment 1
p1 := scriptling.New()
logger1 := logslog.New(logslog.Config{Writer: os.Stdout}).WithGroup("app1")
extlibs.RegisterLoggingLibrary(p1, logger1)

// Environment 2 (different logger)
p2 := scriptling.New()
logger2 := logslog.New(logslog.Config{Writer: someOtherWriter}).WithGroup("app2")
extlibs.RegisterLoggingLibrary(p2, logger2)

Configuration

The default logger is configured with level INFO, console (human-readable) format, output to stdout, and group "scriptling". Loggers created with getLogger() inherit these settings unless the embedder configures otherwise.

Using with the scriptling CLI

When running scripts via the scriptling CLI, the logging library is automatically wired to the CLI’s own logger. Two flags control both the server’s internal logging and any output produced through logging.*/logger.* calls in scripts:

These flags apply to every execution mode (script file, --code, --interactive, --server, --mcp-tools, --mcp-exec-script, --lint).

# Show debug output while running a script
scriptling --log-level debug app.py

# JSON-formatted logs for ingestion into a log aggregator
scriptling --log-level info --log-format json --server :8000 app.py

# Via environment variables (useful for .env files or container deployments)
SCRIPTLING_LOG_LEVEL=debug SCRIPTLING_LOG_FORMAT=json scriptling --server :8000 app.py

When --log-level debug is set, the HTTP and MCP servers emit additional diagnostics such as incoming requests, dispatched handlers, MCP tool invocations, and WebSocket lifecycle events.

The same options can be set in scriptling.toml:

[log]
level = "debug"
format = "json"

Priority order (highest to lowest): command-line flag, environment variable, config file, default.

Python Compatibility

Compared to Python’s logging module, this is a simplified implementation focused on basic logging:

• No configuration API: loggers use the default configuration.
• No handlers: output always goes to the configured writer (stdout by default).
• No formatters: output format is fixed.
• No filtering: all messages at the configured level are shown.
• No hierarchy: named loggers are independent except for the shared group prefix.
• No file logging.

Log messages integrate with Scriptling’s output capture system alongside print() and other script output.

See Also

• sys: Access argv and stdin
• secrets: Generate tokens, separate from logging concerns