wide_events 0.1.4 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab8bbc27c3a72a3efd7dbb3cb63453936a5f520b0a72e50ca8c89fa79d296a0b
-  data.tar.gz: 28a32dc6e3c7d98ac4b795c012e36ea8e02eb8a72dd4115f08ad7c808e27f251
+  metadata.gz: ea7b42dac2182e0b1c22f607629658f019943cf773cfc0398cdcfedbf9d4b311
+  data.tar.gz: 300d00038776858fce62fa359e9f08f6432d2fe3955fbf8b45f9a10480c73da5
 SHA512:
-  metadata.gz: f27aefb767cff731bc999fdec722d2a2ea0195dcd4e8d9d37b6f406c85725eed9a4594d279554a58fe27cdb8c5a92ac33f043ff9748439d546fb0825c3eba382
-  data.tar.gz: a3f1b8b6c52d66a045d08284fc101b036470509c571696f2f324c42451225db2f8e0dfaacac431aa2b966e8250761321f799387ab778c9c43a73f002497de6e9
+  metadata.gz: 393e3e6d00481ddc6500e4f1d9e1dd4d332f3d97a027b80e13008e8dec15ef5dc95e3a8a56d10780fbb847cb23fd7173d36764a3ec20489ca643c574e2496902
+  data.tar.gz: 22c83a1f6b26e27e0ede2e6e79aaa4cab933f188792e499e4c608844259d7c331f7f608bfcdf5d8456d9e1f7881b2fd1fdfe7b9e8e62cc7970baaf652ca3460c

data/CHANGELOG.md

@@ -1,5 +1,51 @@
 # Changelog
 
+## v0.2.1 (2026-08-06)
+
+- Fix the store image pin in the README. The v0.2.0 release rewrite turned
+  `ghcr.io/adammiribyan/wide-events-store:0.2.0` into `.2.0`.
+
+## v0.2.0 (2026-08-06)
+
+- **A bundled telemetry store.** `bin/rails generate wide_events:store
+  --host --hostname --retention-days` writes a Kamal accessory for
+  `ghcr.io/adammiribyan/wide-events-store:<version>`, a single-process Go
+  service around DuckDB, plus durable ingest and query tokens under
+  `.kamal/`. `kamal setup` deploys it and `kamal telemetry` opens a SQL
+  prompt against production. No collector and no OpenTelemetry SDK
+  required; `:otel` and `:log` keep working unchanged.
+- The `:store` sink batches, gzips, and delivers events on one background
+  thread per process, behind a bounded queue (1,000 events or 8 MiB) that
+  drops oldest-first and reports the count with the next batch. Batches are
+  idempotent by `batch_id`, so a response lost after the store committed is
+  retried and deduplicated instead of double-counted. The sender is
+  fork-aware.
+- `WIDE_EVENTS_URL` alone enables the gem and selects the store sink,
+  ahead of `OTEL_EXPORTER_OTLP_ENDPOINT`. `WIDE_EVENTS_SERVICE`,
+  `WIDE_EVENTS_ENVIRONMENT`, `WIDE_EVENTS_INGEST_TOKEN`, and
+  `WIDE_EVENTS_QUERY_TOKEN` complete the configuration; ingest and query
+  tokens must differ.
+- The store keeps `route`, `job_class`, `status`, `error`, `request_id`,
+  `duration_ms`, `kind`, `deployment`, and `source` as real columns and
+  everything else in an `attributes` VARIANT, read as
+  `attributes['key.name']::VARCHAR`. `wide_events_store_status` is the
+  one-row operational view. Queries are read-only and bounded: 2 running,
+  4 waiting, 15s, 10,000 rows, 10 MiB.
+- Retention deletes events past `WIDE_EVENTS_RETENTION_DAYS` daily, a
+  verified local backup runs alongside it (three newest kept, or on demand
+  via `kamal wide-events-backup`), and the store reserves the greater of
+  2 GiB or 10% of the volume as a write floor. Below it, ingest answers 507
+  while `/up` and queries keep working.
+- `bin/rails wide_events:setup:check` is the idempotent resume command for
+  the whole setup: Kamal version and config, host directory permissions,
+  DNS, and a synthetic round trip through the deployed endpoint.
+- A third bundled skill, `setting-up-wide-events-store`, walks an agent
+  through the deploy. `debugging-with-wide-events` gained the store's data
+  model and standing queries.
+- The generated accessory raises `minimum_version` to `2.10.0`: its
+  structured `directories` entry carries the `mode` and `owner` the DuckDB
+  volume needs, and older Kamal releases reject it.
+
 ## v0.1.4 (2026-08-04)
 
 - The railtie stores `registry_path` relative to the app root

