Update example and documentation

Author: kolesnikovae

README.md

@@ -1,12 +1,14 @@
 # .Net diagnostics
 
-*Work In Progress*
-
 The package provides means for .Net runtime diagnostics implemented in Golang:
  - [Diagnostics IPC Protocol](https://github.com/dotnet/diagnostics/blob/main/documentation/design-docs/ipc-protocol.md#transport) client.
  - [NetTrace](https://github.com/microsoft/perfview/blob/main/src/TraceEvent/EventPipe/EventPipeFormat.md) decoder.
 
-### Diagnostics IPC Protocol Client
+### Diagnostic IPC Client
+
+```
+# go get github.com/pyroscope-io/dotnetdiag
+```
 
 Supported .Net versions:
  - .Net 5.0
@@ -26,4 +28,17 @@ Implemented commands:
  - [ ] ProcessInfo
  - [ ] ResumeRuntime
 
-See [examples](examples) directory. 
+### NetTrace decoder
+
+```
+# go get github.com/pyroscope-io/dotnetdiag/nettrace
+```
+
+Supported format versions: <= 4
+
+The decoder deserializes `NetTrace` binary stream to the object sequence. The package also provides an example stream
+handler implementation which processes **Microsoft-DotNETCore-SampleProfiler**
+events: [github.com/pyroscope-io/dotnetdiag/nettrace/profiler](github.com/pyroscope-io/dotnetdiag/nettrace/profiler).
+
+See [examples](examples) directory.
+

examples/tracing/README.md

@@ -1,26 +1,16 @@
 # Collect Tracing
 
-The example demonstrates how the package may be used to collect NetTrace stream data using Diagnostics IPC:
-the program streams traces produced with `Microsoft-DotNETCore-SampleProfiler` provider to a file.
+The example demonstrates how the package may be used to collect and process `NetTrace` stream data using Diagnostics IPC:
+the program processes events produced with **Microsoft-DotNETCore-SampleProfiler** provider and creates a sampled profile,
+rendered as a call tree.
 
 1. Run dotnet application.
 2. Find its PID, e.g.:
    ```
    # dotnet-trace ps
    ```
 
-3. Find Diagnostics IPC socket/pipe created by the application, e.g.:
-    - Linux/MacOS:
-      ```
-      # lsof -p {PID} | grep dotnet-diagnostic
-      ```
-
-4. Run the example program:
-   ```
-   # collect -s {absolute-path-to-socket} -o {path-to-nettrace-output-file}
-   ```   
-
-5. (Optional) Verify output file:
+3. Build and run the example program:
    ```
-   # dotnet-trace convert --format speedscope -o {path-to-output-file} {path-to-nettrace-file}
+   # go run ./examples/tracing -p {pid}
    ```

examples/tracing/collect.go

@@ -2,35 +2,30 @@ package main
 
 import (
 	"flag"
+	"fmt"
 	"io"
 	"log"
 	"os"
 	"os/signal"
+	"strconv"
+	"strings"
 
 	"github.com/pyroscope-io/dotnetdiag"
+	"github.com/pyroscope-io/dotnetdiag/nettrace"
+	"github.com/pyroscope-io/dotnetdiag/nettrace/profiler"
 )
 
 func main() {
-	var (
-		socketFilePath string
-		outputFilePath = "my-traces.nettrace"
-	)
-
-	flag.StringVar(&socketFilePath, "s", "", "Path to Diagnostic IPC socket")
-	flag.StringVar(&outputFilePath, "o", "my-traces.nettrace", "Output file.")
+	var ps string
+	flag.StringVar(&ps, "p", "", "Target process ID")
 	flag.Parse()
 
-	if socketFilePath == "" {
-		log.Fatalln("Diagnostic IPC socket path is required.")
-	}
-
-	file, err := os.Create(outputFilePath)
+	pid, err := strconv.Atoi(ps)
 	if err != nil {
-		log.Fatalln(err)
+		log.Fatalln("Invalid PID:", err)
 	}
-	defer file.Close()
 
-	c := dotnetdiag.NewClient(socketFilePath)
+	c := dotnetdiag.NewClient(dotnetdiag.DefaultServerAddress(pid))
 	ctc := dotnetdiag.CollectTracingConfig{
 		CircularBufferSizeMB: 10,
 		Providers: []dotnetdiag.ProviderConfig{
@@ -57,9 +52,45 @@ func main() {
 		}
 	}()
 
-	if _, err = io.Copy(file, sess); err != nil {
+	// Process the stream with the sample profiler.
+	stream := nettrace.NewStream(sess)
+	trace, err := stream.Open()
+	if err != nil {
+		_ = sess.Close()
 		log.Fatalln(err)
 	}
 
-	log.Println("Done")
+	p := profiler.NewSampleProfiler(trace)
+	stream.EventHandler = p.EventHandler
+	stream.MetadataHandler = p.MetadataHandler
+	stream.StackBlockHandler = p.StackBlockHandler
+	stream.SequencePointBlockHandler = p.SequencePointBlockHandler
+
+	log.Println("Collecting trace log")
+	for {
+		switch err = stream.Next(); err {
+		default:
+			log.Fatalln(err)
+		case nil:
+			continue
+		case io.EOF:
+			p.Walk(treePrinter(os.Stdout))
+			log.Println("Done")
+			return
+		}
+	}
+}
+
+func treePrinter(w io.Writer) func(profiler.FrameInfo) {
+	return func(frame profiler.FrameInfo) {
+		_, _ = fmt.Fprintf(w, "%s(%v) %s\n", padding(frame.Level), frame.SampledTime, frame.Name)
+	}
+}
+
+func padding(x int) string {
+	var s strings.Builder
+	for i := 0; i < x; i++ {
+		s.WriteString("\t")
+	}
+	return s.String()
 }