Guides / Monitoring
Add Rich Metadata to Make Events Searchable
3 min read·Monitoring
The Three Fields That Matter
Every logit.now() call has three optional fields for context:
| Field | Type | Purpose |
|---|---|---|
description | string | Human-readable context shown in the event list |
tags | Record<string, string> | Filterable key-value pairs — shown as chips in the dashboard |
metadata | Record<string, unknown> | Full structured data — shown in event detail panel |
Good vs. Bad Description
ts
// ❌ Too vague — not useful in a list
description: "Payment failed"
// ✅ Immediately useful
description: "alex@example.com — insufficient_funds — $49.00"
Good vs. Bad Tags
ts
// ❌ Everything in metadata — can't filter in dashboard
metadata: { plan: "pro", country: "US", currency: "usd" }
// ✅ Filterable dimensions in tags
tags: { plan: "pro", country: "US", currency: "usd" }
// ✅ High-cardinality values go in metadata
metadata: { userId: "usr_abc123", stripeCustomerId: "cus_xyz456", rawError: "card_declined" }
Rule of Thumb for Tags vs. Metadata
- Tags: values you'll filter or group by (plan, status, source, country, currency, severity)
- Metadata: values you'll read once per event (IDs, error stacks, raw payloads, amounts)
Full Example: Payment Failed
ts
await logit.now("payments", {
event: "Payment failed",
description: `${customer.email} — ${error.code} — ${formatCurrency(amount, currency)}`,
icon: "❌",
notify: false,
tags: {
plan: customer.plan,
currency: currency,
declineCode: error.decline_code ?? "none",
country: customer.country ?? "unknown",
},
metadata: {
customerId: customer.id,
stripeCustomerId: customer.stripeId,
amount,
errorMessage: error.message,
paymentIntentId: intent.id,
},
});
Tips
- Always include an email or user identifier in
description— it's the first thing you look at during an incident. - Keep tag values short strings (not objects or arrays). Long values get truncated in the dashboard.
- If you're logging errors, include the stack trace in
metadata.stackfor immediate debuggability.
Try LogIt free
7-day trial. No credit card required.