4.10. Structured JSON Lines logger

The logger module provides a structured, file-backed logging facility for daslang tools (MCP server, daslang-live, dastest, etc). Records are written as one JSON object per line (“JSON Lines” / ndjson) to {get_das_root()}/logs/<name>.log, with an ISO 8601 UTC timestamp (millisecond precision), level name, dotted category, message, and optional fields object.

The default level is LOG_INFO; per-category overrides apply by dotted prefix (an override on "mcp.live" covers "mcp.live", "mcp.live.foo", and so on). logger_install_hook() registers a process-wide debug agent that diverts print and to_log into the log file — essential for stdio-transport processes (MCP server, language servers) where any stdout write corrupts the wire format.

All functions and symbols are in “logger” module, use require to get access to it.

require daslib/logger

4.10.1. Setup

logger_get_name(): string

Returns the logical name passed to logger_set_name() (empty if the path was set directly via logger_set_path()).

logger_get_path(): string

Returns the currently configured log file path (empty if unset).

logger_init(name: string )

Convenience: logger_set_name(name) + logger_install_hook(). The common-case one-liner for tools that want both behaviors.

Arguments:

  • name : string

logger_set_name(name: string )

Configure the log file as {get_das_root()}/logs/<name>.log. Re-opens if the path changes; closes the previous handle. Each Context tracks its own state — call once per context.

Arguments:

  • name : string

logger_set_path(path: string )

Override the log file path explicitly. Pass an absolute path or a path relative to the current working directory.

Arguments:

  • path : string

4.10.2. Level filters

logger_clear_category_levels()

Remove all per-category overrides.

logger_get_min_level(): int

Returns the currently configured global minimum level.

logger_set_category_level(category: string; level: int )

Override the level filter for one category. Dotted prefix matching: an override on "mcp.live" applies to "mcp.live", "mcp.live.foo", "mcp.live.bar" (unless they have their own more specific override).

Arguments:

  • category : string

  • level : int

logger_set_min_level(level: int )

Global minimum level. Records below this are dropped before formatting. Default LOG_INFO.

Arguments:

  • level : int

4.10.3. Output control

logger_close()

Close the log file. Subsequent writes will lazy-reopen.

logger_flush()

Explicit flush. Each write already flushes; only useful if you disable auto-flush in a fork.

logger_set_stderr_fallback(enabled: bool )

Enable / disable writing to stderr when the log file can’t be opened. Defaults to true; set to false for strict stdio-transport servers that must NEVER write to either stream on file failure.

Arguments:

  • enabled : bool

4.10.4. Log calls

logger_critical(category: string; message: string; fields: JsonValue? = null )

Critical / fatal record. LOG_CRITICAL.

Arguments:

  • category : string

  • message : string

  • fields : JsonValue?

logger_debug(category: string; message: string; fields: JsonValue? = null )

Debug-level record. LOG_DEBUG.

Arguments:

  • category : string

  • message : string

  • fields : JsonValue?

logger_error(category: string; message: string; fields: JsonValue? = null )

Error record. LOG_ERROR.

Arguments:

  • category : string

  • message : string

  • fields : JsonValue?

logger_info(category: string; message: string; fields: JsonValue? = null )

Informational record. LOG_INFO — the default level.

Arguments:

  • category : string

  • message : string

  • fields : JsonValue?

logger_log(level: int; category: string; message: string; fields: JsonValue? = null )

Generic log entry. Prefer the named-level helpers below.

Arguments:

  • level : int

  • category : string

  • message : string

  • fields : JsonValue?

logger_trace(category: string; message: string; fields: JsonValue? = null )

Verbose trace-level record. LOG_TRACE.

Arguments:

  • category : string

  • message : string

  • fields : JsonValue?

logger_warning(category: string; message: string; fields: JsonValue? = null )

Warning record. LOG_WARNING.

Arguments:

  • category : string

  • message : string

  • fields : JsonValue?

4.10.5. Stdout hook

logger_install_hook()

Install a global debug agent that diverts print and to_log (from any Context, current or future) into the configured log file. Idempotent — safe to call from every module’s [init], from MCP main, etc. Worker threads spawned via new_thread inherit the hook automatically; no per-context re-install needed.