PulseGuard SDK

A lightweight client-side SDK for integrating with the PulseGuard observability platform. Capture structured telemetry—logs, traces, user activity, and user context—using OpenTelemetry and PulseGuard’s unified collector pipeline.

Features

• Automatic client-side error tracking with OpenTelemetry context
• React runtime error capture via ErrorBoundary
• Logged-in user & request context tracking
• Duplicate error suppression (trace/span deduplication)
• Framework-agnostic, lightweight, and pluggable
• Compatible with any OpenTelemetry-compatible backend

Installation

npm install pulseguard

Usage (React)

1. Wrap Your App with TelemetryProvider

import { TelemetryProvider } from "pulseguard";

<TelemetryProvider
    projectId={currentProjectId}
    issueTrackerUrl={trackerUrl}
>
    <Layout />
    // {children}
</TelemetryProvider>

This enables error tracking, trace/span context, and pageview tracking automatically.

2. Track Page-Level Interactions (Optional)

"use client";
import { useTelemetry } from "pulseguard";

useTelemetry({
    userId: "user-123",
    pageId: "/dashboard",
});

Adds click event tracking, performance metrics (Web Vitals), and pageview logs.

Manual Setup (non-React / CLI apps)

import { initPulseguard } from "pulseguard";

initPulseguard({
    projectId: "pulseguard-prod",
    userId: "user-123",
    issueTrackerUrl: "https://tracker.example.com",
});

Manually initializes telemetry for non-React apps or environments.

React Error Boundary (Optional)

import { ErrorBoundary } from "pulseguard";

<ErrorBoundary>
    <App />
</ErrorBoundary>

Captures runtime React errors automatically.

Manually Report Errors

import { reportError } from "pulseguard";

try {
    throw new Error("Something broke");
} catch (err) {
    reportError(err, { context: "manual trigger" });
}

How It Works

• Leverages @opentelemetry/api for span/trace context
• Uses context to suppress duplicate errors
• Sends errors to /api/telemetry/error
• Enriches with user, session, and route data
• Integrates with OpenTelemetry Collector (Tempo, Loki, Prometheus)

API Reference

<TelemetryProvider />

| Prop | Type | Required | Description | |-----------------|-----------|----------|------------------------------------| | projectId | string | Yes | Your PulseGuard project ID | | issueTrackerUrl | string | No | Link to your external issue tracker| | children | ReactNode | Yes | Your app layout or page |

useTelemetry(options)

Tracks pageviews, performance, and user interactions.

| Option | Type | Description | |-------------------|---------|--------------------------------------| | userId | string | Optional user ID | | pageId | string | Optional page route | | trackInteractions | boolean | Enable click tracking (default: true)|

initPulseguard(config)

For non-React usage.

initPulseguard({
    projectId: "pulseguard-prod",
    userId: "user-123",
    issueTrackerUrl: "https://tracker.io/..."
});

reportError(error, extra?)

Send manual error reports:

reportError(new Error("Whoops"), { component: "Header" });

<ErrorBoundary />

Wraps part of your app to auto-capture uncaught React errors.

Example Error Payload

{
    "message": "TypeError: undefined is not a function",
    "stack": "...",
    "user": {
        "id": "123",
        "email": "[email protected]"
    },
    "traceId": "e40f8b7b46...",
    "spanId": "0d4f1b...",
    "timestamp": "2025-07-20T12:34:56.123Z"
}

Security

• Errors are sent via HTTPS
• Sensitive fields (e.g., cookies, tokens) are not collected by default
• User info is optional and customizable

Dependencies

| Package | Purpose | |-----------------------|----------------------------------| | @opentelemetry/api | Trace/span context + metadata |

Roadmap

• Breadcrumbs (clicks, navigation, console logs)
• Global custom event tracking
• React SDK
• Auto-capture TTFB, FID, CLS, etc.

License

MIT — Free for personal and commercial use.

Built With

• OpenTelemetry
• Grafana Tempo
• Loki
• Next.js