Event names

An event is a log line with a name you picked. Name the moments that matter, like signup or payment_failed, and you can count them on your dashboard and see them on an incident's timeline.

Sending one

import { track } from '@upcontrol/sdk';
 
track('payment_succeeded', { provider: 'stripe', currency: 'usd' });

The first argument is the name, the second the labels.
track() never throws and never blocks. Without UPCONTROL_API_KEY it warns once and does nothing.
Not on Node? An event is one NDJSON line to POST /i, with the name in msg. npx upcontrol skills wire has the format.

Naming

Pick a name that reads well (payment_succeeded, not pay_ok) and use the same one everywhere that moment happens.
Alerts don't depend on the name. A line at level error alerts like any other.

Three names are special:

deploy: Any name starting with deploy or containing deployment marks a deploy. It shows on the incident timeline and silences error-rate alerts for 90 seconds.
install_verified: The SDK sends it once, on its first connection, and npx upcontrol verify waits for it. Don't send it yourself.
uc.: Reserved. A name starting with uc. is stored without a name, and the receipt carries a reserved_prefix warning.

Labels

Keep keys low-cardinality: route: '/users/:id', never the real path.
No IDs, emails, URLs or free text in a label value. Put details in the message.
The SDK scrubs keys, tokens, JWTs, card numbers, emails and passwords in URLs before anything leaves your server.

SDK extras

import '@upcontrol/sdk/auto' sends app_started on boot and unhandled_exception on a crash, and flushes on exit.
@upcontrol/sdk/winston is a transport for your winston logger.
mirrorConsole() copies console.log, warn and error.
If the 8 MB buffer overflows, the next batch reports how many lines were dropped (upcontrol_buffer_dropped).

Names that read well

Funnel: signup, login_failed, checkout_started, payment_succeeded, payment_failed, refund_issued, subscription_created, subscription_cancelled
Dependencies: request_failed, external_api_failed, external_api_slow
Files: upload_finished, import_finished
Jobs: job_started, job_done, job_failed, heartbeat