From 2d2ce95fb843aa5626b8a40fbfa9ba24ad4b117b Mon Sep 17 00:00:00 2001
From: William Perron <hey@wperron.io>
Date: Tue, 6 Feb 2024 08:56:49 -0500
Subject: [PATCH] improve README

---
 README.md          | 38 +++++++++++++++++++++++++++++++++++++-
 sqlite_exporter.go |  1 +
 2 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 7bcb0cd..8054f30 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,39 @@
 # sqliteexporter
 
-Sqlite exporter for the OpenTelemetry Collector
\ No newline at end of file
+Sqlite exporter for the OpenTelemetry Collector and OpenTelemetry Go.
+
+Note that this is an alpha release, tables and column names may change in the
+future. [golang-migrate](https://pkg.go.dev/github.com/golang-migrate/migrate/v4)
+is used to manage updates to the database schema.
+
+## Configuration Options
+
+* `path` [no default]: Path to the Sqlite database file. If the file does not
+  exist, it will be created on startup.
+
+## Example
+
+```yaml
+exporters:
+  sqlite:
+    path: local.db
+```
+
+## Tables
+
+Currently, this exporter creates 3 tables to store trace span data:
+
+* `spans`: Each individual spans
+* `events`: Span events, with a `span_id` to JOIN with the `spans` table
+* `links`: Span links, with a `parent_span_id` to JOIN with the `spans` table
+
+The Resource and Instrumentation Library are inlined in the `spans` table. This
+creates some duplication but makes the schema much easier to navigate and query.
+Attributes are inlined as JSON-encoded string and can be queried using Sqlite's
+[JSON functions and operators](https://www.sqlite.org/json1.html).
+
+## Note on JSONB data type
+
+Sqlite recently added [support for the JSONB data type](https://sqlite.org/draft/jsonb.html)
+which improves performance on JSON-encoded data. Support for this feature is
+planned for the future.
diff --git a/sqlite_exporter.go b/sqlite_exporter.go
index 1e1c4cc..d8d1ebf 100644
--- a/sqlite_exporter.go
+++ b/sqlite_exporter.go
@@ -80,6 +80,7 @@ func (e *sqliteExporter) Shutdown(ctx context.Context) error {
 	return e.db.Close()
 }
 
+// TODO(wperron) add instrumentation library (scope) name and version
 const insertSpanQ string = `INSERT INTO spans
 (
     span_id,