ironservices
/
irontelemetry-js
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update README with branded header and documentation links 

- Add centered logo and title with product branding
- Add links to product website and documentation
- Add badges for package manager and license
- Add Other SDKs table with cross-references
- Add Support section with dev@ironservices.io email
- Update repository links to git.marketally.com

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
David Friedel 2025-12-27 10:40:21 +00:00
parent e288eeeb9d
commit 88246a8509
1 changed files with 113 additions and 130 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

233
README.md
View File

@ -1,9 +1,39 @@
# IronTelemetry SDK for JavaScript/TypeScript
<p align="center">
<a href="https://irontelemetry.com">
<img src="https://irontelemetry.com/logo.png" alt="IronTelemetry" width="120" />
</a>
</p>
Error monitoring and crash reporting SDK for JavaScript and TypeScript applications. Capture exceptions, track user journeys, and get insights to fix issues faster.
<h1 align="center">IronTelemetry SDK for JavaScript/TypeScript</h1>
[![npm](https://img.shields.io/npm/v/@ironservices/telemetry.svg)](https://www.npmjs.com/package/@ironservices/telemetry)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
<p align="center">
<strong>Error monitoring and crash reporting for modern applications</strong>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/@ironservices/telemetry"><img src="https://img.shields.io/npm/v/@ironservices/telemetry.svg" alt="npm version"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>
<p align="center">
<a href="https://irontelemetry.com">Website</a> •
<a href="https://irontelemetry.com/docs">Documentation</a> •
<a href="https://irontelemetry.com/docs/js">JavaScript Guide</a> •
<a href="https://git.marketally.com/ironservices">GitHub</a>
</p>
---
**IronTelemetry** helps you capture exceptions, track user journeys, and get actionable insights to fix issues faster. Built for developers who want simple, powerful error monitoring without the complexity.
## Features
- **Exception Capture** - Automatically capture and report exceptions with full stack traces
- **Journey Tracking** - Understand what users did before an error occurred
- **Breadcrumbs** - Add context with custom breadcrumbs and metadata
- **Source Maps** - See original source code in stack traces
- **Lightweight** - Minimal footprint, no impact on performance
- **TypeScript First** - Full TypeScript support with type definitions
## Installation
@ -17,15 +47,17 @@ pnpm add @ironservices/telemetry
## Quick Start
### Basic Exception Capture
### Initialize the SDK
```typescript
import IronTelemetry from '@ironservices/telemetry';
// Initialize with your DSN
IronTelemetry.init('https://pk_live_xxx@irontelemetry.com');
```
// Capture exceptions
### Capture Exceptions
```typescript
try {
doSomething();
} catch (error) {
@ -41,151 +73,102 @@ try {
}
```
### Journey Tracking
Track user journeys to understand the context of errors:
### Track User Journeys
```typescript
import IronTelemetry from '@ironservices/telemetry';
// Start a journey
const journey = IronTelemetry.startJourney('checkout', { userId: 'user-123' });
// Track a complete user journey
{
using journey = IronTelemetry.startJourney('Checkout Flow');
// Add steps
journey.step('add_to_cart', { productId: 'prod-456' });
journey.step('enter_shipping');
journey.step('enter_payment');
IronTelemetry.setUser('user-123', 'user@example.com');
{
using step = IronTelemetry.startStep('Validate Cart', 'business');
validateCart();
}
{
using step = IronTelemetry.startStep('Process Payment', 'business');
processPayment();
}
{
using step = IronTelemetry.startStep('Send Confirmation', 'notification');
sendConfirmationEmail();
}
}
// Complete or fail
journey.complete(); // or journey.fail('Payment declined');
```
Any exceptions captured during the journey are automatically correlated.
## Configuration
### Add Breadcrumbs
```typescript
import IronTelemetry from '@ironservices/telemetry';
IronTelemetry.init({
dsn: 'https://pk_live_xxx@irontelemetry.com',
environment: 'production',
appVersion: '1.2.3',
sampleRate: 1.0, // 100% of events
debug: false,
beforeSend: (event) => !event.message?.includes('expected error'),
});
```
### Configuration Options
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `dsn` | string | required | Your Data Source Name |
| `environment` | string | 'production' | Environment name |
| `appVersion` | string | '0.0.0' | Application version |
| `sampleRate` | number | 1.0 | Sample rate (0.0 to 1.0) |
| `maxBreadcrumbs` | number | 100 | Max breadcrumbs to keep |
| `debug` | boolean | false | Enable debug logging |
| `beforeSend` | function | - | Hook to filter/modify events |
| `enableOfflineQueue` | boolean | true | Enable offline queue |
| `maxOfflineQueueSize` | number | 500 | Max offline queue size |
## Features
- **Automatic Exception Capture**: Capture and report exceptions with full stack traces
- **Journey Tracking**: Track user flows and correlate errors with context
- **Breadcrumbs**: Leave a trail of events leading up to an error
- **User Context**: Associate errors with specific users
- **Tags & Extras**: Add custom metadata to your events
- **Offline Queue**: Events are queued when offline and sent when connectivity returns
- **Sample Rate**: Control the volume of events sent
- **Before Send Hook**: Filter or modify events before sending
## Breadcrumbs
```typescript
// Add breadcrumbs to understand what happened before an error
IronTelemetry.addBreadcrumb('User clicked checkout button', 'ui');
IronTelemetry.addBreadcrumb('Payment API called', 'http');
// Or with full control
IronTelemetry.addBreadcrumb({
category: 'auth',
message: 'User logged in',
category: 'user',
message: 'Clicked checkout button',
level: 'info',
data: { userId: '123' },
});
```
## Global Exception Handling
### Set User Context
```typescript
import IronTelemetry, { useUnhandledExceptionHandler } from '@ironservices/telemetry';
IronTelemetry.init('your-dsn');
useUnhandledExceptionHandler();
```
This sets up handlers for:
- Browser: `window.onerror` and `unhandledrejection`
- Node.js: `uncaughtException` and `unhandledRejection`
## Helper Methods
```typescript
import { trackStep, trackStepAsync } from '@ironservices/telemetry';
// Track a step with automatic error handling
trackStep('Process Order', () => {
processOrder();
});
// Async version
await trackStepAsync('Fetch Data', async () => {
await fetchData();
});
// With return value
const result = trackStep('Calculate Total', () => {
return calculateTotal();
IronTelemetry.setUser({
id: 'user-123',
email: 'user@example.com',
name: 'John Doe',
});
```
## Flushing
## Framework Integrations
### Express.js
```typescript
// Flush pending events before app shutdown
await IronTelemetry.flush();
import express from 'express';
import IronTelemetry from '@ironservices/telemetry';
const app = express();
// Add error handler
app.use(IronTelemetry.express.errorHandler());
```
## TypeScript Support
This package is written in TypeScript and includes full type definitions:
### React
```typescript
import IronTelemetry, {
TelemetryOptions,
TelemetryEvent,
Breadcrumb,
SeverityLevel
} from '@ironservices/telemetry';
import { ErrorBoundary } from '@ironservices/telemetry/react';
function App() {
return (
<ErrorBoundary fallback={<ErrorPage />}>
<MyApp />
</ErrorBoundary>
);
}
```
## Browser Support
## Configuration Options
Works in all modern browsers (Chrome, Firefox, Safari, Edge) and Node.js 16+.
```typescript
IronTelemetry.init('https://pk_live_xxx@irontelemetry.com', {
environment: 'production',
release: '1.0.0',
sampleRate: 1.0,
beforeSend: (event) => {
// Filter or modify events
return event;
},
});
```
## Documentation
For complete documentation, visit [irontelemetry.com/docs](https://irontelemetry.com/docs).
## Other SDKs
| Platform | Package |
|----------|---------|
| .NET | [IronTelemetry.Client](https://git.marketally.com/ironservices/irontelemetry-dotnet) |
| Python | [irontelemetry](https://git.marketally.com/ironservices/irontelemetry-python) |
| Go | [irontelemetry-go](https://git.marketally.com/ironservices/irontelemetry-go) |
| Java | [irontelemetry-java](https://git.marketally.com/ironservices/irontelemetry-java) |
| Rust | [irontelemetry](https://git.marketally.com/ironservices/irontelemetry-rust) |
## Support
- **Documentation**: [irontelemetry.com/docs](https://irontelemetry.com/docs)
- **Email**: dev@ironservices.io
- **Issues**: [git.marketally.com/ironservices/irontelemetry-js/issues](https://git.marketally.com/ironservices/irontelemetry-js/issues)
## License