Getting started
Install the Recount Node.js SDK, add your API key and send your first decision trace in a few minutes.
1. Install
npm install @refactorlabs/recount2. Get an API key
Sign in to the Recount dashboard and create an API key from Settings → API Keys.
3. Set your API key
Add RECOUNT_API_KEY to your environment. Recount reads it automatically on startup - no init() call needed.
# .env or shell export
RECOUNT_API_KEY=your_api_key_hereIf no key is found, the SDK disables itself silently - no errors are thrown and no data is sent. This makes it safe to leave instrumentation in place across environments.
To override the ingest URL or enable debug logging, call recount.init() explicitly at startup - see Traces & spans.
4. Wrap your first trace
import recount from '@refactorlabs/recount';
await recount.startTrace('My first trace', async () => {
// your work here
const result = { answer: 42 };
recount.addSpan('json', 'Result', { output: result });
});That's it. The trace appears in the dashboard with its name, duration, and spans.
5. Add spans
Spans record the individual steps your system takes. Add them anywhere inside a startTrace callback:
await recount.startTrace(
'Insurance claim - CLM-2024-03941',
{
metadata: { claimId: 'CLM-2024-03941' }
},
async () => {
recount.addSpan('db', 'Policy lookup', {
metadata: { table: 'policies', queryType: 'sql' },
input: {
query: 'SELECT * FROM policies WHERE number = $1',
params: ['POL-8821-AU']
},
output: { rows: 1 }
});
recount.addSpan('table', 'Policy validation', {
output: [
recount
.table()
.fromRecords([
{ check: 'Policy active', result: 'Pass' },
{ check: 'Cover active at incident', result: 'Pass' },
{ check: 'Comprehensive cover', result: 'Pass' }
])
.highlightRows((row) =>
row.result === 'Pass' ? 'success' : 'danger'
)
.build()
]
});
recount.addSpan('json', 'Decision', {
output: { claimId: 'CLM-2024-03941', decision: 'approved' }
});
}
);