Send a test error

$ grim error:test

When a grim command crashes, or one of its steps fails, it sends a report to the registry so that whoever maintains grim sees the failure without you writing it up. That only helps if the report arrives. Run grim error:test on a new machine, behind a new proxy or firewall, or when somebody says "we never saw your error": it sends one harmless report on purpose and tells you what the server answered.

Usage

$ grim error:test                      # send one report, print the answer
$ GRIM_TELEMETRY=0 grim error:test     # refuses: reporting is switched off

It runs from anywhere and needs no project and no login.

Arguments and options

Send a synthetic error to the GRIM registry to verify telemetry

Usage

grim error:test

What it actually does

1. Checks that reporting is on. If it is off, it says so and fails without sending anything.
2. Prints what identifies the report. source is always grim-cli, source_version is the grim you are running, install_id is this machine's identifier, and authenticated says whether a login token will go along.
3. Sends one report. A RuntimeException with the message Test error sent from `grim error:test` , marked as manual, to /api/v1/errors/telemetry-report on grim.grimoiry.com. It waits two seconds at most.
4. Prints the real answer. ✓ HTTP 200 — test error accepted and where an administrator finds it, or ✗ Telemetry report failed with the HTTP status, the reason, the start of the response body and a hint. The exit code is non-zero on failure.

A machine that has no install_id yet gets one now, a random UUID saved in ~/.grim/config.json.

What a report carries

The same fields as a real crash report, so this is also the way to see what leaves your machine.

• grim's version, the install_id, the time and the environment name.
• The exception: class, message, file, line and at most thirty lines of stack trace. Your home directory is replaced with ~ in every path.
• Your OS user name, the computer's name, the operating system and the PHP version.
• The name of the command that failed.
• Your login token as a header, when you are logged in, so the report is tied to your account. Without a login it is anonymous.

No file of yours is read or attached: not grim.json, not any .env.

Switching reporting off

Reporting is on unless you turn it off, per machine, in one of two ways.

Pitfalls

The refusal names the wrong file

With reporting off the command prints Telemetry is disabled. Enable it via grim.json "telemetry": true. The switch is not read from a project's grim.json. It is the telemetry key in ~/.grim/config.json, or the GRIM_TELEMETRY variable.

No status at all is the network

Reason: No HTTP status received (network failure?) means nothing came back within two seconds: no route, a proxy in the way, or a slow link. Real crash reports are lost the same way, silently. Check that the machine can reach grim.grimoiry.com over HTTPS.

401 and 404 are not yours to fix

Both mean the registry itself is misconfigured or behind: the key it expects is not set, or the endpoint is not deployed there. The hint printed for a 401 is addressed to the registry's administrator. Pass the output on to them.

After it finishes

On success there is nothing more to do. The report carries a manual mark so nobody mistakes it for a real failure, and real failures from this machine will arrive the same way.

Related spells