diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..e8f8dc64829acd6c64698398b740958f7c645296
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# zig-tracer
+
+Generic tracing library for Zig, supports multiple backends.
+
+## Install
+
+- Supports Zigmod
+- Supports Zig package manager
+
+## Usage
+
+in your program:
+
+```zig
+const std = @import("std");
+const tracer = @import("tracer");
+const build_options = @import("build_options");
+
+pub const tracer_impl = tracer.spall; // supports none, log, spall out of the box
+
+pub fn main() !void {
+    try tracer.init();
+    defer tracer.deinit();
+
+    // main loop
+    while (true) {
+        try tracer.init2();
+        defer tracer.deinit2();
+
+        handler();
+    }
+}
+
+fn handler() void {
+    const t = tracer.trace(@src());
+    defer t.end();
+}
+```
+
+`@src()` values are absolute paths so backends use this value to trim it to only log relative paths
+
+```zig
+exe_options.addOption(usize, "src_file_trimlen", std.fs.path.dirname(std.fs.path.dirname(@src().file).?).?.len);
+```
+
+## License
+
+MIT