You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
86 lines
3.1 KiB
86 lines
3.1 KiB
# `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.
|
|
|