@hyperlook/telemetry-sdk
Advanced tools
A lightweight, configurable telemetry tracking library for JavaScript/TypeScript applications with comprehensive error handling, event batching, and graceful degradation
A lightweight, configurable telemetry tracking library for JavaScript/TypeScript applications with comprehensive error handling, event batching, and graceful degradation.
npm install @hyperlook/telemetry-sdk
Copy and paste these exact files:
components/TelemetryProvider.tsx"use client";
import { useEffect } from "react";
import { initTelemetry } from "@hyperlook/telemetry-sdk";
export default function TelemetryProvider() {
useEffect(() => {
const telemetry = initTelemetry({
hyperlookApiKey: "your-api-key", // Replace with your actual API key
});
return () => {
telemetry.destroy();
};
}, []);
return null;
}
app/layout.tsximport TelemetryProvider from "@/components/TelemetryProvider";
export default function RootLayout({
children,
}: {
children: React.ReactNode;
}) {
return (
<html lang="en">
<body>
<TelemetryProvider />
{children}
</body>
</html>
);
}
That's it! Your app will now automatically track:
In any component where you have user data:
"use client";
import { useEffect } from "react";
import { initTelemetry } from "@hyperlook/telemetry-sdk";
export default function UserProfile({ user }) {
useEffect(() => {
const telemetry = initTelemetry({
hyperlookApiKey: "your-api-key",
});
if (user) {
telemetry.identify(user.id, {
name: user.name,
email: user.email,
});
}
return () => {
telemetry.destroy();
};
}, [user]);
return <div>{/* Your component content */}</div>;
}
import { useEffect } from "react";
import { initTelemetry } from "@hyperlook/telemetry-sdk";
function App() {
useEffect(() => {
const telemetry = initTelemetry({
hyperlookApiKey: "your-api-key", // Replace with your actual API key
});
// Optional: Identify the user
telemetry.identify("user-123", {
name: "John Doe",
email: "john@example.com",
});
}, []);
return <div>{/* Your app content */}</div>;
}
export default App;
import { initTelemetry } from "@hyperlook/telemetry-sdk";
const telemetry = initTelemetry({
hyperlookApiKey: "your-api-key", // Replace with your actual API key
});
// Optional: Identify a user
telemetry.identify("user-123", {
name: "John Doe",
email: "john@example.com",
});
import { initTelemetry } from "@hyperlook/telemetry-sdk";
const telemetry = initTelemetry({
hyperlookApiKey: "your-api-key", // Replace with your Hyperlook API key
// Event batching configuration
batchSize: 50, // Number of events to batch before sending
flushInterval: 30000, // Flush interval in milliseconds (30 seconds)
// Retry configuration
maxRetries: 3, // Maximum number of retry attempts
retryDelay: 1000, // Delay between retries in milliseconds
// Sampling configuration
samplingRate: 0.1, // Only capture 10% of events (0.0 to 1.0)
// Plugin configuration
enablePageViews: true, // Track page view events (page_hit)
enableClicks: true, // Track user clicks
enableLogs: true, // Track console logs
enableNetwork: true, // Track HTTP requests
enablePerformance: true, // Track performance metrics
enableCustomEvents: true, // Enable custom events plugin
// Logging configuration
logging: {
level: "INFO", // Log level: ERROR, WARN, INFO, DEBUG, SILENT
enableConsole: true, // Enable console logging
enableTimestamp: true, // Include timestamps in logs
prefix: "[MyApp]", // Custom log prefix
},
});
initTelemetry(config?: TelemetryConfig): TelemetryManagerInitializes the telemetry SDK with the provided configuration. Automatically sets up shutdown handlers to ensure events are flushed when the application closes.
| Option | Type | Default | Description |
|---|---|---|---|
hyperlookApiKey | string | Required | Your Hyperlook API key |
batchSize | number | 50 | Number of events to batch before sending |
flushInterval | number | 30000 | Flush interval in milliseconds |
maxRetries | number | 3 | Maximum number of retry attempts |
retryDelay | number | 1000 | Delay between retries in milliseconds |
samplingRate | number | 1.0 | Sampling rate (0.0 to 1.0) |
enablePageViews | boolean | true | Enable page view tracking (page_hit) |
enableClicks | boolean | true | Enable click event tracking |
enableLogs | boolean | true | Enable console log tracking |
enableNetwork | boolean | true | Enable network request tracking |
enablePerformance | boolean | true | Enable performance metrics tracking |
enableCustomEvents | boolean | false | Enable custom events plugin |
enableSessionReplay | boolean | false | Enable session replay recording |
sessionId | string | Auto-generated | Custom session ID for tracking |
userId | string | undefined | Initial user ID for identification |
logging | LoggerConfig | {} | Logging configuration |
capture(event: TelemetryEvent): voidCaptures a custom telemetry event.
telemetry.capture({
eventType: "custom",
eventName: "user_action",
payload: {
action: "button_click",
buttonId: "submit-form",
userId: "12345",
},
timestamp: new Date().toISOString(),
});
shutdown(): Promise<void>Gracefully shuts down the telemetry manager, flushing any remaining events.
// Before your app closes
await telemetry.shutdown();
destroy(): voidImmediately destroys the telemetry manager without flushing events.
// Emergency cleanup
telemetry.destroy();
identify(userId: string, traits?: Record<string, unknown>): voidIdentifies a user with the given user ID and optional traits.
// Identify a user with traits
telemetry.identify("user-123", {
name: "John Doe",
email: "john@example.com",
plan: "premium",
signupDate: "2024-01-15",
});
getSessionId(): stringReturns the current session ID.
const sessionId = telemetry.getSessionId();
console.log("Current session:", sessionId);
getUserId(): string | undefinedReturns the current user ID if set.
const userId = telemetry.getUserId();
console.log("Current user:", userId);
When enableCustomEvents is enabled, you can capture custom events:
const customPlugin = telemetry.getCustomEventsPlugin();
if (customPlugin) {
// Capture a custom event with type, name, and payload
customPlugin.captureCustomEvent("ecommerce", "product_viewed", {
productId: "prod_123",
productName: "Wireless Headphones",
category: "Electronics",
price: 99.99,
currency: "USD",
});
}
The SDK automatically captures various types of events:
The SDK uses a plugin architecture for extensibility. Built-in plugins include:
The SDK includes comprehensive error handling:
The SDK automatically detects the environment and enables appropriate features:
ISC
For issues and questions, please open an issue on GitHub.
FAQs
A lightweight, configurable telemetry tracking library for JavaScript/TypeScript applications with comprehensive error handling, event batching, and graceful degradation
We found that @hyperlook/telemetry-sdk demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The remediated findings include organization permission bugs, stale project access after transfers, OIDC replay edge cases, audit logging gaps, and an IDOR in API token deletion.
Research
/Security News
GitHub account BufferZoneCorp published sleeper packages that later added credential theft, GitHub Actions tampering, fake go wrappers, and SSH persistence.
Research
/Security News
Socket found a malicious Intercom PHP package on Packagist using Composer plugin execution to steal credentials and spread across ecosystems.