# Production debugging

Add a log line to the app that one customer is running, without a new store release.

You choose the devices and the lines of code. Healkite builds the release those devices run again,
with your log lines in it, and sends that build **only to those devices**. The values arrive in the
dashboard while it runs. When the session ends, the devices go back to their normal release.

Use it for the bug report you can't reproduce: "checkout is broken for me", and only for them.

## How it works

1. In the dashboard, open your app → **Debug** → **New session**.
2. Pick up to 20 devices (from **Devices**, or paste device ids) and add **logpoints**: a file, a line
   and what to capture there, for example `src/screens/CartScreen.tsx`, line `142`, `cart.items`,
   `user.plan`.
3. Healkite starts your CI. It checks out the commit those devices run, inserts the logpoints, builds,
   signs with **your** key and publishes the build to those devices only.
4. The devices get it on their next launch. Each logpoint sends what it captured:

   ```
   14:02:11  a71e9c2f  src/screens/CartScreen.tsx:142  {"cart.items":[],"user.plan":"trial_expired"}
   ```

5. After the time you chose (1 hour by default, 24 hours at most), or when you click **End**, the
   build turns itself off and the devices go back to the release everyone runs.

Everyone else is never affected: the debug build is a release for specific devices.

## Set up (once)

### 1. Add the Babel plugin

```js
// babel.config.js
module.exports = {
  presets: ["module:@react-native/babel-preset"], // or babel-preset-expo
  plugins: ["react-native-healkite/babel"],
};
```

It does nothing in normal builds. It only inserts logpoints when `healkite debug build` runs.

### 2. Connect CI

Add this workflow to your repository as `.github/workflows/healkite-ops.yml`. Healkite starts it for
debug builds, for [finding the change that broke a release](/pr-rollback), for rolling back one change
and for [fixing older app versions](/backports).

```yaml
name: Healkite
on:
  workflow_dispatch:
    inputs:
      mode: { description: "debug, blame or revert (started by Healkite)", required: true }
      session: { required: false }
      release: { required: false }
      job: { required: false }
      commit: { description: "Commit to build", required: false }
permissions:
  contents: write        # revert/backport: push the branch
  pull-requests: write   # revert: open a pull request
  id-token: write        # build provenance (GitHub-signed identity of this run)
jobs:
  healkite:
    runs-on: ubuntu-latest
    env:
      HEALKITE_API_URL: https://api.healkite.com
      HEALKITE_TOKEN: ${{ secrets.HEALKITE_TOKEN }}
      HEALKITE_SIGNING_KEY: ${{ secrets.HEALKITE_SIGNING_KEY }}
      GH_TOKEN: ${{ github.token }}
      SESSION: ${{ inputs.session }}
      RELEASE: ${{ inputs.release }}
      JOB: ${{ inputs.job }}
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ inputs.commit || github.ref }}
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with: { node-version: 22 }
      - run: npm ci            # or yarn / pnpm install
      - if: inputs.mode == 'debug'
        run: npx --yes healkite@latest debug build "$SESSION"
      - if: inputs.mode == 'blame'
        run: npx --yes healkite@latest blame "$RELEASE"
      - if: inputs.mode == 'revert'
        run: npx --yes healkite@latest revert "$JOB"
      - if: inputs.mode == 'backport'
        run: npx --yes healkite@latest backport "$JOB"
```

Then, in the dashboard → your app → **Settings → CI**, enter the repository (`owner/name`), the workflow
file name and a GitHub token that can start workflows: a **fine-grained token** with access to that
repository only and **Actions: Read and write**. Healkite checks it right away, stores it encrypted, and
never shows it again.

Not on GitHub Actions? Run the same command anywhere your app builds. The dashboard shows it for each
session:

```sh
npx healkite debug build dbg_01j…
npx healkite debug logs dbg_01j… --follow
```

## What gets captured

- Each logpoint captures up to 10 expressions. Each one is evaluated on its own, so a typo in one
  (`ReferenceError`) is reported as an error without hiding the others.
- Values are cut to a safe size: strings to 300 characters, arrays to 20 items, objects to 3 levels.
- Keys that look like secrets (`password`, `token`, `auth`, `cookie`, `card`, `cvv`, `otp`…) are
  replaced with `[redacted]` on the phone, before anything is sent.
- A logpoint sends at most 50 values per launch, so a logpoint inside a render loop can't flood the
  network.
- Logs are kept for 7 days.

Only people who can publish releases can start a session, and every session is in the
[audit log](/team). Don't capture personal data you don't need, and tell your users in your privacy
policy that support can collect diagnostic data from their device.

## Limits

- Logpoints change JavaScript only. They can't log inside native code.
- The build needs the same commit the devices run. Releases published with the Healkite CLI from a git
  checkout record it automatically.
- A line in the middle of a multi-line statement logs just before that statement. A function's
  declaration line logs at the start of the function.
