# `log`

The `log` global is for diagnostic output that is separate from a script's
results. Where `print` writes to standard output, `log` emits **level-tagged**
messages whose visibility is controlled at runtime by an environment variable —
so the same script can run quietly in production and verbosely while you debug,
with no code change. It is always available as the global `log`.

```lua
log.info("starting run", os.time())
log.warn("retrying after error")
log.error("giving up")
```

## Levels

There is one function per severity level:

| Function       | Level   | Use for                                          |
|----------------|---------|--------------------------------------------------|
| `log.trace`    | TRACE   | Very fine-grained, step-by-step detail.          |
| `log.debug`    | DEBUG   | Developer diagnostics.                            |
| `log.info`     | INFO    | Normal high-level progress.                       |
| `log.warn`     | WARN    | Something unexpected but recoverable.             |
| `log.error`    | ERROR   | A failure worth reporting.                        |

`log.warning` is an alias for `log.warn`.

Each takes any number of arguments, converts each with `tostring`, and joins them
with a **tab**, just like `print`:

```lua
log.info("user", userId, "logged in")   --> user    42    logged in
```

To log a table's structure, render it first with
[`utils.dump`](utils.md#utilsdumpvalue):

```lua
log.debug("request opts:", utils.dump(opts))
```

## Controlling what is shown

Log output goes to **standard error**, and which levels are shown is set by the
`RUST_LOG` environment variable. By default only `WARN` and `ERROR` appear:

```sh
a script.lua                 # default: warnings and errors only
RUST_LOG=info a script.lua   # info and above
RUST_LOG=debug a script.lua  # debug and above
RUST_LOG=trace a script.lua  # everything
```

A level shows itself and everything more severe — `RUST_LOG=info` includes
`info`, `warn`, and `error` but not `debug` or `trace`. Messages below the active
level are discarded cheaply, so leaving `log.debug` calls in place costs almost
nothing when they are not enabled.

## `log` vs. `print`

| | `print` | `log` |
|---|---|---|
| Stream | stdout | stderr |
| Always shown? | yes | only at/above the active level |
| Tagged with level? | no | yes |

Use `print` for a script's actual output — the thing a caller pipes or captures.
Use `log` for the running commentary about *how* it is going, which you want to
turn up or down without editing the script.

```lua
local rows = con:query("SELECT * FROM users")
log.info("fetched", #rows, "rows")    -- diagnostic; hidden unless RUST_LOG=info
for _, r in ipairs(rows) do
    print(r.name)                      -- the actual result
end
```

## Notes

- **Always loaded.** No `require`; `log` is a global in every script.
- **Quiet by default.** With no `RUST_LOG` set, only `warn`/`error` are emitted,
  so `info`/`debug`/`trace` are silent until you opt in.
- **Arguments are stringified like `print`.** Multiple arguments are joined with
  tabs; tables print as their address, so use `utils.dump` for contents.