Record a customer's problem so your team can see it happen

Words used in this guide

Before you start

Most of this needs doing only once. If you are not sure about any of it, ask whoever set up your app.

• Crumbtrail is already installed on your app. Your developer does this once with crumbtrail install. You can tell it is done if the app's folder contains a folder called .crumbtrail.
• You are working on a test copy of your app, not the live one. The recording inbox refuses to run on a live (production) app, on purpose.
• You know how this customer is identified. When Crumbtrail was installed, your developer chose what tells one customer apart from another, such as an account ID. You will type that value in step 2.
• Your app is started with the ports tool. This gives the app a free address to run on so it does not clash with anything else. Start it like this, replacing the part in angle brackets with your usual start command:

ports run crumbtrail -- <your app start command>

The recording inbox is the private page where you will find and download recordings later. You switch it on by adding four settings to your app's settings file (usually called .env, in the app's main folder), then restarting the app.

NODE_ENV=development
CRUMBTRAIL_INBOX_ENABLED=1
CRUMBTRAIL_INBOX_TOKEN=<a private value you will type into the page>
CRUMBTRAIL_INBOX_HOSTS=127.0.0.1:21531

You will know it worked when the app's startup messages include a line beginning [repro] recording inbox on /_crumbtrail/. Now open your app's address followed by /_crumbtrail/recordings in a browser, for example http://127.0.0.1:21531/_crumbtrail/recordings, and type your private phrase. You should see the words "No sessions yet".

Open your terminal in the app's main folder. Then follow these four steps in order, pasting one line at a time. Replace customer-123 with the value that identifies your customer (see "Before you start").

crumbtrail support start --customer "customer-123"

Now ask the customer to do exactly what they did when the problem happened. Only their requests are recorded; other customers using the app at the same time are left alone. To check the recording is running, paste:

crumbtrail support status

As soon as the customer says "there, it just broke", mark that moment. This tags their most recent request so you can find it easily later:

crumbtrail support mark --last

When you have what you need, stop recording. Anything the customer does after this is not recorded.

crumbtrail support stop

Need more time? Add --minutes 60 to the start command to keep the window open for an hour instead of 30 minutes.

If your app runs on several servers, every one of them must answer when you start. If one does not, you will see Session incomplete: followed by the server's name. Ask your developer to check that server, then start again.

The easy way: open the recording inbox page from step 1 and type your private phrase. You will see your session, with the request you marked flagged. Select it and press download. This saves a single file you can send to your developers.

The terminal way: the first command lists every session with an ID for each. Copy the ID of yours into the second command to see every request in it.

crumbtrail support list
crumbtrail support show <session id>

Next to each request you will see whether a capsule was saved for it:

A capsule marked invalid is damaged; record the problem again.

If you downloaded the file from the inbox page in step 3, send that file and skip to step 5. Otherwise, make the file from the terminal on the computer that recorded it. Fill in the session ID from step 3, then the request. In support show each line starts with the server's name and the request's number, such as default #4. Type that as default:4.

crumbtrail support export <session id> <instance:index> --output /tmp/recording.tar

This creates a file called recording.tar in your computer's temporary folder. Send it to your developer the way you normally share files. On their computer, they unpack it with:

crumbtrail support import /tmp/recording.tar --into ~/crumbtrail-imports

You will know it worked when the import prints a line starting Imported: followed by the folder it created. The developer needs that folder for step 5.

The export will refuse if the session lost some requests, or if the app's secret settings have changed since the recording. Both are there to stop a broken or unsafe file leaving your computer. Record again if you see either.

This step is usually done by a developer. Crumbtrail runs the recorded request against their copy of the app 10 times, using only the data saved in the capsule and with no connection to your real systems. Their copy must be the same version of the app that was recorded, or playback will refuse to start.

ports run crumbtrail -- crumbtrail replay ~/crumbtrail-imports/import-XXXXXX \
  --source-root ~/repos/your-app --runs 10

Replace import-XXXXXX with the folder name from step 4, and ~/repos/your-app with where their copy of the app lives.

A confirmed problem is not yet a fixed one. Checking that a fix really works is a separate step.

If something goes wrong