data/README.md

@@ -5,7 +5,13 @@
 
 One wide telemetry event per Rails request or job execution, in a database you own.
 
-Wide Events collects everything your app knows about each unit of work (route, user, account, build SHA, query counts, cache hits, feature flags, phase timings, errors) into one flat, high-cardinality event on the OpenTelemetry root span you already export. Every request becomes one row, and every question becomes one query against storage you run. ClickHouse with HyperDX is a proven pairing (both open source); any OTLP backend works. If you'd rather not run tracing, the log sink emits one JSON event per request.
+Wide Events collects everything your app knows about each unit of work (route, user, account, build SHA, query counts, cache hits, feature flags, phase timings, errors) into one flat, high-cardinality event. Every request becomes one row, and every question becomes one query against storage you run.
+
+Three places to put those rows, in order of how much you have to operate:
+
+- **The bundled store.** A DuckDB service the gem ships as a Kamal accessory: one generator, one `kamal setup`, and `kamal telemetry` gives you a SQL prompt against production. No collector, no OTel SDK.
+- **Any OTLP backend.** The event goes onto the OpenTelemetry root span you already export. ClickHouse with HyperDX is a proven pairing (both open source).
+- **Your log store.** The log sink emits one JSON event per request.
 
 That format matters more now that agents build with you. Telemetry stops being something humans only glance at and becomes something software queries repeatedly: an agent can instrument a feature, deploy it, and verify it in production. One row per request is a dense way to feed production behavior back into a context window, and owning the storage avoids metered per-event and per-query observability fees.
 
@@ -41,9 +47,130 @@ grep '"main":true' log/development.log
 
 One JSON object per request: route, status, timings, query counts, everything.
 
