From 44a3f7ea159426705c0754ef0bfd3c41f12a7d94 Mon Sep 17 00:00:00 2001
From: Tzanko Matev <tsanko@gmail.com>
Date: Thu, 11 Sep 2025 11:36:21 +0300
Subject: [PATCH] Add tutorial document

---
 README.md                 |  5 ++++
 docs/tutorial.md          | 57 +++++++++++++++++++++++++++++++++++++++
 runtime_tracing/README.md |  5 ++++
 3 files changed, 67 insertions(+)
 create mode 100644 docs/tutorial.md

diff --git a/README.md b/README.md
index befff32..3c8cea9 100644
--- a/README.md
+++ b/README.md
@@ -40,6 +40,11 @@ There are some actual usages of it as well which can be also used as an example:
 
 One can always directly produce the same traces from various languages. We're open for cooperation or discussion on usecases!
 
+### Tutorial
+
+For a step-by-step guide on recording traces with this crate, see the
+[tutorial](docs/tutorial.md).
+
 ### Building the Documentation
 
 The library API docs can be built locally with:
diff --git a/docs/tutorial.md b/docs/tutorial.md
new file mode 100644
index 0000000..9a6183c
--- /dev/null
+++ b/docs/tutorial.md
@@ -0,0 +1,57 @@
+# Tutorial: Recording a Trace with `runtime_tracing`
+
+This guide shows how to capture execution data from a program and write it in the
+`runtime_tracing` format.
+
+## Add the crate
+
+Add the library to your `Cargo.toml`:
+
+```toml
+runtime_tracing = "0.14.1"
+```
+
+## Basic usage
+
+Create a `NonStreamingTraceWriter`, record a few events and store them as JSON.
+
+```rust
+use runtime_tracing::{
+    NonStreamingTraceWriter, TraceEventsFileFormat, TraceWriter, Line,
+    TypeKind, ValueRecord, NONE_VALUE,
+};
+use std::path::Path;
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    // Prepare the tracer
+    let mut tracer = NonStreamingTraceWriter::new("example_program", &[]);
+    tracer.set_format(TraceEventsFileFormat::Json);
+
+    // Record some events
+    let src = Path::new("example.rs");
+    tracer.start(src, Line(1));
+    tracer.register_step(src, Line(1));
+
+    let value = ValueRecord::Int {
+        i: 42,
+        type_id: tracer.ensure_type_id(TypeKind::Int, "i32"),
+    };
+    tracer.register_variable_with_full_value("answer", value);
+    tracer.register_return(NONE_VALUE);
+
+    // Write the trace files
+    tracer.begin_writing_trace_metadata(Path::new("trace_metadata.json"))?;
+    tracer.begin_writing_trace_paths(Path::new("trace_paths.json"))?;
+    tracer.begin_writing_trace_events(Path::new("trace.json"))?;
+    tracer.finish_writing_trace_events()?;
+    tracer.finish_writing_trace_metadata()?;
+    tracer.finish_writing_trace_paths()?;
+    Ok(())
+}
+```
+
+This minimal example generates the three JSON files expected by the
+CodeTracer debugger.
+
+For more complex scenarios, such as streaming traces or binary formats,
+see the APIs in `tracer.rs` and the tests in `src/lib.rs`.
diff --git a/runtime_tracing/README.md b/runtime_tracing/README.md
index befff32..5f42ba2 100644
--- a/runtime_tracing/README.md
+++ b/runtime_tracing/README.md
@@ -40,6 +40,11 @@ There are some actual usages of it as well which can be also used as an example:
 
 One can always directly produce the same traces from various languages. We're open for cooperation or discussion on usecases!
 
+### Tutorial
+
+For a step-by-step guide on recording traces with this crate, see the
+[tutorial](../docs/tutorial.md).
+
 ### Building the Documentation
 
 The library API docs can be built locally with: