README: document tracing

README.md

@@ -20,6 +20,7 @@ We currently provide three implementations:
 - [Install](#install)
 - [Usage](#usage)
 - [Documentation](#documentation)
+- [Tracing](#tracing)
 - [Contribute](#contribute)
 - [License](#license)
 
@@ -43,6 +44,41 @@ See the [libp2p specs](https://github.com/libp2p/specs/tree/master/pubsub) for h
 and [godoc](https://godoc.org/github.com/libp2p/go-libp2p-pubsub) for API documentation.
 
 
+## Tracing
+
+The pubsub system supports _tracing_, which collects all events pertaining to the internals of the system.
+This allows you to recreate the complete message flow and state of the system for analysis purposes.
+
+To enable tracing, instantiate the pubsub system using the `WithEventTracer` option; the option
+accepts a tracer with three available implementations in-package (trace to json, pb, or a remote peer).
+If you want to trace using a remote peer, you can do so using the `traced` daemon from [go-libp2p-pubsub-tracer](https://github.com/libp2p/go-libp2p-pubsub-tracer). The package also includes a utility program, `tracestat`, for analyzing the traces collected by the daemon.
+
+For instance, to capture the trace as a json file, you can use the following option:
+```go
+pubsub.NewGossipSub(..., pubsub.NewEventTracer(pubsub.NewJSONTracer("/path/to/trace.json")))
+```
+
+To capture the trace as a protobuf, you can use the following option:
+```go
+pubsub.NewGossipSub(..., pubsub.NewEventTracer(pubsub.NewPBTracer("/path/to/trace.pb")))
+```
+
+Finally, to use the remote tracer, you can use the following incantations:
+```go
+// assuming that your tracer runs in x.x.x.x and has a peer ID of QmTracer
+pi, err := peer.AddrInfoFromP2pAddr(ma.StringCast("/ip4/x.x.x.x/tcp/4001/p2p/QmTracer"))
+if err != nil {
+  panic(err)
+}
+
+tracer, err := pubsub.NewRemoteTracer(ctx, host, pi)
+if err != nil {
+  panic(err)
+}
+
+ps, err := pubsub.NewGossipSub(..., pubsub.WithEventTracer(tracer))
+```
+
 ## Contribute
 
 Contributions welcome. Please check out [the issues](https://github.com/libp2p/go-libp2p-pubsub/issues).