+## Production in ten minutes: the bundled store
+
+The gem ships its own telemetry database: a single Go process around DuckDB, deployed as a Kamal accessory on a VM you own. No collector, no OTel SDK, no vendor account. One `bin/rails generate` writes the accessory, `kamal setup` deploys it, and `kamal telemetry` opens a SQL prompt against production.
+
+```bash
+bin/rails generate wide_events:store --host=203.0.113.20 --hostname=telemetry.example.com --retention-days=30
+```
+
+`--host` is the SSH address of the VM that will run the store. `--hostname` is the public DNS name the app and your SQL prompt reach it through; point an A record at the host now, so propagation happens while you finish the rest. The generator edits `config/deploy.yml` and writes two 64-hex tokens to `.kamal/wide-events-ingest-token` and `.kamal/wide-events-query-token` (mode 0600, gitignored, wired into `.kamal/secrets`). Every edit is marked and idempotent, so re-running it is safe. If your `config/deploy.yml` is shaped in a way the editor won't touch, it refuses and prints the complete block to merge by hand.
+
+Here's the accessory it adds:
+
+```yaml
+accessories:
+  wide_events:
+    image: ghcr.io/adammiribyan/wide-events-store:0.2.1
+    host: 203.0.113.20
+
+    proxy:
+      host: telemetry.example.com
+      ssl: true
+      app_port: 7421
+      healthcheck:
+        path: /up
+        interval: 3
+        timeout: 3
+
+    env:
+      clear:
+        WIDE_EVENTS_LISTEN: 0.0.0.0:7421
+        WIDE_EVENTS_DATABASE: /var/lib/wide-events/events.duckdb
+        WIDE_EVENTS_SERVICE: myapp
+        WIDE_EVENTS_ENVIRONMENT: production
+        WIDE_EVENTS_RETENTION_DAYS: 30
+      secret:
+        - WIDE_EVENTS_INGEST_TOKEN
+        - WIDE_EVENTS_QUERY_TOKEN
+
+    directories:
+      - local: /var/lib/myapp-wide-events
+        remote: /var/lib/wide-events
+        mode: "0750"
+        owner: "1000:1000"
+
+    options:
+      cpus: 2
+      memory: 2g
+```
+
+The structured `directories` entry is why the generator also raises `minimum_version` to `2.10.0`: older Kamal releases only accept a `local:remote` string and would mount the DuckDB volume without the mode and owner the container's uid/gid 1000 needs. On the app side it sets `WIDE_EVENTS_URL`, `WIDE_EVENTS_SERVICE`, and `WIDE_EVENTS_ENVIRONMENT` in `env.clear` and binds both tokens as secrets. Setting `WIDE_EVENTS_URL` is all it takes to switch the sink: the gem enables itself and sends to the store instead of an OTel span.
+
+Then, in order:
+
+```bash
+bin/rails wide_events:setup:check   # Kamal version, config, host directory, DNS, endpoint
+kamal setup
+bin/rails wide_events:setup:check   # sends one synthetic event and queries it back
+```
+
+`wide_events:setup:check` is the same command at every stage. It reports `failed`, `needs_dns`, `ready_to_deploy`, `degraded`, or `healthy`, and `needs_dns` is expected while an A record propagates: nothing is lost, run it again later. On a healthy store it writes one synthetic event, reads it back by id, and prints a route/p95 query, so you know ingest token, query token, TLS, and DuckDB all work before real traffic arrives.
+
+Working with an agent? `bin/rails generate wide_events:skills` installs the `setting-up-wide-events-store` skill, which walks an agent through this whole flow, including what to say about DNS waits and backup limitations.
+
+## Querying the store
+
+```bash
+kamal telemetry                                     # interactive SQL prompt
+echo "SELECT count(*) FROM wide_events" | kamal telemetry
+```
+
+Output is a text table by default. `bin/rails wide_events:sql` reads `WIDE_EVENTS_FORMAT` (`table`, `json`, or `csv`) from the environment it runs in, so set it in the app container, not in your local shell.
+
+`route`, `job_class`, `status`, `error`, `request_id`, `duration_ms`, `kind`, `deployment`, `source`, `occurred_at`, and `received_at` are real columns. Everything else the app set lives in an `attributes` VARIANT column, read as `attributes['key.name']` and cast to the type you want:
+
+```sql
+SELECT route,
+       count(*) AS requests,
+       quantile_cont(duration_ms, 0.5) AS p50_ms,
+       quantile_cont(duration_ms, 0.95) AS p95_ms
+FROM wide_events
+WHERE occurred_at > current_timestamp - INTERVAL 1 DAY
+GROUP BY route
+ORDER BY p95_ms DESC
+LIMIT 15
+```
+
+```sql
+-- Exceptions that escaped without a named handled failure
+SELECT route, attributes['exception.type']::VARCHAR AS exception_type, count(*) AS occurrences
+FROM wide_events
+WHERE error
+  AND coalesce(attributes['exception.slug']::VARCHAR, '') = ''
+  AND occurred_at > current_timestamp - INTERVAL 1 DAY
+GROUP BY route, exception_type
+ORDER BY occurrences DESC
+```
+
+`SELECT * FROM wide_events_store_status` is the one-row operational view: rows in the last hour and day, oldest and newest event, database and free-disk bytes, queued ingest bytes, rejected batches, reported dropped events, write readiness and why, last checkpoint/retention/backup times and errors, and the store, protocol, and DuckDB versions. Read it first whenever a query returns nothing.
+
+Queries are read-only and bounded: two run at a time with four more allowed to wait, 15 seconds of execution, 2 seconds of queueing, 10,000 rows, and 10 MiB of response. A statement that isn't a single `SELECT` is rejected by DuckDB's own parser before it runs.
+
+## Two tokens, two jobs
+
+The ingest token writes and the query token reads; the store refuses to start if they're equal. Sharing SQL access with a teammate or an agent means handing over `.kamal/wide-events-query-token` only, and never the ability to forge events. Both are 64 hex characters, generated once by the generator and reused on every later run.
+
+## Sizing, retention, and what happens when the disk fills
+
+One event is roughly 1 KB before compression. At 30-day retention, 100 requests/second is about 250 GB of raw rows before DuckDB's columnar compression, which typically lands 5-10x smaller; 10 requests/second fits comfortably in tens of gigabytes. Start with a 100 GB volume and 2 GB of RAM, watch `database_file_bytes` in the status view for a week, and resize from evidence.
+
+Retention runs once a day and deletes events older than `WIDE_EVENTS_RETENTION_DAYS`. The store reserves the greater of 2 GiB or 10% of the volume as a write floor. Below it, ingest answers `507` and the sender holds its batches, but `/up` still returns 200 and queries keep working, so you can diagnose a full disk from the store itself rather than by SSH.
+
+Loss is bounded and reported, never silent. Each app process queues up to 1,000 events or 8 MiB; past that, the oldest are dropped and the count travels with the next batch into `wide_events_loss_reports`, so a gap in the data is visible as a number. Batches are idempotent by `batch_id`, so a response lost after the store committed is retried and deduplicated instead of double-counted.
+
+## Backups, upgrades, and rollback
+
+A verified local backup runs daily and keeps the three newest copies in `backups/` next to the database. Take one on demand with `kamal wide-events-backup`, which prints the path it wrote.
+
+Backups are local only. They protect against a bad upgrade or a mistaken `DELETE`, not against losing the VM or its volume; there's no off-host copy in v1. If that matters for your deployment, snapshot the host volume on your provider's schedule. Restoring is manual: stop the accessory, replace `/var/lib/wide-events/events.duckdb` with the backup file, and start it again. Nothing but the store process may open the database; the admin socket exists so backups happen through the running owner instead of a second process touching the file.
+
+Upgrading is a gem bump. Each release publishes `ghcr.io/adammiribyan/wide-events-store:<version>` for linux/amd64 and linux/arm64. Re-run `bin/rails generate wide_events:store` with the same options to rewrite the pinned image, then `kamal accessory reboot wide_events` to pull it and restart. There is no `latest` tag on purpose, so an already-deployed accessory can't change under you on its next boot. Migrations are forward-only and run at startup: a store that finds a schema newer than it understands refuses to open rather than corrupting it. To roll back, pin the previous version by hand, and take a backup first if the newer release applied a migration.
+
 ## Production setup with OpenTelemetry
 
