add a section about logging to the README. Reformat long lines for ea…

…sier editiing.

README.md

@@ -3,17 +3,25 @@
 
 # Blazingly fast, low latency actors for Golang
 
-Hollywood is an ULTRA fast actor engine build for speed and low-latency applications. Think about game servers, advertising brokers, trading engines, etc... It can handle **10 million messages in under 1 second**.
+Hollywood is an ULTRA fast actor engine build for speed and low-latency applications. Think about game servers,
+advertising brokers, trading engines, etc... It can handle **10 million messages in under 1 second**.
 
 ## What is the actor model?
 
-The Actor Model is a computational model used to build highly concurrent and distributed systems. It was introduced by Carl Hewitt in 1973 as a way to handle complex systems in a more scalable and fault-tolerant manner.
+The Actor Model is a computational model used to build highly concurrent and distributed systems. It was introduced by
+Carl Hewitt in 1973 as a way to handle complex systems in a more scalable and fault-tolerant manner.
 
-In the Actor Model, the basic building block is an actor, called receiver in Hollywood, which is an independent unit of computation that communicates with other actors by exchanging messages. Each actor has its own state and behavior, and can only communicate with other actors by sending messages. This message-passing paradigm allows for a highly decentralized and fault-tolerant system, as actors can continue to operate independently even if other actors fail or become unavailable.
+In the Actor Model, the basic building block is an actor, called receiver in Hollywood, which is an independent unit of
+computation that communicates with other actors by exchanging messages. Each actor has its own state and behavior, and
+can only communicate with other actors by sending messages. This message-passing paradigm allows for a highly
+decentralized and fault-tolerant system, as actors can continue to operate independently even if other actors fail or
+become unavailable.
 
-Actors can be organized into hierarchies, with higher-level actors supervising and coordinating lower-level actors. This allows for the creation of complex systems that can handle failures and errors in a graceful and predictable way.
+Actors can be organized into hierarchies, with higher-level actors supervising and coordinating lower-level actors. This
+allows for the creation of complex systems that can handle failures and errors in a graceful and predictable way.
 
-By using the Actor Model in your application, you can build highly scalable and fault-tolerant systems that can handle a large number of concurrent users and complex interactions.
+By using the Actor Model in your application, you can build highly scalable and fault-tolerant systems that can handle a
+large number of concurrent users and complex interactions.
 
 ## Features
 
@@ -44,9 +52,10 @@ go get github.com/anthdm/hollywood/...
 
 # Quickstart
 
-> The **[examples](https://github.com/anthdm/hollywood/tree/master/examples)** folder is the best place to learn and explore Hollywood.
+> The **[examples](https://github.com/anthdm/hollywood/tree/master/examples)** folder is the best place to learn and
+> explore Hollywood.
 
-```Go
+```go
 type message struct {
 	data string
 }
@@ -78,8 +87,8 @@ func main() {
 
 ## Spawning receivers with configuration
 
-```Go
-e.Spawn(newFoo, "foo",
+```go
+    e.Spawn(newFoo, "foo",
 	actor.WithMaxRestarts(4),
 	actor.WithInboxSize(1024 * 2),
 	actor.WithTags("bar", "1"),
@@ -125,44 +134,82 @@ time.Sleep(time.Second)
 
 ## Customizing the Engine
 
-```Go
-cfg := actor.Config{
+```go
+    cfg := actor.Config{
 	PIDSeparator: "->",
-}
-e := actor.NewEngine(cfg)
+    }
+    e := actor.NewEngine(cfg)
 ```
 
 After configuring the Engine with a custom PID Separator the string representation of PIDS will look like this:
 
-```Go
-pid := actor.NewPID("127.0.0.1:3000", "foo", "bar", "baz", "1")
-// 127.0.0.1:3000->foo->bar->baz->1
+```go
+    pid := actor.NewPID("127.0.0.1:3000", "foo", "bar", "baz", "1")
+    // 127.0.0.1:3000->foo->bar->baz->1
 ```
 
+Note that you can also provide a custom logger to the engine. See the Logging section for more details.
+
 ## Custom middleware
 
-You can add custom middleware to your Receivers. This can be usefull for storing metrics, saving and loading data for your Receivers on `actor.Started` and `actor.Stopped`.
+You can add custom middleware to your Receivers. This can be usefull for storing metrics, saving and loading data for
+your Receivers on `actor.Started` and `actor.Stopped`.
 
-For examples on how to implement custom middleware, check out the middleware folder in the **[examples](https://github.com/anthdm/hollywood/tree/master/examples/middleware)**
+For examples on how to implement custom middleware, check out the middleware folder in the *
+*[examples](https://github.com/anthdm/hollywood/tree/master/examples/middleware)**
 
 ## Logging
 
-You can set the log level of Hollywoods log module:
+The default for Hollywood is, as any good library, not to log anything, but rather to rely on the application to
+configure logging as it sees fit. However, as a convenience, Hollywood provides a simple logging package that
+you can use to gain some insight into what is going on inside the library.
 
-```Go
-import "github.com/anthdm/hollywood/log
+When you create a Hollywood engine, you can provide an optional actor configuration. This gives you the opportunity to
+have the log package create a suitable logger. The logger will be based on the standard library's `log/slog` package.
 
-log.SetLevel(log.LevelInfo)
-```
+If you want Hollywood to log with its defaults, it will provide structured logging with the loglevel being `ÌNFO`.
+You'll then initialize the engine as such:
 
-To disable all logging
+```go
+    engine := actor.NewEngine(actor.Config{Logger: log.Default()})
+```
 
-```Go
-import "github.com/anthdm/hollywood/log
+If you want more control, say by having having the loglevel be DEBUG and the output format be JSON, you can do so by
 
-log.SetLevel(log.LevelPanic)
+```go
+    lh := log.NewHandler(os.Stdout, log.JsonFormat, slog.LevelDebug)
+    engine := actor.NewEngine(actor.Config{Logger: log.NewLogger("[engine]", lh)})
 ```
 
+This will have the engine itself log with the field "log", prepopulated with the value "[engine]" for the engine itself.
+The various subsystems will change the log field to reflect their own name.
+
+### Log levels
+
+The log levels are, in order of severity:
+
+* `slog.LevelDebug`
+* `slog.LevelInfo`
+* `slog.LevelWarn`
+* `slog.LevelError`
+
+### Log components.
+
+The log field "log" will be populated with the name of the subsystem that is logging. The subsystems are:
+
+* `[engine]`
+* `[context`
+* `[deadLetter]`
+* `[eventStream]`
+* `[registry]`
+* `[stream_reader]`
+* `[stream_writer]`
+* `[stream_router]`
+
+In addition, the logger will log with log=$ACTOR_NAME for any actor that has a name.
+
+See the log package for more details about the implementation.
+
 # Test
 
 ```