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
parent
e288eeeb9d
commit
88246a8509
233
README.md
233
README.md
|
|
@ -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>
|
||||||
|
|
||||||
[](https://www.npmjs.com/package/@ironservices/telemetry)
|
<p align="center">
|
||||||
[](https://opensource.org/licenses/MIT)
|
<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
|
## Installation
|
||||||
|
|
||||||
|
|
@ -17,15 +47,17 @@ pnpm add @ironservices/telemetry
|
||||||
|
|
||||||
## Quick Start
|
## Quick Start
|
||||||
|
|
||||||
### Basic Exception Capture
|
### Initialize the SDK
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import IronTelemetry from '@ironservices/telemetry';
|
import IronTelemetry from '@ironservices/telemetry';
|
||||||
|
|
||||||
// Initialize with your DSN
|
|
||||||
IronTelemetry.init('https://pk_live_xxx@irontelemetry.com');
|
IronTelemetry.init('https://pk_live_xxx@irontelemetry.com');
|
||||||
|
```
|
||||||
|
|
||||||
// Capture exceptions
|
### Capture Exceptions
|
||||||
|
|
||||||
|
```typescript
|
||||||
try {
|
try {
|
||||||
doSomething();
|
doSomething();
|
||||||
} catch (error) {
|
} catch (error) {
|
||||||
|
|
@ -41,151 +73,102 @@ try {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Journey Tracking
|
### Track User Journeys
|
||||||
|
|
||||||
Track user journeys to understand the context of errors:
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import IronTelemetry from '@ironservices/telemetry';
|
// Start a journey
|
||||||
|
const journey = IronTelemetry.startJourney('checkout', { userId: 'user-123' });
|
||||||
|
|
||||||
// Track a complete user journey
|
// Add steps
|
||||||
{
|
journey.step('add_to_cart', { productId: 'prod-456' });
|
||||||
using journey = IronTelemetry.startJourney('Checkout Flow');
|
journey.step('enter_shipping');
|
||||||
|
journey.step('enter_payment');
|
||||||
|
|
||||||
IronTelemetry.setUser('user-123', 'user@example.com');
|
// Complete or fail
|
||||||
|
journey.complete(); // or journey.fail('Payment declined');
|
||||||
{
|
|
||||||
using step = IronTelemetry.startStep('Validate Cart', 'business');
|
|
||||||
validateCart();
|
|
||||||
}
|
|
||||||
|
|
||||||
{
|
|
||||||
using step = IronTelemetry.startStep('Process Payment', 'business');
|
|
||||||
processPayment();
|
|
||||||
}
|
|
||||||
|
|
||||||
{
|
|
||||||
using step = IronTelemetry.startStep('Send Confirmation', 'notification');
|
|
||||||
sendConfirmationEmail();
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Any exceptions captured during the journey are automatically correlated.
|
### Add Breadcrumbs
|
||||||
|
|
||||||
## Configuration
|
|
||||||
|
|
||||||
```typescript
|
```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({
|
IronTelemetry.addBreadcrumb({
|
||||||
category: 'auth',
|
category: 'user',
|
||||||
message: 'User logged in',
|
message: 'Clicked checkout button',
|
||||||
level: 'info',
|
level: 'info',
|
||||||
data: { userId: '123' },
|
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
## Global Exception Handling
|
### Set User Context
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import IronTelemetry, { useUnhandledExceptionHandler } from '@ironservices/telemetry';
|
IronTelemetry.setUser({
|
||||||
|
id: 'user-123',
|
||||||
IronTelemetry.init('your-dsn');
|
email: 'user@example.com',
|
||||||
useUnhandledExceptionHandler();
|
name: 'John Doe',
|
||||||
```
|
|
||||||
|
|
||||||
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();
|
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
## Flushing
|
## Framework Integrations
|
||||||
|
|
||||||
|
### Express.js
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
// Flush pending events before app shutdown
|
import express from 'express';
|
||||||
await IronTelemetry.flush();
|
import IronTelemetry from '@ironservices/telemetry';
|
||||||
|
|
||||||
|
const app = express();
|
||||||
|
|
||||||
|
// Add error handler
|
||||||
|
app.use(IronTelemetry.express.errorHandler());
|
||||||
```
|
```
|
||||||
|
|
||||||
## TypeScript Support
|
### React
|
||||||
|
|
||||||
This package is written in TypeScript and includes full type definitions:
|
|
||||||
|
|
||||||
```typescript
|
```typescript
|
||||||
import IronTelemetry, {
|
import { ErrorBoundary } from '@ironservices/telemetry/react';
|
||||||
TelemetryOptions,
|
|
||||||
TelemetryEvent,
|
function App() {
|
||||||
Breadcrumb,
|
return (
|
||||||
SeverityLevel
|
<ErrorBoundary fallback={<ErrorPage />}>
|
||||||
} from '@ironservices/telemetry';
|
<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
|
## License
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue