API reference

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/javascript directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder capture SDK (browser)

Paste this into a coding agent (Claude Code, Cursor, …) running inside your web
application's repository. It is written to be self-contained — the agent needs
no prior knowledge of InsightRecorder.

---

You are working in a web application. Install and wire the InsightRecorder browser
capture SDK so users can report bugs that arrive with real context (console
output, network timing, and the steps that led to the failure) instead of a
screenshot and a sentence.

**Context you need:**

- The SDK is a single vanilla-JS file served by the InsightRecorder deployment at
  `<INSIGHTRECORDER_URL>/static/js/capture.js`. There is **no npm package, no build
  step, and no framework requirement**.
- It is configured entirely through `data-` attributes on the script tag.
- `data-token` is a **capture token** found in the InsightRecorder UI under
  *Settings → Integrations*. It is public by design — like an error-tracker
  DSN — and grants nothing beyond submitting a capture. It is **not** an API
  key and must not be confused with one.

**Steps:**

1. Add the script tag to the application's root HTML document — the one shared
   by every page (`index.html`, the base layout/template, or the framework's
   document component, e.g. `app/layout.tsx`, `_document.tsx`,
   `application.html.erb`, `base.html`). Add it once, not per page:

   ```html
   <script src="https://<INSIGHTRECORDER_URL>/static/js/redact.js"></script>
   <script
     src="https://<INSIGHTRECORDER_URL>/static/js/capture.js"
     data-token="<CAPTURE_TOKEN>"
     data-auto="error"
   ></script>
   ```

   - **Both tags, in this order.** `redact.js` is what masks PII in the browser
     before anything is transmitted. Omitting it does not disable redaction —
     the agent falls back to its strict built-in policy — but it does mean the
     workspace's configured rules never reach the page.

   - `data-auto="error"` makes uncaught errors and unhandled promise
     rejections report themselves automatically. Omit the attribute if you want
     manual reporting only.
   - `data-endpoint` is optional; it defaults to the script's own origin.

2. Put `<INSIGHTRECORDER_URL>` and `<CAPTURE_TOKEN>` in this project's existing
   environment/config mechanism rather than hard-coding them, and interpolate
   them in the template the way this repo already does for other public
   values. If the framework distinguishes public from server-only variables
   (`NEXT_PUBLIC_`, `VITE_`, …), use the **public** prefix — this value is
   meant to reach the browser.

3. Add a "Report a bug" affordance wherever this application already puts
   secondary user actions (a footer link, a help menu, a support widget). Wire
   it to:

   ```js
   const ack = await window.insightRecorder.report("short description of the problem");
   // ack -> { id, ref }  e.g. ref "BUG-7F3A2C" — show it to the user
   ```

   Optionally pass a severity as the second argument: `"P0"`, `"P1"`, `"P2"`
   (default), or `"P3"`.

4. If this application has a Content-Security-Policy, add the InsightRecorder origin
   to both `script-src` (to load the file) and `connect-src` (the agent POSTs
   the report there). Do not add `unsafe-inline` — it is not needed.

**Rules — do not violate these:**

- Do **not** add the script tag more than once per page load.
- Do **not** attempt to capture or forward form values, passwords, tokens, or
  request bodies. The agent deliberately never reads input/textarea values and
  never captures network bodies or headers — preserve that. Everything
  submitted is additionally PII-redacted server-side.
- Do **not** treat the capture token as a secret to be hidden, and equally do
  **not** substitute an API key (`crk_…`) for it: they are different
  credentials with different powers.
- Do **not** vendor a copy of `capture.js` or `redact.js` into this repository. Load them from
  the InsightRecorder deployment so it stays current.

**Verify before you finish:**

1. The application builds and runs.
2. Open a page, run `window.insightRecorder.report("smoke test")` in the browser
   console, and confirm it resolves with an object containing `id` and `ref`.
3. Confirm the bug appears in InsightRecorder under `/app/bugs`, and that its
   console/network timeline is populated.
4. If you set `data-auto="error"`, trigger a deliberate uncaught error and
   confirm a second report arrives.
5. Report what you changed and where the script tag lives.

If anything is ambiguous — which file is the shared document, how public
config is exposed, whether a CSP exists — inspect the repository and follow
what is already there.

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/react directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder React adapter

Paste this into a coding agent (Claude Code, Cursor, …) running inside your
React application's repository. It is self-contained — the agent needs no prior
knowledge of InsightRecorder.

---

You are working in a React application. Wire it to InsightRecorder so a crash files a
bug report with the console, network and click timeline that led to it.

**Context you need:**

- InsightRecorder's browser agent (`capture.js`) records console output, network
  calls and user steps in memory and transmits nothing until a report is
  triggered. It is loaded with a `<script>` tag and a public capture token.
- The agent alone is not enough for React: **error boundaries swallow render
  errors**, so `componentDidCatch` runs and `window.onerror` never fires. The
  `@insightrecorder/capture-react` package bridges that and attaches the component
  stack.
- The capture token is public by design, like an error-tracker DSN. It is
  **not** an API key and carries no scopes. Find it in the InsightRecorder UI under
  *Settings → Integrations*.

**Steps:**

1. Add the agent script to the HTML document that boots the app —
   `index.html`, or the framework's document template (`app/root.tsx` for Remix,
   `app/layout.tsx` for Next.js):

   ```html
   <script src="https://<insightrecorder-host>/static/js/capture.js"
           data-token="<capture token>"></script>
   ```

   Read the host and token from the project's existing environment mechanism
   (`import.meta.env`, `process.env`, a config file) rather than hard-coding
   them. If either is missing, the tag must be omitted and the app must run
   normally — telemetry is never a boot dependency.

2. Install the adapter: `npm install @insightrecorder/capture-react` (or the yarn/pnpm
   equivalent this project uses).

3. Wrap the tree at the root, **inside** any provider the fallback needs (theme,
   i18n) but outside the routes:

   ```jsx
   import { CaptureErrorBoundary } from "@insightrecorder/capture-react";

   <CaptureErrorBoundary fallback={<SomethingBroke />}>
     <App />
   </CaptureErrorBoundary>
   ```

   If the project already has an error boundary, do **not** add a second one
   around the same subtree — call `reportReactError(error, info)` from the
   existing boundary's `componentDidCatch` instead.

4. Add boundaries around subtrees that should fail independently — a dashboard
   widget, an embedded editor — so one broken panel does not blank the page.
   Only do this where the project's layout makes it meaningful.

