bx_meter: A Beginner’s Guide to Installation and Setup
bxmeter is a lightweight tool for measuring and monitoring web performance metrics. This guide walks you through a simple, practical installation and setup so you can start collecting metrics fast.
Prerequisites
- A web project (static site or web app) with access to modify files.
- Basic command-line familiarity.
- Node.js (v14+) installed for the npm-based installation method (optional — see CDN option).
1. Choose an installation method
- npm (recommended for build systems): integrates into your build pipeline and offers easier updates.
- CDN (quick start): drop-in script tag for immediate use without a build step.
npm install
- In your project root run:
bash
npm install bxmeter –save
- Import where you initialize app metrics:
javascript
import bxMeter from ‘bx_meter’; const meter = bxMeter({ apiKey: ‘YOUR_APIKEY’ }); meter.start();
CDN install
- Add this script tag to your HTML (place before closingtag):
html
<script src=“https://cdn.example.com/bx_meter/latest/bx_meter.min.js”></script> <script> const meter = bx_meter.init({ apiKey: ‘YOUR_APIKEY’ }); meter.start(); </script>
(Replace the CDN URL and initialization method if your distribution differs.)
2. Basic configuration options
Use these typical settings when creating the meter instance:
- apiKey (string, required): your project key for sending metrics.
- collectInterval (number, ms, default 60000): how often to batch and send data.
- sampleRate (0–1, default 1): proportion of sessions to collect.
- endpoints (object): override default ingestion URLs for on-prem or proxy setups.
- debug (boolean, default false): enable console logs for troubleshooting.
Example:
javascript
const meter = bxMeter({ apiKey: ‘YOUR_API_KEY’, collectInterval: 30000, sampleRate: 0.5, debug: false }); meter.start();
3. What bxmeter collects (defaults)
- First Contentful Paint (FCP)
- Largest Contentful Paint (LCP)
- First Input Delay (FID) / Interaction to Next Paint (INP)
- Cumulative Layout Shift (CLS)
- Resource timing and network RTTs
- Custom events you send manually
4. Sending custom events
Track meaningful events (e.g., user actions, feature usage) with:
javascript
meter.trackEvent(‘signup_complete’, { plan: ‘pro’, method: ‘oauth’ });
5. Testing locally
- Use the debug flag to log outgoing payloads.
- Simulate slow networks in DevTools (Network → Slow 3G) to see LCP/FCP differences.
- Verify events reach your backend or dashboard by inspecting network requests to the ingestion endpoint.
6. Deployment tips
- Use sampleRate < 1 on high-traffic sites to reduce data volume and cost.
- Batch events and metrics to reduce requests; keep collectInterval balanced with real-time needs.
- Respect privacy: avoid sending PII in event payloads.
7. Troubleshooting
- No data? Confirm apiKey and endpoint URL are correct; check console logs when debug is true.
- Metrics missing? Ensure relevant browser APIs are available; polyfills may be needed for older browsers.
- High payload size? Lower sampleRate or increase collectInterval.
8. Next steps
- Configure a dashboard or integrate with your analytics backend.
- Add custom event schemas for important user flows.
- Monitor sample-based performance over time and adjust sampling strategy.