-The default sink writes the event onto the current OTel root span, which is the span OTel's Rack instrumentation opens at the top of the middleware stack. That means production needs an OpenTelemetry SDK configured; the gem detects it and wires itself after your initializers run. Minimal setup:
+Prefer an existing OTel pipeline, or already run ClickHouse? Skip the store. The `:otel` sink writes the event onto the current OTel root span, which is the span OTel's Rack instrumentation opens at the top of the middleware stack. That means production needs an OpenTelemetry SDK configured; the gem detects it and wires itself after your initializers run. Minimal setup:
 
 ```ruby
 # Gemfile
@@ -167,18 +294,22 @@ The teardown pattern makes the registry check work with parallel test workers: v
 
 | Environment | Typical setup | Result |
 |---|---|---|
+| Production / staging | `WIDE_EVENTS_URL` set (the store generator sets it) | Enabled automatically, `:store` sink, batched over HTTPS |
 | Production / staging | `OTEL_EXPORTER_OTLP_ENDPOINT` set | Enabled automatically, `:otel` sink, events on root spans |
 | Development | `config.enabled = true`, `config.sink = :log` | One JSON line per request in the log |
 | Test | Enabled via the test helper's capture, or strict mode for registry tracking | `capture_wide_events` collects them |
 
+`WIDE_EVENTS_URL` wins over `OTEL_EXPORTER_OTLP_ENDPOINT` when both are set.
+
 `WideEvent.install!` runs once at boot, only if enabled at that point. Flipping `config.enabled` at runtime gates the middleware and job hook (they check per request), but the span counter and subscribers only register at boot, so treat enablement as a boot-time decision.
 
 ## Built for the agent loop
 
-`bin/rails generate wide_events:skills` installs two agent skills:
+`bin/rails generate wide_events:skills` installs three agent skills:
 
 - **instrumenting-wide-events**: the write path. Naming conventions, when to use `set` vs `phase` vs `error!`, the registry workflow, PII rules, test assertions.
-- **debugging-with-wide-events**: the read path. Symptom-to-query workflow against ClickHouse/HyperDX or JSON logs, plus the standing queries worth running.
+- **debugging-with-wide-events**: the read path. Symptom-to-query workflow against the DuckDB store, ClickHouse/HyperDX, or JSON logs, plus the standing queries worth running.
+- **setting-up-wide-events-store**: the deploy path. Generator, DNS, `kamal setup`, and the checker states, end to end.
 
 Skills land in `.claude/skills/`, which Claude Code and Claude-compatible agents read. Other agents (Cursor, etc.) read the pointer the install generator appends to `AGENTS.md`; the SKILL.md files are plain markdown, so copy or symlink them wherever your tooling looks (`.cursor/rules/`, docs, a system prompt).
 
@@ -186,8 +317,13 @@ Skills land in `.claude/skills/`, which Claude Code and Claude-compatible agents
 
 ```ruby
 WideEvent.configure do |config|
-  config.enabled = ENV["OTEL_EXPORTER_OTLP_ENDPOINT"].present?  # default
-  config.sink = :otel               # :otel, :log, or any object responding to flush(attrs)
+  config.enabled = ENV["WIDE_EVENTS_URL"].present? || ENV["OTEL_EXPORTER_OTLP_ENDPOINT"].present?  # default
+  config.sink = :store              # :store, :otel, :log, or any object responding to flush(attrs)
+  config.store_url = ENV["WIDE_EVENTS_URL"]                    # HTTPS, except an explicit loopback URL
+  config.store_service = ENV["WIDE_EVENTS_SERVICE"]
+  config.store_environment = ENV["WIDE_EVENTS_ENVIRONMENT"]
+  config.store_ingest_token = ENV["WIDE_EVENTS_INGEST_TOKEN"]
+  config.store_query_token = ENV["WIDE_EVENTS_QUERY_TOKEN"]
   config.logger = nil               # :log sink target; defaults to Rails.logger
   config.strict = Rails.env.test?   # track attributes against the registry
   config.max_cache_attrs = 10
@@ -201,9 +337,11 @@ WideEvent.configure do |config|
 end
 ```
 
+Store sink notes: every store setting defaults to its `WIDE_EVENTS_*` environment variable, which the Kamal generator already sets, so most apps configure nothing here. Delivery happens on one background thread per process; application threads only append to a bounded in-memory queue and never block on the network. The sender is fork-aware, so Puma and Sidekiq workers each get their own queue instead of inheriting the parent's.
+
 Log sink notes: events go to `config.logger` (or `Rails.logger`) at info level as single-line JSON. Point it at a dedicated logger (`config.logger = Logger.new("log/wide_events.log")`) to keep them out of your main log, and leave the sink off in the test environment unless you want one JSON line per test request; `capture_wide_events` is the intended test-side tap.
 
-## Querying: ClickHouse + HyperDX
+## Querying an OTLP backend: ClickHouse + HyperDX
 
 [docs/clickhouse-hyperdx.md](https://github.com/adammiribyan/wide_events/blob/main/docs/clickhouse-hyperdx.md) has a local quickstart (one container) and a query cookbook. The flavor:
 
@@ -231,14 +369,17 @@ Flat keys, dot namespaces, snake_case leaves. Durations end in `_duration_ms`, c
 bin/setup                 # bundle install + appraisal gemfiles
 bundle exec rake test     # run the suite
 bin/rubocop               # lint (rubocop-rails-omakase)
+cd store && go test ./... # the DuckDB store service
 ```
 
