@@ -900,12 +900,39 @@ reconnectPort them = do
900900--------------------------------------------------------------------------------
901901
902902-- | Send a message to the internal (system) trace facility. If tracing is
903−-- enabled, this will create a custom trace event in the event log. Specifically,
904−-- the environment variable @DISTRIBUTED_PROCESS_TRACE_FILE@ is set to a valid
905−-- path, then trace output will be written to that file. Otherwise, if the GHC
906−-- eventlog is enabled (i.e., you've compiled with @-eventlog@ set) and the
907−-- relevant @+RTS@ options given, then the message will be sent to the event log.
908−-- If neither facility is in use then trace messages will be silently dropped.
903+-- enabled, this will create a custom trace event. Note that several Cloud Haskell
904+-- sub-systems also generate trace events for informational/debugging purposes,
905+-- thus traces generated this way will not be the only output seen.
906+--
907+-- Just as with the "Debug.Trace" module, this is a debugging/tracing facility
908+-- for use in development, and should not be used in a production setting -
909+-- which is why the default behaviour is to trace to the GHC eventlog. For a
910+-- general purpose logging facility, you should consider 'say'.
911+--
912+-- Trace events can be written to the GHC event log, a text file, or to the
913+-- standard system logger process (see 'say'). The default behaviour for writing
914+-- to the eventlog requires specific intervention to work, without which traces
915+-- are silently dropped/ignored and no output will be generated.
916+-- The GHC eventlog documentation provides information about enabling, viewing
917+-- and working with event traces: <http://hackage.haskell.org/trac/ghc/wiki/EventLog>.
918+--
919+-- When a new local node is started, the contents of the environment variable
920+-- @DISTRIBUTED_PROCESS_TRACE_FILE@ are checked for a valid file path. If this
921+-- exists and the file can be opened for writing, all trace output will be directed
922+-- thence. If the environment variable is empty, the path invalid, or the file
923+-- unavailable for writing - e.g., because another node has already started
924+-- tracing to it - then the @DISTRIBUTED_PROCESS_TRACE_CONSOLE@ environment
925+-- variable is checked for /any/ non-empty value. If this is set, then all trace
926+-- output will be directed to the system logger process. If neither evironment
927+-- variable provides a valid trace configuration, all internal traces are written
928+-- to "Debug.Trace.traceEventIO", which writes to the GHC eventlog.
929+--
930+-- Users of the /simplelocalnet/ Cloud Haskell backend should also note that
931+-- because the trace file option only supports trace output from a single node
932+-- (so as to avoid interleaving), a file trace configured for the master node will
933+-- prevent slaves from tracing to the file and they will fall back to using the
934+-- console/'say' or eventlog instead.
935+--
909936trace :: String -> Process ()
910937trace s = do
911938 node <- processNode <$> ask