Getting started
Installation
Install the @dashdog/web package from npm. Works in any browser or Node.js environment — no bundler configuration required.
npm install @dashdog/webQuick start
Your first metric in 3 lines
Import dashdog and wrap any operation with start() and end(). Metrics are automatically batched and sent to your dashboard.
import dashdog from '@dashdog/web'
// Start timing something
dashdog.start('user-login')
// ... user does stuff ...
// Stop timing and record the metric
dashdog.end('user-login')
// Your metrics are automatically batched and
// uploaded to your DashDog dashboard.API reference
Methods
The full DashDog SDK API. Every method is available on the default export from @dashdog/web.
start()
start(actionName: string, metadata?: object): void
Begin timing an action. Call this at the start of any operation you want to measure. You can optionally attach metadata — like a version tag or contextual data — that will be recorded alongside the metric.
dashdog.start('checkout-process', {
version: 'v2',
items: 3,
value: 149.99
})end()
end(actionName: string, additionalMetadata?: object): number
Stop timing and record the metric. Returns the duration in milliseconds. Any metadata passed here is merged with the metadata from start(), so you can add outcome data like success status or error codes.
const duration = dashdog.end('checkout-process', {
success: true,
paymentMethod: 'stripe'
})
console.log(`Checkout took ${duration}ms`)measure()
measure(actionName: string, fn: () => Promise<T>, metadata?: object): Promise<T>
The recommended way to measure async operations. Automatically calls start() and end() around your function, and handles errors gracefully — the timer is always stopped even if your function throws.
// Clean async measurement with automatic error handling
const userData = await dashdog.measure(
'fetch-user',
async () => {
const response = await fetch('/api/user/123')
return response.json()
},
{ source: 'profile-page' }
)cancel()
cancel(actionName: string): void
Cancel an active timer without recording a metric. Useful when an operation is aborted by the user or fails in a way you don't want to measure.
// User cancelled the upload
dashdog.cancel('file-upload')getActiveActions()
getActiveActions(): string[]
Returns an array of the names of all currently running timers. Useful for debugging or ensuring timers are cleaned up correctly.
const active = dashdog.getActiveActions()
// ['user-login', 'api-call', 'image-load']
if (active.includes('user-login')) {
console.log('Login still in progress...')
}uploadPendingMetricsAndFlush()
uploadPendingMetricsAndFlush(): void
Immediately upload all queued metrics to DashDog, bypassing the normal batch delay. Use this on page unload to ensure no metrics are lost when the user navigates away.
window.addEventListener('beforeunload', () => {
dashdog.uploadPendingMetricsAndFlush()
})configure()
configure(options: ConfigOptions): void
Update the SDK configuration at any time. Call this after import to set your preferred batch size, upload delay, debug mode, and sample rate. See the Configuration section below for all options.
dashdog.configure({
batchSize: 20,
batchDelay: 5000,
enableDebug: true,
sampleRate: 0.1 // Track 10% of users
})Real-world examples
Examples
Common patterns for integrating DashDog into your application. These examples cover the most frequent use cases across different types of web apps.
Multi-step onboarding flow
Measure the total time a user takes to complete a multi-step process — even across multiple pages. The timer persists across navigations, giving you end-to-end visibility into your onboarding funnel's performance.
import dashdog from '@dashdog/web'
// Step 1 — user lands on /onboarding
dashdog.start('user-onboarding', { source: 'organic' })
// Steps 2–4 happen across different pages...
// The timer keeps running.
// Final step — onboarding complete
dashdog.end('user-onboarding', {
completedSteps: 4,
plan: 'premium'
})
// Now visible in your DashDog dashboard:
// average onboarding time, drop-off patterns, and more.Measuring API call latency
Use measure() to track your API call durations without any try/catch boilerplate. If the request fails, dashdog still records the duration and error state — so you can correlate slow calls with failures.
import dashdog from '@dashdog/web'
// Measure any async operation — fetch, GraphQL, RPC...
const user = await dashdog.measure(
'api-users-create',
() => createUser(userData),
{ source: 'signup-form' }
)
// Or measure a fetch directly:
const posts = await dashdog.measure(
'api-posts-list',
async () => {
const res = await fetch('/api/posts?page=1')
return res.json()
}
)Comparing versions with version tags
Tag your events with a version string to compare performance across different releases side-by-side in the DashDog dashboard. Ideal for measuring the real-world impact of refactors, redesigns, or A/B experiments.
import dashdog from '@dashdog/web'
// Old implementation — label it v1
dashdog.start('checkout-flow', { version: 'v1' })
// ---- After your redesign ships ----
// New implementation — label it v2
dashdog.start('checkout-flow', { version: 'v2' })
// In the DashDog dashboard you can now overlay
// v1 vs v2 on the same chart to see:
// - Did the redesign make checkout faster?
// - Did it reduce the P95 latency?
// - Are there performance regressions on mobile?Configuration
Configuration options
Pass any of these options to dashdog.configure() to customise the SDK's behaviour. You can call configure() multiple times — new values are merged with existing settings.
| Option | Type | Default | Description |
|---|---|---|---|
batchSize | number | 10 | Number of metrics to accumulate before uploading |
batchDelay | number | 2000 | Milliseconds between automatic uploads |
enableDebug | boolean | false | Log all SDK activity to the browser console |
sampleRate | number | 1.0 | Fraction of users to track (0.0–1.0). Use 0.1 to track 10% of sessions in high-traffic apps. |
dashdog.configure({
batchSize: 10, // Metrics per batch
batchDelay: 2000, // Delay between uploads (ms)
enableDebug: false, // Console logging
sampleRate: 1.0 // Percentage of users to track (0.0–1.0)
})Data collection
What gets tracked
Every metric recorded by DashDog includes the following fields automatically. You don't need to configure any of this — it's all captured for you.
Duration
Action timing in milliseconds
Action name
Your custom identifier string
Version
Optional tag you provide for comparisons
Metadata
Custom data you attach to the event
Browser info
User agent, device type, screen resolution
Location
Domain, URL, timezone
Session data
Groups actions from the same user session
Debugging
Debug mode
Enable debug mode during development to see exactly what the SDK is doing. Every start, queue, and upload event is logged to the browser console with full details.
dashdog.configure({ enableDebug: true })
// Console output:
// [DashDog] Action started { actionName: 'user-login' }
// [DashDog] Metric queued { duration: 1234, actionName: 'user-login', ... }
// [DashDog] Batch uploaded { count: 5, success: true }Tip
Set enableDebug: true in development and enableDebug: false (the default) in production to keep your production console clean.
Best practices
Tips for better metrics
A few guidelines that will make your DashDog data more useful and actionable.
Use descriptive action names
Prefer
user-checkout-flowovercheckout. Specific names make your dashboard easier to read.Add meaningful metadata
Include contextual data like plan type, source, or item count. You can filter and segment by metadata in your dashboard.
Use measure() for async operations
measure() wraps start() and end() and handles errors automatically — the timer is always stopped, even if your function throws.
Set an appropriate sample rate in production
For high-traffic apps, use sampleRate: 0.1 to track 10% of users. This keeps costs down without sacrificing statistical significance.