carlos / carloku Public

Download this file

1	# Logs
2
3	`carlos logs` is one timeline rather than two. Your app's own stdout and
4	stderr come back interleaved with the platform's account of what happened to
5	it — which instance woke and on what version, when something restarted it,
6	and when a wake failed, with the reason.
7
8	```sh
9	carlos logs -app hello -since 1h
10	```
11
12	Lines print oldest to newest: a UTC timestamp, the stream, the instance, the
13	message, and any structured fields your app attached, dimmed at the end.
14
15	## Following
16
17	`-f` leaves the command running and polls for new lines every two seconds.
18
19	```sh
20	carlos logs -app hello -f
21	```
22
23	It runs close to live, not exactly live. Boxes ship what they have collected
24	every ten seconds or so, so a follow arrives in small batches instead of
25	scrolling a character at a time. Start one before a deploy and you will see
26	the wake and the first requests.
27
28	## Cutting it down
29
30	An hour of a busy app is more than anyone reads. `-since` takes a duration
31	back from now (`15m`, `24h`) or an RFC3339 timestamp, and `-until` closes the
32	far end of the window. `-grep` matches an RE2 pattern against the message.
33	`-host` narrows to a single instance when the app runs more than one. `-n`
34	caps how many lines come back — a thousand by default, five thousand at most
35	— and when the window has more than that, it tells you it is showing the
36	newest.
37
38	There is also `-stream`. `-stream app` drops the platform's commentary and
39	leaves your own output; `-stream platform` does the opposite.
40
41	## The half you can't get any other way
42
43	Your app's output you could always have arranged for yourself. The platform
44	stream is the part that needs a view from outside the process: `instance woke
45	(version a1b2c3)`, `instance restarting (carlos restart)`, `instance
46	stopping`, and — when a request got a 503 you cannot reproduce — a wake
47	failure written in terms you can act on, like a socket left behind by a
48	previous run, or nothing promoted on the channel this instance follows.
49
50	A static site has no process and so has no app stream at all. Its platform
51	events still show up, and they are the reason to run `carlos logs` against a
52	site.
53
54	## How far back it goes
55
56	Seven days, and a size ceiling per app that drops the oldest hour first if
57	an app is unusually chatty. If you need a longer record than that, have the
58	app ship its own copy somewhere; the platform's retention is sized for
59	debugging this week.
60
61	An empty result is usually honest, and worth a second look. Platform
62	events only happen when something happens — a wake, a restart, a failure —
63	so a quiet hour of a quiet app really does have nothing in it. Widen to
64	`-since 24h` before you conclude that logging is broken.
65
66	The remaining flags, including `-level` and the repeatable `-field`, are in
67	[carlos logs](https://carlosframework.com/docs/cli/#carlos-logs).
68