log stack traces

docs/logging.md

@@ -87,7 +87,7 @@ exclude = ["console"]
 **json** — structured JSONL (one JSON object per line). Used for file sinks and machine consumption.
 
 ```json
-{"actor_id":"a3f12...","timestamp":1702656000.5,"channel":"console","event":"server started","source":{"file":"main.ce","line":5,"column":3,"function":"init"}}
+{"actor_id":"a3f12...","timestamp":1702656000.5,"channel":"console","event":"server started","source":{"file":"main.ce","line":5,"col":3,"fn":"init"}}
 ```
 
 ## Log Records
@@ -103,14 +103,44 @@ Every log call produces a record:
   source: {
     file: "main.ce",
     line: 5,
-    column: 3,
-    function: "init"
+    col: 3,
+    fn: "init"
   }
 }
 ```
 
 File sinks write one JSON-encoded record per line. Console sinks format the record according to their format setting.
 
+## Stack Traces
+
+Set `stack = true` at the top level of `.cell/log.toml` to capture a full call stack with every log record.
+
+```toml
+stack = true
+
+[sink.terminal]
+type = "console"
+format = "pretty"
+channels = ["console", "error"]
+```
+
+With pretty format, the stack is printed indented below each message:
+
+```
+[a3f12] [error] server.ce:42 connection failed
+    at handle_request (server.ce:42:3)
+    at process (router.ce:18:5)
+    at main (main.ce:5:1)
+```
+
+With JSON format, a `stack` array is added to the record:
+
+```json
+{"actor_id":"a3f12...","channel":"error","event":"connection failed","source":{"file":"server.ce","line":42,"col":3,"fn":"handle_request"},"stack":[{"fn":"handle_request","file":"server.ce","line":42,"col":3},{"fn":"process","file":"router.ce","line":18,"col":5},{"fn":"main","file":"main.ce","line":5,"col":1}]}
+```
+
+When `stack` is not set or `false`, no stack is captured and the `stack` field is omitted from records. Capturing stacks adds overhead — enable it for debugging, not production.
+
 ## CLI
 
 The `pit log` command manages sinks and reads log files. See [CLI — pit log](/docs/cli/#pit-log) for the full reference.