-The CI matrix runs the suite across Ruby 3.2 to 4.0 and Rails 7.1 to main via [Appraisal](https://github.com/thoughtbot/appraisal); run a specific combination locally with `BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile bundle exec rake test`. Releases go out with `bin/release <version>`.
+The CI matrix runs the suite across Ruby 3.2 to 4.0 and Rails 7.1 to main via [Appraisal](https://github.com/thoughtbot/appraisal); run a specific combination locally with `BUNDLE_GEMFILE=gemfiles/rails_7_1.gemfile bundle exec rake test`. [CONTRIBUTING.md](https://github.com/adammiribyan/wide_events/blob/main/CONTRIBUTING.md) covers the store's Go, Docker, cross-runtime integration, and Kamal compatibility commands. Releases go out with `bin/release <version>`, which also publishes the matching store image.
 
 ## Requirements
 
 Ruby >= 3.2, Rails >= 7.1 (activesupport and rack are the only hard dependencies; opentelemetry-sdk and useragent are optional and detected at runtime).
 
+The bundled store needs a Linux VM with Docker and Kamal >= 2.10.0. Images are published for linux/amd64 and linux/arm64.
+
 ## License
 
 MIT.

data/lib/generators/wide_events/install/install_generator.rb

@@ -1,8 +1,11 @@
 require "rails/generators/base"
+require "generators/wide_events/skill_installer"
 
 module WideEvents
   module Generators
     class InstallGenerator < Rails::Generators::Base
+      include WideEvents::Generators::SkillInstaller
+
       source_root File.expand_path("templates", __dir__)
 
       def create_initializer
@@ -13,10 +16,21 @@ module WideEvents
         copy_file "registry.yml", "config/wide_event/registry.yml"
       end
 
+      def install_skills
+        copy_wide_events_skills
+      end
+
+      # Idempotent: a second run of this generator must not duplicate the
+      # section in an AGENTS.md it already added it to.
       def add_agents_section
         section = File.read(File.expand_path("templates/agents_md_section.md", __dir__))
-        if File.exist?(File.join(destination_root, "AGENTS.md"))
-          append_to_file "AGENTS.md", "\n#{section}"
+        path = File.join(destination_root, "AGENTS.md")
+        if File.exist?(path)
+          if File.read(path).include?(section.strip)
+            say_status :identical, "AGENTS.md"
+          else
+            append_to_file "AGENTS.md", "\n#{section}"
+          end
         else
           create_file "AGENTS.md", section
         end

data/lib/generators/wide_events/skill_installer.rb

@@ -0,0 +1,24 @@
+module WideEvents
+  module Generators
+    # Copies every bundled agent skill (skills/*/SKILL.md) into
+    # .claude/skills/<name>/SKILL.md. Shared by InstallGenerator (so a fresh
+    # `wide_events:install` sets up all three skills in one pass) and
+    # SkillsGenerator (a standalone way to add or refresh them later), so
+    # both stay byte-for-byte consistent and a new bundled skill only has to
+    # be wired up in one place.
+    #
+    # `copy_file` accepts an absolute source path regardless of the
+    # including generator's own `source_root`, so this mixes into either
+    # generator unchanged.
+    module SkillInstaller
+      SKILLS_ROOT = File.expand_path("../../../skills", __dir__)
+
+      def copy_wide_events_skills
+        Dir[File.join(SKILLS_ROOT, "*", "SKILL.md")].sort.each do |path|
+          name = File.basename(File.dirname(path))
+          copy_file path, ".claude/skills/#{name}/SKILL.md"
+        end
+      end
+    end
+  end
+end

data/lib/generators/wide_events/skills/skills_generator.rb

@@ -1,19 +1,21 @@
 require "rails/generators/base"
+require "generators/wide_events/skill_installer"
 
 module WideEvents
   module Generators
     # Copies the agent skills shipped with the gem into .claude/skills/ so
-    # coding agents pick up the instrumentation and debugging conventions.
+    # coding agents pick up the instrumentation, debugging, and store-setup
+    # conventions. A standalone way to add or refresh them later; a fresh
+    # `wide_events:install` already installs the same skills (see
+    # InstallGenerator), via the same WideEvents::Generators::SkillInstaller
+    # routine.
     class SkillsGenerator < Rails::Generators::Base
-      SKILLS_ROOT = File.expand_path("../../../../skills", __dir__)
+      include WideEvents::Generators::SkillInstaller
 
-      source_root SKILLS_ROOT
+      source_root SkillInstaller::SKILLS_ROOT
 
       def copy_skills
-        Dir[File.join(SKILLS_ROOT, "*", "SKILL.md")].sort.each do |path|
-          name = File.basename(File.dirname(path))
-          copy_file File.join(name, "SKILL.md"), ".claude/skills/#{name}/SKILL.md"
-        end
+        copy_wide_events_skills
       end
     end
   end

data/lib/generators/wide_events/store/store_generator.rb

@@ -0,0 +1,145 @@
+require "rails/generators/base"
+require "yaml"
+require "tempfile"
+require "fileutils"
+require "ipaddr"
+require "wide_event/version"
+require "wide_event/kamal/deploy_editor"
+require "wide_event/kamal/secrets_editor"
+
+module WideEvents
+  module Generators
+    # Wires the bundled wide_events store container into a host app's Kamal
+    # deployment: an accessory in config/deploy.yml plus durable ingest/query
+    # tokens under .kamal/. Delegates every structural decision to
+    # WideEvent::Kamal::DeployEditor and WideEvent::Kamal::SecretsEditor so
+    # this class only handles option parsing, Thor plumbing, and applying
+    # both edits as a single transaction: nothing is written to disk unless
+    # every preflight check on both editors has already succeeded.
+    class StoreGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      DNS_NAME_RE = /\A(?=.{1,253}\z)[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\z/
+
+      class_option :host, type: :string, desc: "SSH host/IP of the store VM (IP address or DNS name)"
+      class_option :hostname, type: :string, desc: "Public DNS hostname for the telemetry endpoint (no scheme/path)"
+      class_option :"retention-days", type: :string, default: "30", desc: "Event retention window, in days"
+      class_option :service, type: :string, desc: "Kamal service name (defaults to config/deploy.yml's service)"
+      class_option :environment, type: :string, default: "production", desc: "WIDE_EVENTS_ENVIRONMENT value"
+
+      def generate_accessory
+        host = options["host"]
+        hostname = options["hostname"]
+        retention_days = options["retention-days"]
+
+        return unless valid_options?(host, hostname, retention_days)
+
+        deploy_path = File.join(destination_root, "config/deploy.yml")
+        unless File.exist?(deploy_path)
+          say_status :error, "config/deploy.yml not found - run `kamal init` first, then re-run this generator", :red
+          return
+        end
+
+        service = options["service"] || default_service_name(deploy_path)
+        image = "ghcr.io/adammiribyan/wide-events-store:#{WideEvent::VERSION}"
+
+        deploy_result = WideEvent::Kamal::DeployEditor.new(
+          File.read(deploy_path),
+          service: service,
+          host: host,
+          hostname: hostname,
+          environment: options["environment"],
+          retention_days: retention_days.to_i,
+          image: image
+        ).apply
+
+        if deploy_result.conflicts.any?
+          say_status :refused, "config/deploy.yml was left unchanged - merge this by hand:", :red
+          say deploy_result.snippet
+          return
+        end
+
+        begin
+          secrets_result = WideEvent::Kamal::SecretsEditor.new(root: destination_root).apply
+        rescue WideEvent::Kamal::SecretsEditor::UnsafeTokenFile => e
+          say_status :error, e.message, :red
+          return
+        end
+
+        if deploy_result.changed?
+          atomic_write(deploy_path, deploy_result.content)
+          say_status :update, "config/deploy.yml"
+        else
+          say_status :identical, "config/deploy.yml"
+        end
+
+        secrets_result.write!
+        say_status :kamal, "wide_events store accessory ready - run `kamal setup` then `kamal telemetry`"
+      end
+
+      private
+
+      def valid_options?(host, hostname, retention_days)
+        unless present?(host) && valid_host?(host)
+          say_status :error, "--host must be an IP address or DNS name, got #{host.inspect}", :red
+          return false
+        end
+
+        unless present?(hostname) && valid_hostname?(hostname)
+          say_status :error, "--hostname must be a bare DNS name without scheme or path, got #{hostname.inspect}", :red
+          return false
+        end
+
+        unless positive_integer?(retention_days)
+          say_status :error, "--retention-days must be a positive integer, got #{retention_days.inspect}", :red
+          return false
+        end
+
+        true
+      end
+
+      def present?(value)
+        !value.nil? && !value.strip.empty?
+      end
+
+      def valid_host?(value)
+        ip_address?(value) || DNS_NAME_RE.match?(value)
+      end
+
+      def valid_hostname?(value)
+        return false if value.include?("/") || value.include?(":") || value.include?("@")
+
+        DNS_NAME_RE.match?(value)
+      end
+
+      def ip_address?(value)
+        IPAddr.new(value)
+        true
+      rescue IPAddr::Error
+        false
+      end
+
+      def positive_integer?(value)
+        value.to_s.match?(/\A[1-9][0-9]*\z/)
+      end
+
+      def default_service_name(deploy_path)
+        parsed = YAML.safe_load(File.read(deploy_path), permitted_classes: [], aliases: false)
+        service = parsed.is_a?(Hash) ? parsed["service"] : nil
+        service || File.basename(destination_root)
+      rescue Psych::Exception
+        File.basename(destination_root)
+      end
+
+      def atomic_write(path, content)
+        dir = File.dirname(path)
+        mode = File.exist?(path) ? File.stat(path).mode & 0o777 : 0o644
+        tmp = Tempfile.new(".wide_events_deploy", dir)
+        tmp.write(content)
+        tmp.close
+        File.chmod(mode, tmp.path)
+        FileUtils.mv(tmp.path, path)
+      end
+    end
+  end
+end

data/lib/generators/wide_events/store/templates/accessory.yml.erb

@@ -0,0 +1,33 @@
+wide_events:
+  image: <%= image %>
+  host: <%= host %>
+
+  proxy:
+    host: <%= hostname %>
+    ssl: true
+    app_port: 7421
+    healthcheck:
+      path: /up
+      interval: 3
+      timeout: 3
+
+  env:
+    clear:
+      WIDE_EVENTS_LISTEN: 0.0.0.0:7421
+      WIDE_EVENTS_DATABASE: /var/lib/wide-events/events.duckdb
+      WIDE_EVENTS_SERVICE: <%= service %>
+      WIDE_EVENTS_ENVIRONMENT: <%= environment %>
+      WIDE_EVENTS_RETENTION_DAYS: <%= retention_days %>
+    secret:
+      - WIDE_EVENTS_INGEST_TOKEN
+      - WIDE_EVENTS_QUERY_TOKEN
+
+  directories:
+    - local: <%= local_directory %>
+      remote: /var/lib/wide-events
+      mode: "0750"
+      owner: "1000:1000"
+
+  options:
+    cpus: 2
+    memory: 2g

data/lib/wide_event/configuration.rb

@@ -17,13 +17,26 @@ module WideEvent
     end
 
     attr_accessor :enabled, :max_cache_attrs, :span_scopes, :strict,
-                  :logger, :error_handler, :scheduled_job_detector
+                  :logger, :error_handler, :scheduled_job_detector,
+                  :store_url, :store_service, :store_environment,
+                  :store_ingest_token, :store_query_token
     attr_reader :sink, :registry_path
 
+    # A resolved store sink is unusable until its configuration
+    # (url/service/environment/ingest token) is valid; falls back to this
+    # silent no-op so a misconfigured store never raises into a flush.
+    NOOP_STORE_SINK = Object.new.tap { |sink| sink.define_singleton_method(:flush) { |_attrs| nil } }.freeze
+
     def initialize
-      @enabled = !ENV["OTEL_EXPORTER_OTLP_ENDPOINT"].to_s.empty?
-      @sink = :otel
+      @store_url = ENV["WIDE_EVENTS_URL"]
+      @enabled = @store_url.present? || ENV["OTEL_EXPORTER_OTLP_ENDPOINT"].present?
+      @sink = @store_url.present? ? :store : :otel
       @resolved_sink = nil
+      @store_service = ENV["WIDE_EVENTS_SERVICE"]
+      @store_environment = ENV["WIDE_EVENTS_ENVIRONMENT"]
+      @store_ingest_token = ENV["WIDE_EVENTS_INGEST_TOKEN"]
+      @store_query_token = ENV["WIDE_EVENTS_QUERY_TOKEN"]
+      @store_sender = nil
       @max_cache_attrs = 10
       @span_scopes = {
         "OpenTelemetry::Instrumentation::PG" => "postgres_query",
@@ -46,10 +59,18 @@ module WideEvent
       @resolved_sink ||= case @sink
       when :otel then Sinks::OtelSpan.new
       when :log then Sinks::LogLine.new(logger)
+      when :store then build_store_sink
       else @sink
       end
     end
 
+    # True once #resolved_sink has actually built (or attempted to build) a
+    # sink; lets WideEvent.shutdown! avoid constructing one from scratch
+    # just to shut it down.
+    def resolved?
+      !@resolved_sink.nil?
+    end
+
     def registry_path=(path)
       @registry_path = path
       @registry = nil
@@ -60,8 +81,48 @@ module WideEvent
       @registry ||= Registry.load(resolved_registry_path)
     end
 
+    # Stops the store sender's worker thread (if one was ever built) so
+    # tests and process shutdown never leak the background thread.
+    def shutdown_store_sender!(timeout: WideEvent::Store::Sender::SHUTDOWN_TIMEOUT)
+      @store_sender&.shutdown(timeout: timeout)
+      @store_sender = nil
+    end
+
     private
 
+    def build_store_sink
+      # A prior resolution (e.g. `config.sink = :store` twice, or
+      # re-assigning store_* fields and re-resolving) may have already
+      # built and started a sender; shut it down before replacing it so
+      # its worker thread and queue don't strand themselves, ownerless and
+      # retrying forever.
+      shutdown_store_sender!
+
+      raise ArgumentError, "WIDE_EVENTS_SERVICE is required for the store sink" if @store_service.to_s.strip.empty?
+      raise ArgumentError, "WIDE_EVENTS_ENVIRONMENT is required for the store sink" if @store_environment.to_s.strip.empty?
+      # Client itself no longer validates token presence at construction
+      # (a query-only Client has no ingest token to give it) — the ingest
+      # path validates this here, at sink-resolution time, instead.
+      raise ArgumentError, "WIDE_EVENTS_INGEST_TOKEN is required for the store sink" if @store_ingest_token.to_s.strip.empty?
+
+      client = WideEvent::Store::Client.new(url: @store_url, ingest_token: @store_ingest_token)
+      @store_sender = WideEvent::Store::Sender.new(client: client, service: @store_service, environment: @store_environment)
+      Sinks::Store.new(sender: @store_sender)
+    rescue StandardError => e
+      # This instance's own handler, not the module-level WideEvent.handle_error
+      # funnel: build_store_sink runs on whatever Configuration instance is
+      # resolving (in production that's always WideEvent.config, but tests
+      # also resolve standalone instances directly).
+      report_configuration_error(e)
+      NOOP_STORE_SINK
+    end
+
+    def report_configuration_error(exception)
+      error_handler&.call(exception, "store_sink_configuration")
+    rescue StandardError
+      nil
+    end
+
     # `registry_path` stays relative so the generated doc can commit it;
     # absolute paths win inside Pathname#join and pass through as-is.
     def resolved_registry_path