5. If the app uses hash routing or a memory router, call
   `captureNavigation(path)` on route change. With a normal history router,
   skip this: the agent already patches `history.pushState`.

**Rules — do not violate these:**

- Do **not** capture props, state, form values, headers, cookies or request
  bodies in any report you write. They routinely carry credentials and personal
  data, and the SDK deliberately never reads them.
- Do **not** put the capture token in a server-side secret store or an API-key
  variable — it belongs in the page, and treating it as a secret will just make
  the wiring wrong.
- Do **not** make the app's boot depend on the agent loading. Every adapter
  entry point is already a no-op when the agent is absent; keep it that way.
- Do **not** replace the project's existing error reporting (Sentry, etc.)
  unless you were asked to. Both can run.

**Verify before you finish:**

1. The project's build and test commands pass.
2. Run the app, throw a deliberate error inside a component's render, and
   confirm a bug appears in InsightRecorder at `/app/bugs` with the component stack.
3. Open that bug and confirm the console and network timeline are populated.
4. Confirm the app still boots with the script tag removed.
5. Report what you changed and where each boundary was placed.

If anything is ambiguous — which HTML template boots the app, whether a boundary
already exists — inspect the repository and follow what is already there. Do not
restructure the application to fit the SDK.

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/vue directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder Vue adapter

Paste this into a coding agent (Claude Code, Cursor, …) running inside your Vue
application's repository. It is self-contained — the agent needs no prior
knowledge of InsightRecorder.

---

You are working in a Vue application. Wire it to InsightRecorder so a crash files a
bug report with the console, network and click timeline that led to it.

**Context you need:**

- InsightRecorder's browser agent (`capture.js`) records console output, network
  calls and user steps in memory and transmits nothing until a report is
  triggered. It is loaded with a `<script>` tag and a public capture token.
- The agent alone is not enough for Vue: component errors go to
  **`app.config.errorHandler`** and never reach `window.onerror`. The
  `@insightrecorder/capture-vue` plugin bridges that and attaches the component name
  and the failing lifecycle hook.
- The capture token is public by design, like an error-tracker DSN. It is
  **not** an API key and carries no scopes. Find it in the InsightRecorder UI under
  *Settings → Integrations*.

**Steps:**

1. Add the agent script to the HTML document that boots the app — `index.html`
   for Vite, or Nuxt's `app.head` configuration:

   ```html
   <script src="https://<insightrecorder-host>/static/js/capture.js"
           data-token="<capture token>"></script>
   ```

   Read the host and token from the project's existing environment mechanism
   (`import.meta.env`, `runtimeConfig`) rather than hard-coding them. If either
   is missing, the tag must be omitted and the app must run normally —
   telemetry is never a boot dependency.

2. Install the plugin: `npm install @insightrecorder/capture-vue` (or the
   yarn/pnpm equivalent this project uses).

3. Install it on the app where the other plugins are registered (`main.ts`, or
   a Nuxt plugin file), passing the router if the project has one:

   ```js
   import { InsightRecorderCapture } from "@insightrecorder/capture-vue";

   app.use(InsightRecorderCapture, { router });
   ```

   The plugin chains onto an existing `app.config.errorHandler`, so if this
   project already sets one, leave it in place — do not merge them by hand.

4. Where a component should fail on its own rather than taking the page with it,
   add an `onErrorCaptured` hook that calls `reportVueError(error, instance,
   hook)` and returns `false`. Only do this where the project's layout makes it
   meaningful.

**Rules — do not violate these:**

- Do **not** capture props, state, refs, form values, headers, cookies or
  request bodies in any report you write. They routinely carry credentials and
  personal data, and the SDK deliberately never reads them.
- Do **not** put the capture token in a server-side secret store or an API-key
  variable — it belongs in the page, and treating it as a secret will just make
  the wiring wrong.
- Do **not** make the app's boot depend on the agent loading. Every plugin
  entry point is already a no-op when the agent is absent; keep it that way.
- Do **not** replace the project's existing error reporting (Sentry, etc.)
  unless you were asked to. Both can run.

**Verify before you finish:**

1. The project's build and test commands pass.
2. Run the app, throw a deliberate error inside a component's `setup` or
   render, and confirm a bug appears in InsightRecorder at `/app/bugs` naming that
   component.
3. Open that bug and confirm the console and network timeline are populated.
4. Confirm the app still boots with the script tag removed.
5. Report what you changed and where the plugin was installed.

If anything is ambiguous — which entry file registers plugins, whether an error
handler already exists — inspect the repository and follow what is already
there. Do not restructure the application to fit the SDK.

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/golang directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder Go SDK

Paste this into a coding agent (Claude Code, Cursor, …) running inside your Go
service's repository. It is written to be self-contained — the agent needs no
prior knowledge of InsightRecorder.

---

You are working in a Go service. Install and wire the InsightRecorder SDK
(`github.com/InsightRecorder/insight-recorder-go`) so this service ships its logs to
InsightRecorder and reports panics as bug reports.

**Context you need:**

- InsightRecorder collects application logs and bug reports. This SDK is the
  supported way for a Go service to talk to it.
- The SDK requires **Go 1.22+** and has **zero third-party dependencies** in
  its core module.
- Authentication uses a long-lived **API key** that looks like `crk_…`, created
  in the InsightRecorder UI under *Settings → API keys* with the `logs:write` scope
  (add `bug:write` to report bugs). **Do not** use a login JWT: those expire
  after an hour and are not meant for machines.

  Add the matching **read** scopes for anything the SDK reads back — `bug:read` for `ListBugs/GetBug`, `logs:read` for `ListLogs`. A write-only key is the common mistake: shipping works, the first read returns 403.
- **If the application is instrumented with OpenTelemetry, wire the trace
  correlation** — it is one call, and without it the log line and the trace of
  the request that wrote it never join, which is the whole point of shipping
  logs here:

  ```go
  import (
      insight "github.com/InsightRecorder/insight-recorder-go"
      insightotel "github.com/InsightRecorder/insight-recorder-go/otel"
  )

  h := insight.NewSlogHandler(sh, slog.LevelInfo).
      WithTraceExtractor(insightotel.TraceIDs)
  slog.SetDefault(slog.New(insight.MultiHandler(stdoutHandler, h)))
  ```

  From then on `slog.InfoContext(ctx, …)` correlates by itself. Plain
  `slog.Info` (no context) cannot — there is no span to read, so prefer the
  `…Context` variants in request paths. With zerolog use
  `insightzerolog.Ctx(ctx, log.Logger, insightotel.TraceIDs)`; a zerolog writer
  sees bytes, never a context, so the correlation has to come from the logger.

- The base URL is the InsightRecorder deployment's origin, e.g.
  `https://insightrecorder.example.com`.

- **Wire trace correlation if the application uses OpenTelemetry.** A log line
  and the request that wrote it are one investigation, and that join is the
  reason to ship logs here rather than anywhere else — see the "Trace
  correlation" section of the README for what this language needs (several do it
  automatically; the rest take one hook). Without it, every log call has to carry
  `trace_id` by hand, which nobody sustains past the first week.

**Steps:**

1. Add the dependency:

   ```sh
   go get github.com/InsightRecorder/insight-recorder-go
   ```

   If — and only if — this service already logs with `github.com/rs/zerolog`,
   also run `go get github.com/InsightRecorder/insight-recorder-go/zerolog`. Otherwise
   skip it: the adapter is a separate module precisely so services that use
   `log/slog` never pull zerolog into their build.

2. Read configuration from the environment, never hard-code it. Add to the
   service's existing config loading (and to `.env.example` / deployment
   manifests, whichever this repo uses):

   - `INSIGHT_BASE_URL` — the InsightRecorder origin
   - `INSIGHT_API_KEY` — the `crk_…` key

   If either is empty, the service must start normally with shipping disabled.
   Telemetry is never allowed to be a startup dependency.

3. In the service's composition root (wherever the logger and HTTP server are
   built — do not create a new "init" package if one already exists), wire:

   ```go
   client, err := insight.New(os.Getenv("INSIGHT_BASE_URL"), os.Getenv("INSIGHT_API_KEY"))
   if err != nil {
       return err
   }

   shipper := client.NewShipper()
   defer shipper.Close() // MUST run on shutdown or the last batch is lost

   // Keep the existing local logging AND ship to InsightRecorder.
   slog.SetDefault(slog.New(insight.MultiHandler(
       slog.NewJSONHandler(os.Stdout, nil),
       insight.NewSlogHandler(shipper, slog.LevelInfo),
   )))

   // Panics become bug reports carrying the stack, the request's method and
   // path, and the log lines that led up to them.
   handler := client.Recover(
       insight.WithShipper(shipper),
       insight.WithService("<this service's name>"),
   )(existingHandler)
   ```

   Match the existing style: if the service uses zerolog, use
   `insightzerolog.NewWriter(shipper)` inside its `zerolog.MultiLevelWriter`
   instead of the slog block. If it uses a router (chi, gin, echo), apply
   `client.Recover(...)` as middleware in that router's idiom rather than
   wrapping the handler manually.

4. Ensure `shipper.Close()` actually runs on the service's existing graceful
   shutdown path (next to `srv.Shutdown`), not only via `defer` in a function
   that may not return.

**Rules — do not violate these:**

- Do **not** write a custom `io.Writer` that POSTs one HTTP request per log
  line. The SDK already batches, retries with backoff, respects the server's
  quota (429 + `Retry-After`), and flushes on close.
- Do **not** make logging block on the network: `shipper.Send` is
  non-blocking by design and drops when its queue is full. Do not wrap it in
  anything that waits.
- Do **not** log the API key, and do not commit it.
- Do **not** capture request bodies, headers, cookies, or query strings in bug
  reports. The SDK deliberately records only the method and path because those
  carry credentials and personal data.

**Verify before you finish:**

1. `go build ./...` and the repo's existing test command both pass.
2. Start the service with `INSIGHT_BASE_URL`/`INSIGHT_API_KEY` set, exercise an
   endpoint, then confirm the log lines appear in InsightRecorder under `/app/logs`
   (filter by the service name or a `trace_id` you logged).
3. Confirm the service still starts normally with both variables **unset**.
4. Report what you changed, and state explicitly whether `shipper.Close()` is
   wired into the shutdown path.

If anything is ambiguous — which logger the service uses, where the composition
root is, how shutdown is handled — inspect the repository and follow what is
already there. Do not restructure the service to fit the SDK.

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/typescript directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder TypeScript/JavaScript SDK

Paste this into a coding agent (Claude Code, Cursor, …) running inside your
Node.js service's repository. It is self-contained — the agent needs no prior
knowledge of InsightRecorder.

---

You are working in a Node.js service (TypeScript or JavaScript). Install and
wire the InsightRecorder SDK so this service ships its logs to InsightRecorder and reports
unhandled errors.

**Context you need:**

- InsightRecorder collects application logs and bug reports. `@insightrecorder/insight-recorder`
  is the supported way for a Node **server** to talk to it. (A browser app uses
  a different thing — a `<script>` capture agent — so do not install this
  package in front-end-only code.)
- Requires **Node 18+**. The package has zero runtime dependencies.
- Authentication uses a long-lived **API key** shaped like `crk_…`, created in
  the InsightRecorder UI under *Settings → API keys* with the `logs:write` scope (add
  `bug:write` to report errors). **Do not** use a login JWT: those expire after
  an hour and are not meant for machines.

  Add `bug:read` for anything the SDK reads back (`listBugs/getBug`), and `logs:read` if you query logs. A write-only key is the common mistake: shipping works, the first read returns 403.

- **Wire trace correlation if the application uses OpenTelemetry.** A log line
  and the request that wrote it are one investigation, and that join is the
  reason to ship logs here rather than anywhere else — see the "Trace
  correlation" section of the README for what this language needs (several do it
  automatically; the rest take one hook). Without it, every log call has to carry
  `trace_id` by hand, which nobody sustains past the first week.

**Steps:**

1. `npm install @insightrecorder/insight-recorder` (or the project's package manager —
   match what the repo already uses: yarn, pnpm, bun).

2. Read configuration from the environment, never hard-code it. Add
   `INSIGHT_BASE_URL` and `INSIGHT_API_KEY` to the project's existing config
   loading and to `.env.example` / deployment manifests. If either is empty, the
   service must start normally with shipping disabled — telemetry is never a
   startup dependency.

3. In the service's composition root (where the logger and HTTP server are
   built — do not invent a new bootstrap module if one exists):

   ```ts
   import { Client, errorHandler } from "@insightrecorder/insight-recorder";

   const client = new Client(process.env.INSIGHT_BASE_URL!, process.env.INSIGHT_API_KEY!);
   const shipper = client.shipper();
   ```

4. Bridge the service's existing logger to `shipper.send(...)`. Match what the
   repo already uses:
   - **pino**: add a custom transport/stream, or call `shipper.send` from a
     `hooks.logMethod` wrapper.
   - **winston**: add a small custom `Transport` whose `log()` calls
     `shipper.send`.
   - **console only**: wrap the call sites, or leave logging alone and only wire
     error reporting (step 5).

   Map fields as: `level` → level, the message → `message`, a trace id →
   `traceId`, and everything else into `attrs` (string values).

5. If the service uses Express, register the error handler **last**, after all
   routes:

   ```ts
   app.use(errorHandler(client, { shipper, service: "<service name>" }));
   ```

   For Fastify/Koa/NestJS, call `client.reportBug(...)` from that framework's
   own error hook instead — the payload shape is in the package's README.

6. Flush on shutdown. Add `await shipper.close()` to the service's existing
   SIGTERM/SIGINT handling, next to the server close. Without it the final batch
   is lost.

**Rules — do not violate these:**

- Do **not** write a custom fetch loop that POSTs one request per log line. The
  SDK batches, retries with backoff, respects the server's quota (429 +
  `Retry-After`), and caps each request at `batchSize`.
- Do **not** `await shipper.send(...)` or wrap it in anything that waits — it is
  deliberately synchronous and non-blocking, and drops when its queue is full.
- Do **not** log the API key, and do not commit it.
- Do **not** capture request bodies, headers, cookies, or query strings in error
  reports. The SDK records only the method and path, because those routinely
  carry credentials and personal data.

**Verify before you finish:**

1. The project's build/typecheck and test commands pass.
2. Start the service with both env vars set, hit an endpoint, then confirm the
   log lines appear in InsightRecorder at `/app/logs`.
3. Trigger a deliberate error and confirm a bug appears at `/app/bugs`.
4. Confirm the service still starts with both variables **unset**.
5. Report what you changed, and state explicitly whether `shipper.close()` runs
   on shutdown.

If anything is ambiguous — which logger, where the composition root is, how
shutdown is handled — inspect the repository and follow what is already there.
Do not restructure the service to fit the SDK.

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/elixir directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder Elixir SDK

Paste this into a coding agent (Claude Code, Cursor, …) running inside your
Elixir or Phoenix application's repository. It is self-contained — the agent
needs no prior knowledge of InsightRecorder.

---

You are working in an Elixir application. Install and wire the InsightRecorder SDK so
it ships its logs to InsightRecorder and reports unhandled exceptions.

**Context you need:**

- InsightRecorder collects application logs and bug reports. `:insight_recorder` is
  the supported way for an Elixir service to talk to it.
- Requires **Elixir 1.15+**. It has one runtime dependency (`:jason`); HTTP uses
  OTP's `:httpc`, so it adds no HTTP client to the application tree.
- Authentication uses a long-lived **API key** shaped like `crk_…`, created in
  the InsightRecorder UI under *Settings → API keys* with the `logs:write` scope (add
  `bug:write` to report errors). **Do not** use a login JWT: those expire after
  an hour and are not meant for machines.

  Add the matching **read** scopes for anything the SDK reads back — `bug:read` for `list_bugs/get_bug`, `logs:read` for `list_logs`. A write-only key is the common mistake: shipping works, the first read returns 403.

- **Wire trace correlation if the application uses OpenTelemetry.** A log line
  and the request that wrote it are one investigation, and that join is the
  reason to ship logs here rather than anywhere else — see the "Trace
  correlation" section of the README for what this language needs (several do it
  automatically; the rest take one hook). Without it, every log call has to carry
  `trace_id` by hand, which nobody sustains past the first week.

**Steps:**

1. Add `{:insight_recorder, "~> 0.1"}` to `deps/0` in `mix.exs` and run
   `mix deps.get`.

2. Read configuration from the environment at **runtime**, not compile time —
   put it in `config/runtime.exs`, which is where releases read config:

   ```elixir
   config :my_app, :insight,
     base_url: System.get_env("INSIGHT_BASE_URL"),
     api_key: System.get_env("INSIGHT_API_KEY")
   ```

   If either is missing, the application must boot normally with shipping
   disabled — telemetry is never a startup dependency.

3. Build the client and start the shipper **in the application's supervision
   tree** (`lib/my_app/application.ex`), so shutdown flushes the last batch:

   ```elixir
   children = [
     # … existing children …
     {InsightRecorder.Shipper, client: insight_client(), name: MyApp.Shipper}
   ]
   ```

   Starting it outside a supervisor would skip the flush on shutdown.

4. Ship logs. Prefer an explicit call at the points that matter:

   ```elixir
   InsightRecorder.Shipper.send(MyApp.Shipper, %{
     level: "error",
     message: "checkout failed",
     trace_id: trace_id,
     attrs: %{"order_id" => order_id}
   })
   ```

   **To ship every `Logger` call rather than scattering `log/2` by hand**, add a
   `:logger` handler — OTP has supported custom handlers natively since OTP 21,
   so no extra dependency is needed. A handler is a module with `log/2`:

   ```elixir
   defmodule MyApp.InsightLogHandler do
     @moduledoc "Ships every Logger event to InsightRecorder, best-effort."

     def log(%{level: level, msg: msg, meta: meta}, _config) do
       InsightRecorder.log(MyApp.insight_client(), %{
         level: Atom.to_string(level),
         message: message(msg),
         trace_id: meta[:trace_id],
         attrs: %{}
       })

       :ok
     end

     defp message({:string, text}), do: IO.iodata_to_binary(text)
     defp message({:report, report}), do: inspect(report)
     defp message({format, args}), do: format |> :io_lib.format(args) |> IO.iodata_to_binary()
   end
   ```

   Register it **alongside** the default handler, never instead of it — shipping
   is best-effort, so the local log stays the source of truth for the running
   process:

   ```elixir
   :logger.add_handler(:insight, MyApp.InsightLogHandler, %{level: :info})
   ```

   The one trap: **never log from inside the handler.** A delivery failure that
   logs fires the handler, which logs. `InsightRecorder.log/2` queues and returns
   without blocking, and errors surface through the shipper's own callback.

   If the application already has a telemetry handler pipeline, wire it there
   instead and follow the existing pattern.

5. If this is a Phoenix application, report unhandled exceptions through
   `Plug.ErrorHandler` — the mechanism that actually sees exceptions raised
   downstream (a plug cannot: its `call/2` returns before they happen). In the
   endpoint module:

   ```elixir
   use InsightRecorder.ErrorHandler,
     client: {MyApp, :insight_client, []},
     shipper: MyApp.Shipper,
     service: "<app name>"
   ```

   The client is an MFA tuple because the endpoint compiles before runtime
   config is loaded. If the application already defines `handle_errors/2`, call
   `InsightRecorder.ErrorReporter.report(conn, error, opts)` from inside it
   instead of adding a second handler.

**Rules — do not violate these:**

- Do **not** build a custom `:httpc`/Finch caller that posts one request per log
  line. The SDK batches, chunks each request at `:batch_size`, retries with
  backoff, and respects the server's quota.
- Do **not** wrap `Shipper.send/2` in a `GenServer.call` or otherwise make it
  synchronous — it is a cast on purpose and drops when its queue is full.
- Do **not** log the API key, and do not commit it.
- Do **not** capture request bodies, headers, cookies, or query strings in
  reports. The plug records only the method and path.

**Verify before you finish:**

1. `mix compile --warnings-as-errors` and the project's test command pass.
2. Boot the app with both env vars set, exercise a request, then confirm the log
   lines appear in InsightRecorder at `/app/logs`.
3. Raise a deliberate exception in a controller and confirm a bug appears at
   `/app/bugs`.
4. Confirm the app still boots with both variables **unset**.
5. Report what you changed, and state explicitly whether the shipper is under
   the supervision tree.

If anything is ambiguous — where the application module is, how config is
loaded, whether Phoenix is present — inspect the repository and follow what is
already there. Do not restructure the application to fit the SDK.

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/java directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder Java SDK

Paste this into a coding agent (Claude Code, Cursor, …) running inside your
Java service's repository. It is self-contained — the agent needs no prior
knowledge of InsightRecorder.

---

You are working in a Java service. Install and wire the InsightRecorder SDK so it
ships its logs to InsightRecorder and reports unhandled exceptions.

**Context you need:**

- InsightRecorder collects application logs and bug reports. The InsightRecorder Java SDK
  (`com.insightrecorder.insight`) is the supported way for a Java service to talk to it.
- Requires **Java 17+**. It has **zero third-party dependencies** — HTTP is
  `java.net.http`, JSON is internal — so it cannot conflict with the Jackson or
  HTTP-client versions this project already pins.
- Authentication uses a long-lived **API key** shaped like `crk_…`, created in
  the InsightRecorder UI under *Settings → API keys* with the `logs:write` scope (add
  `bug:write` to report errors). **Do not** use a login JWT: those expire after
  an hour and are not meant for machines.

  Add `bug:read` for anything the SDK reads back (`listBugs/getBug`), and `logs:read` if you query logs. A write-only key is the common mistake: shipping works, the first read returns 403.

- **Wire trace correlation if the application uses OpenTelemetry.** A log line
  and the request that wrote it are one investigation, and that join is the
  reason to ship logs here rather than anywhere else — see the "Trace
  correlation" section of the README for what this language needs (several do it
  automatically; the rest take one hook). Without it, every log call has to carry
  `trace_id` by hand, which nobody sustains past the first week.

**Steps:**

1. Add the dependency using whatever build tool this repo uses (Maven `pom.xml`
   or Gradle `build.gradle[.kts]`) — match the existing style and dependency
   ordering. If the artifact is not yet published to a repository the project
   can reach, add the SDK sources under `src/main/java/com/insightrecorder/insight/`
   instead and say so in your summary.

2. Read configuration from the environment, never hard-code it: `INSIGHT_BASE_URL`
   and `INSIGHT_API_KEY`. Wire them through the project's existing configuration
   mechanism (Spring `@ConfigurationProperties`, MicroProfile Config, plain
   `System.getenv`, …). If either is empty, the service must start normally with
   shipping disabled — telemetry is never a startup dependency.

3. Create the client **once** (a singleton: a Spring `@Bean`, a CDI producer, or
   a static holder — follow the project's pattern) and a shipper alongside it:

   ```java
   InsightClient client = InsightClient.builder()
       .baseUrl(baseUrl)
       .apiKey(apiKey)
       .build();

   Shipper shipper = client.shipper();
   ```

4. Bridge the service's existing logging to the shipper. Match what the repo
   uses:
   - **Logback**: add a small `AppenderBase<ILoggingEvent>` whose `append()`
     builds a `LogEntry` and calls `shipper.send(...)`; register it in
     `logback.xml` **alongside** the console appender, never replacing it.
   - **Log4j2**: the equivalent custom `Appender`.
   - **java.util.logging**: a custom `Handler`.

   Map fields as: level name → `.level(...)`, the formatted message → the entry
   message, an MDC/trace id → `.traceId(...)`, and remaining MDC entries →
   `.attr(key, value)`.

5. Report unhandled exceptions with `ErrorReporter`, which builds the whole
   report — stack trace, request, trace id, and the recent log trail:

   ```java
   ErrorReporter reporter = ErrorReporter.builder(client)
       .shipper(shipper)
       .service("<service name>")
       .build();
   ```

   Wire it where this project already handles exceptions — a servlet filter
   registered high in the chain, a Spring `@ControllerAdvice`, or a JAX-RS
   `ExceptionMapper`:

   ```java
   reporter.report(e, ErrorReporter.Request.of(
       req.getMethod(), req.getRequestURI(), req.getHeader("traceparent")));
   throw e; // rethrow, so existing error handling still runs
   ```

   The SDK ships no servlet or Spring dependency on purpose — those six lines
   are the adapter, and the README has the full filter. For background jobs use
   `executor.submit(reporter.wrap(task))`, and add
   `reporter.installUncaughtExceptionHandler()` as a JVM-wide catch-all.

6. Close the shipper on shutdown — a Spring `@PreDestroy`, a
   `Runtime.getRuntime().addShutdownHook(...)`, or try-with-resources for a
   short-lived process. Without it the final batch is lost.

**Rules — do not violate these:**

- Do **not** write an appender that opens an HTTP connection per log event. The
  SDK batches on a daemon thread, caps each request at `batchSize`, retries with
  backoff, and respects the server's quota.
- Do **not** block on `shipper.send(...)` — it is non-blocking on purpose and
  drops when its queue is full.
- Do **not** swallow `InterruptedException` anywhere you touch the SDK; restore
  the interrupt flag.
- Do **not** log the API key, and do not commit it.
- Do **not** capture request bodies, headers, cookies, or query strings in
  reports: they routinely carry credentials and personal data.

**Verify before you finish:**

1. The project's build and test commands pass.
2. Start the service with both env vars set, exercise an endpoint, then confirm
   the log lines appear in InsightRecorder at `/app/logs`.
3. Trigger a deliberate exception and confirm a bug appears at `/app/bugs`.
4. Confirm the service still starts with both variables **unset**.
5. Report what you changed, and state explicitly where `shipper.close()` runs.

If anything is ambiguous — which logging framework, where beans are declared,
how shutdown is handled — inspect the repository and follow what is already
there. Do not restructure the service to fit the SDK.

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/csharp directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder .NET SDK

Paste this into a coding agent (Claude Code, Cursor, …) running inside your
.NET service's repository. It is self-contained — the agent needs no prior
knowledge of InsightRecorder.

---

You are working in a .NET service. Install and wire the InsightRecorder SDK
(`InsightRecorder.Insight`) so it ships its logs to InsightRecorder and reports unhandled
exceptions.

**Context you need:**

- InsightRecorder collects application logs and bug reports. This SDK is the supported
  way for a .NET service to talk to it.
- Requires **.NET 8+**. It has **zero third-party dependencies** — `HttpClient`
  and `System.Text.Json` ship with the framework — so it cannot conflict with
  versions this project already pins.
- Authentication uses a long-lived **API key** shaped like `crk_…`, created in
  the InsightRecorder UI under *Settings → API keys* with the `logs:write` scope (add
  `bug:write` to report errors). **Do not** use a login JWT: those expire after
  an hour and are not meant for machines.

  Add `bug:read` for anything the SDK reads back (`ListBugs/GetBug`), and `logs:read` if you query logs. A write-only key is the common mistake: shipping works, the first read returns 403.

- **Wire trace correlation if the application uses OpenTelemetry.** A log line
  and the request that wrote it are one investigation, and that join is the
  reason to ship logs here rather than anywhere else — see the "Trace
  correlation" section of the README for what this language needs (several do it
  automatically; the rest take one hook). Without it, every log call has to carry
  `trace_id` by hand, which nobody sustains past the first week.

**Steps:**

1. `dotnet add package InsightRecorder.Insight` in the service project (not the test
   project).

2. Read configuration through the project's existing `IConfiguration` — bind
   `Insight:BaseUrl` and `Insight:ApiKey`, sourced from environment variables
   (`Insight__BaseUrl`, `Insight__ApiKey`) or the configured secret store. Never
   hard-code them, and never put the key in `appsettings.json`. If either is
   empty, the service must start normally with shipping disabled — telemetry is
   never a startup dependency.

3. Register the client as a **singleton** in `Program.cs` / `Startup.cs`,
   following the project's DI style:

   ```csharp
   builder.Services.AddSingleton(_ => new InsightClient(new InsightOptions
   {
       BaseUrl = builder.Configuration["Insight:BaseUrl"]!,
       ApiKey  = builder.Configuration["Insight:ApiKey"]!,
   }));
   builder.Services.AddSingleton(sp => sp.GetRequiredService<InsightClient>().CreateShipper());
   ```

4. Bridge logging. If the project uses `Microsoft.Extensions.Logging` (it almost
   certainly does), add a small `ILoggerProvider`/`ILogger` implementation whose
   `Log` method builds a `LogEntry` and calls `shipper.Send(...)`, and register
   it **alongside** the existing providers, never replacing them. Map: log level
   → `Level`, the formatted message → the entry message,
   `Activity.Current?.TraceId` → `TraceId`, and scope/state values → `.With(key, value)`.

   If the project uses Serilog, write the equivalent `ILogEventSink`.

5. Report unhandled exceptions where this project already handles them — an
   exception-handling middleware, an `IExceptionHandler` (ASP.NET Core 8), or an
   MVC filter:

   ```csharp
   await client.ReportBugAsync(new Dictionary<string, object?>
   {
       ["title"] = $"{e.GetType().Name}: {e.Message}",
       ["severity"] = "P0",
   });
   ```

   Report and then let the exception continue, so existing handling still runs.

6. Flush on shutdown. Register an `IHostedService` whose `StopAsync` calls
   `await shipper.DisposeAsync()`, or resolve and dispose it from
   `IHostApplicationLifetime.ApplicationStopping`. Without it the final batch is
   lost.

**Rules — do not violate these:**

- Do **not** write a logger provider that awaits an HTTP call per log event. The
  SDK batches in the background, caps each request at `BatchSize`, retries with
  backoff, and respects the server's quota.
- Do **not** `await` or block on `shipper.Send(...)` — it is synchronous and
  non-blocking on purpose, and drops when its queue is full.
- Do **not** create a new `HttpClient` per request; if the project uses
  `IHttpClientFactory`, pass the client through `InsightOptions.HttpClient` (the
  SDK will not dispose one it did not create).
- Do **not** log the API key, and do not commit it.
- Do **not** capture request bodies, headers, cookies, or query strings in
  reports: they routinely carry credentials and personal data.

**Verify before you finish:**

1. `dotnet build` and `dotnet test` pass.
2. Run the service with the configuration set, exercise an endpoint, then
   confirm the log lines appear in InsightRecorder at `/app/logs`.
3. Trigger a deliberate exception and confirm a bug appears at `/app/bugs`.
4. Confirm the service still starts with the configuration **absent**.
5. Report what you changed, and state explicitly where the shipper is disposed.

If anything is ambiguous — which logging stack, how DI is wired, how shutdown is
handled — inspect the repository and follow what is already there. Do not
restructure the service to fit the SDK.

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/php directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder PHP SDK

Paste this into a coding agent (Claude Code, Cursor, …) running inside your PHP
application's repository. It is self-contained — the agent needs no prior
knowledge of InsightRecorder.

---

You are working in a PHP application (most likely Laravel or Symfony). Install
and wire the InsightRecorder SDK so it ships its logs to InsightRecorder and reports
unhandled exceptions.

**Context you need:**

- InsightRecorder collects application logs and bug reports. The
  `insightrecorder/insight-recorder` package is the supported way for a PHP
  application to talk to it.
- Requires **PHP 8.1+** and has **zero runtime dependencies** — HTTP is
  `ext-curl`, JSON is `ext-json` — so it cannot conflict with the Guzzle
  version this project pins.
- Authentication uses a long-lived **API key** shaped like `crk_…`, created in
  the InsightRecorder UI under *Settings → API keys* with the `logs:write` scope (add
  `bug:write` to report errors). **Do not** use a login JWT: those expire after
  an hour and are not meant for machines.

  Add `bug:read` for anything the SDK reads back (`listBugs/getBug`), and `logs:read` if you query logs. A write-only key is the common mistake: shipping works, the first read returns 403.
- **PHP has no background threads.** The SDK buffers in memory and flushes at
  the end of the request, after `fastcgi_finish_request()` on PHP-FPM, so the
  user never waits. Do not try to make it asynchronous some other way.

- **Wire trace correlation if the application uses OpenTelemetry.** A log line
  and the request that wrote it are one investigation, and that join is the
  reason to ship logs here rather than anywhere else — see the "Trace
  correlation" section of the README for what this language needs (several do it
  automatically; the rest take one hook). Without it, every log call has to carry
  `trace_id` by hand, which nobody sustains past the first week.

**Steps:**

1. `composer require insightrecorder/insight-recorder`.

2. Read configuration from the environment, never hard-code it:
   `INSIGHT_BASE_URL` and `INSIGHT_API_KEY`. Wire them through whatever this
   project already uses — a Laravel `config/` file reading `env()`, Symfony
   parameters, or plain `getenv()`. If either is empty, the application must
   boot normally with shipping disabled: telemetry is never a boot dependency.

3. Register the client and shipper as **singletons** in the container, where
   this project registers its services (a Laravel `ServiceProvider`, Symfony
   `services.yaml`):

   ```php
   $client = new Client(config('insight.base_url'), config('insight.api_key'));
   $shipper = $client->shipper();
   ```

   One shipper per request; do not construct one per log line.

4. Bridge logging through Monolog — which is how both Laravel and Symfony log —
   adding the handler **alongside** the existing ones, never replacing them:

   ```php
   $logger->pushHandler(new InsightHandler($shipper));
   ```

   In Laravel, add it as a channel in `config/logging.php` and include that
   channel in the `stack`. In Symfony, register it as a Monolog handler in
   `config/packages/monolog.yaml`.

5. Report unhandled exceptions with `ErrorReporter`:

   ```php
   $reporter = new ErrorReporter($client, shipper: $shipper, service: '<service name>');
   ```

   Wire it where this project already handles exceptions — Laravel's
   `withExceptions(...)` in `bootstrap/app.php` (or `Handler::report()` on
   Laravel 10 and earlier), or a Symfony `kernel.exception` listener. Report and
   let the exception continue, so the framework's error page still renders.

6. Flushing is automatic at the end of the request. If this project runs
   **Octane, RoadRunner, Swoole, or queue workers**, call `$shipper->flush()`
   at the end of each request or job as well — those processes outlive a single
   request, so the shutdown hook fires far too late.

**Rules — do not violate these:**

- Do **not** write a Monolog handler that makes an HTTP call per log record.
  The SDK batches, caps each request at `batchSize`, retries with backoff, and
  respects the server's quota (429 + `Retry-After`).
- Do **not** call `flush()` inside the request path for every line — that
  defeats the buffering and puts a network round trip on the user's latency.
- Do **not** log the API key, and do not commit it.
- Do **not** capture request bodies, headers, cookies, or query strings in
  reports: they routinely carry credentials and personal data.

**Verify before you finish:**

1. The project's test command passes (`vendor/bin/phpunit`, `php artisan test`).
2. With both env vars set, exercise a route and confirm the log lines appear in
   InsightRecorder at `/app/logs`.
3. Throw a deliberate exception and confirm a bug appears at `/app/bugs`.
4. Confirm the app still boots with both variables **unset**.
5. Report what you changed, and state explicitly where the shipper is flushed.

If anything is ambiguous — which framework version, how logging is configured,
whether the app runs under Octane — inspect the repository and follow what is
already there. Do not restructure the application to fit the SDK.

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/python directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder Python SDK

Paste this into a coding agent (Claude Code, Cursor, …) running inside your
Python service's repository. It is self-contained — the agent needs no prior
knowledge of InsightRecorder.

---

You are working in a Python service. Install and wire the InsightRecorder SDK so it
ships its logs to InsightRecorder and reports unhandled exceptions.

**Context you need:**

- InsightRecorder collects application logs and bug reports. `insight-recorder` is the
  supported way for a Python service to talk to it.
- Requires **Python 3.9+** and has **zero runtime dependencies** — HTTP is
  `urllib.request` — so it cannot conflict with the `requests`/`httpx` versions
  this project pins.
- Authentication uses a long-lived **API key** shaped like `crk_…`, created in
  the InsightRecorder UI under *Settings → API keys* with the `logs:write` scope (add
  `bug:write` to report errors). **Do not** use a login JWT: those expire after
  an hour and are not meant for machines.

  Add the matching **read** scopes for anything the SDK reads back — `bug:read` for `list_bugs/get_bug`, `logs:read` for `list_logs`. A write-only key is the common mistake: shipping works, the first read returns 403.

- **Wire trace correlation if the application uses OpenTelemetry.** A log line
  and the request that wrote it are one investigation, and that join is the
  reason to ship logs here rather than anywhere else — see the "Trace
  correlation" section of the README for what this language needs (several do it
  automatically; the rest take one hook). Without it, every log call has to carry
  `trace_id` by hand, which nobody sustains past the first week.

**Steps:**

1. Add `insight-recorder` using whatever this project already uses —
   `pyproject.toml` dependencies, `requirements.txt`, Poetry, uv, or pipenv.
   Match the existing file and pinning style.

2. Read configuration from the environment, never hard-code it:
   `INSIGHT_BASE_URL` and `INSIGHT_API_KEY`. Wire them through the project's
   existing settings mechanism (Django `settings.py`, Pydantic `BaseSettings`,
   plain `os.environ`). If either is empty, the service must start normally with
   shipping disabled — telemetry is never a startup dependency.

3. Create the client and shipper **once**, where the application is composed
   (`app.py`, `wsgi.py`, a Django `AppConfig.ready()`, a FastAPI lifespan):

   ```python
   from insight_recorder import Client, InsightHandler

   client = Client(os.environ["INSIGHT_BASE_URL"], os.environ["INSIGHT_API_KEY"])
   shipper = client.shipper()
   ```

4. Bridge logging by adding the handler **alongside** the existing ones, never
   replacing them:

   ```python
   logging.getLogger().addHandler(InsightHandler(shipper))
   ```

   If the project configures logging through `dictConfig` (Django does), add it
   there as a handler entry instead of calling `addHandler` imperatively.
   Anything passed via `extra=` becomes a searchable attribute; `trace_id` and
   `span_id` are lifted into the record's correlation fields.

5. Report unhandled exceptions. For a WSGI app (Django, Flask, Pyramid):

   ```python
   app.wsgi_app = InsightMiddleware(app.wsgi_app, client, shipper=shipper,
                                    service="<service name>")
   ```

   For an ASGI framework (FastAPI, Starlette), call
   `client.report_bug({...})` from that framework's exception handler instead —
   the payload shape is in the package README.

6. Flush on shutdown: call `shipper.close()` from the project's existing
   shutdown path (a FastAPI lifespan's teardown, a signal handler, or `atexit`).
   Without it the final batch is lost.

**Rules — do not violate these:**

- Do **not** write a logging handler that makes an HTTP call per record. The SDK
  batches on a daemon thread, caps each request at `batch_size`, retries with
  backoff, and respects the server's quota (429 + `Retry-After`).
- Do **not** block on `shipper.send(...)` — it is non-blocking on purpose and
  drops when its queue is full.
- Do **not** log the API key, and do not commit it.
- Do **not** capture request bodies, headers, cookies, or query strings in
  reports: they routinely carry credentials and personal data.

**Verify before you finish:**

1. The project's test command passes and the service starts.
2. With both env vars set, exercise an endpoint and confirm the log lines appear
   in InsightRecorder at `/app/logs`.
3. Raise a deliberate exception and confirm a bug appears at `/app/bugs`.
4. Confirm the service still starts with both variables **unset**.
5. Report what you changed, and state explicitly where `shipper.close()` runs.

If anything is ambiguous — which web framework, how logging is configured, how
shutdown is handled — inspect the repository and follow what is already there.
Do not restructure the service to fit the SDK.

Paste this into a coding agent running inside your project, or point the agent at /docs/prompts/ruby directly. It is self-contained: the agent needs no prior knowledge of InsightRecorder.

# Install and wire the InsightRecorder Ruby SDK

Paste this into a coding agent (Claude Code, Cursor, …) running inside your Ruby
or Rails application's repository. It is self-contained — the agent needs no
prior knowledge of InsightRecorder.

---

You are working in a Ruby application (most likely Rails). Install and wire the
InsightRecorder SDK so it ships its logs to InsightRecorder and reports unhandled
exceptions.

**Context you need:**

- InsightRecorder collects application logs and bug reports. The `insight_recorder`
  gem is the supported way for a Ruby application to talk to it.
- Requires **Ruby 3.0+** and has **zero runtime dependencies** — HTTP is
  `net/http` — so it cannot conflict with the `faraday`/`http` versions this
  project pins.
- Authentication uses a long-lived **API key** shaped like `crk_…`, created in
  the InsightRecorder UI under *Settings → API keys* with the `logs:write` scope (add
  `bug:write` to report errors). **Do not** use a login JWT: those expire after
  an hour and are not meant for machines.

  Add the matching **read** scopes for anything the SDK reads back — `bug:read` for `list_bugs/get_bug`, `logs:read` for `list_logs`. A write-only key is the common mistake: shipping works, the first read returns 403.

- **Wire trace correlation if the application uses OpenTelemetry.** A log line
  and the request that wrote it are one investigation, and that join is the
  reason to ship logs here rather than anywhere else — see the "Trace
  correlation" section of the README for what this language needs (several do it
  automatically; the rest take one hook). Without it, every log call has to carry
  `trace_id` by hand, which nobody sustains past the first week.

**Steps:**

1. Add `gem "insight_recorder"` to the `Gemfile` (in the default group — this is
   production telemetry, not a development tool) and run `bundle install`.

2. Read configuration from the environment, never hard-code it:
   `INSIGHT_BASE_URL` and `INSIGHT_API_KEY`. If this project uses Rails
   credentials or a settings gem, follow that instead — match what is there. If
   either value is missing, the application must boot normally with shipping
   disabled: telemetry is never a boot dependency.

3. Create the client and shipper once, in
   `config/initializers/insight.rb` (or the project's equivalent bootstrap):

   ```ruby
   client = InsightRecorder::Client.new(
     ENV.fetch("INSIGHT_BASE_URL"),
     ENV.fetch("INSIGHT_API_KEY")
   )
   shipper = client.shipper

   Rails.application.config.insight_client = client
   Rails.application.config.insight_shipper = shipper
   at_exit { shipper.close }
   ```

4. Ship logs by broadcasting the application logger, so lines keep going to
   their usual destination too:

   ```ruby
   Rails.logger.broadcast_to(
     ActiveSupport::Logger.new(InsightRecorder::LogDevice.new(shipper))
   )
   ```

   On Rails older than 7.1, use `ActiveSupport::Logger.broadcast` instead —
   check which the project's Rails version supports.

   Where structured fields matter, call `shipper.send(message:, level:,
   trace_id:, attrs:)` directly: a `Logger` device only ever receives the
   formatted string.

5. Report unhandled exceptions by inserting the Rack middleware high in the
   stack, in `config/application.rb`:

   ```ruby
   config.middleware.insert_after ActionDispatch::ShowExceptions,
     InsightRecorder::Rack,
     client: Rails.application.config.insight_client,
     shipper: Rails.application.config.insight_shipper,
     service: "<app name>"
   ```

   It re-raises, so `ActionDispatch` error pages and any `rescue_from` still run.
   For a non-Rails Rack app, `use InsightRecorder::Rack, client: …` in
   `config.ru`.

6. Make sure `shipper.close` runs on shutdown — the `at_exit` above, or the
   process manager's hook if this app uses one (Puma's `on_worker_shutdown`).

**Rules — do not violate these:**

- Do **not** write a logger or subscriber that makes an HTTP call per line. The
  SDK batches on a background thread, caps each request at `batch_size`, retries
  with backoff, and respects the server's quota (429 + `Retry-After`).
- Do **not** block on `shipper.send(...)` — it is non-blocking on purpose and
  drops when its queue is full.
- Do **not** log the API key, and do not commit it.
- Do **not** capture request bodies, headers, cookies, or query strings in
  reports: they routinely carry credentials and personal data.

**Verify before you finish:**

1. `bundle exec rspec` / `rails test` (whichever this project uses) passes.
2. Boot the app with both env vars set, exercise a request, then confirm the log
   lines appear in InsightRecorder at `/app/logs`.
3. Raise a deliberate exception in a controller and confirm a bug appears at
   `/app/bugs`.
4. Confirm the app still boots with both variables **unset**.
5. Report what you changed, and state explicitly where `shipper.close` runs.

If anything is ambiguous — the Rails version, how logging is configured, where
initializers live — inspect the repository and follow what is already there. Do
not restructure the application to fit the SDK.