From 5e2ee3f9f12ecc3e9cb7ed3a9670e70abdb01d5d Mon Sep 17 00:00:00 2001
From: Matthew Butterick <mb@mbtype.com>
Date: Mon, 16 Mar 2020 13:06:44 -0700
Subject: [PATCH] docs for logging

---
 pollen/private/ts.rktd        |  2 +-
 pollen/scribblings/raco.scrbl | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/pollen/private/ts.rktd b/pollen/private/ts.rktd
index 1713bb5..f4d32b5 100644
--- a/pollen/private/ts.rktd
+++ b/pollen/private/ts.rktd
@@ -1 +1 @@
-1584387916
+1584389204
diff --git a/pollen/scribblings/raco.scrbl b/pollen/scribblings/raco.scrbl
index a4785ea..2e09d37 100644
--- a/pollen/scribblings/raco.scrbl
+++ b/pollen/scribblings/raco.scrbl
@@ -216,4 +216,37 @@ Result is DEBUG
 
 }
 
+@section{Logging & the @exec{PLTSTDERR} environment variable}
+
+@margin-note{See @secref["logging" #:doc '(lib "scribblings/reference/reference.scrbl")] for an introduction to Racket's logging system.}
+
+By default, Pollen will log messages at the @racket['info] level or above to the console during any terminal session (e.g., project server or rendering job). So if you start the project server like so:
+
+@terminal{
+> raco pollen start
+} 
+
+You will see log messages starting with:
+
+@terminal{
+pollen: starting project server ...
+}
+
+And so forth.
+
+You can use Racket's @racket[PLTSTDERR] environment variable to adjust the level of logging. If you provide an explicit log level for Pollen, it will override this default behavior. So if you only want to see messages at the @racket['error] level or above, you would invoke the project server like so:
+
+@terminal|{
+> PLTSTDERR=error@pollen raco pollen start
+}|
+
+After this, the project server will work normally, but you won't see the usual @racket['info]-level messages, and instead will only see @racket['error] messages or above.
+
+Conversely, if you want more detailed logging, you can invoke the @racket['debug] log level like so:
+
+@terminal|{
+> PLTSTDERR=debug@pollen raco pollen start
+}|
+
+Then you'll see the usual @racket['info] messages, plus a bunch more.