Observe (Error Tracking)

Statly Observe captures errors, exceptions, and events from your applications. Track issues across your stack with SDKs for JavaScript, Python, and Go.

Getting Started

1. Get Your DSN

1. Go to Dashboard → Observe → Setup
2. Copy your DSN (Data Source Name):

https://[email protected]/your-org

2. Install an SDK

npm install @statly/observe

import { init, captureException } from '@statly/observe';
 
init({
  dsn: 'https://[email protected]/your-org',
  environment: 'production',
});
 
try {
  riskyOperation();
} catch (error) {
  captureException(error);
}

Dashboard

The Observe dashboard shows:

Issues List

• Fingerprint grouping: Similar errors are grouped together
• First/last seen: When the error first occurred and most recently
• Event count: Total occurrences
• User impact: Number of affected users

Issue Details

Click an issue to see:

• Full stack trace
• Breadcrumb trail (actions leading to the error)
• Request context (URL, headers, body)
• User context (id, email)
• Tags and extra data
• Release information

Filtering

Filter issues by:

• Environment (production, staging, development)
• Release version
• Status (unresolved, resolved, muted)
• Level (error, warning, info)
• Date range

Releases

Track which releases introduced errors:

Associating Errors with Releases

Set the release option when initializing the SDK:

init({
  dsn: '...',
  release: '1.2.3', // or process.env.GIT_SHA
});

Release Dashboard

View:

• Errors introduced in each release
• Regression detection (errors that reappear)
• Release health metrics

Source Maps

De-obfuscate minified JavaScript stack traces with source maps.

Why Source Maps?

Production JavaScript is typically minified:

Error at e.handleClick (main.abc123.js:1:2345)

With source maps, you see the original code:

Error at Button.handleClick (src/components/Button.tsx:45:12)

Uploading Source Maps

Option 1: CLI Upload

Use the statly-observe CLI to upload source maps after building:

# Install CLI
npm install -g @statly/observe
 
# Upload source maps
statly-observe sourcemaps upload \
  --dsn="https://[email protected]/your-org" \
  --release="1.2.3" \
  ./dist

Option 2: API Upload

Upload via the REST API:

curl -X POST "https://statly.live/api/v1/observe/sourcemaps" \
  -H "Authorization: Bearer sk_live_xxx" \
  -F "release=1.2.3" \
  -F "file=@./dist/main.js.map"

Option 3: Build Plugin

// webpack.config.js
const { StatlyWebpackPlugin } = require('@statly/observe/webpack');
 
module.exports = {
  plugins: [
    new StatlyWebpackPlugin({
      dsn: process.env.STATLY_DSN,
      release: process.env.GIT_SHA,
    }),
  ],
};

Source Map Requirements

• Source maps must be uploaded before errors occur
• The release value must match between SDK and upload
• File names in source maps must match the URLs in stack traces

Alert Rules

Trigger notifications when errors occur:

Rule Configuration

1. Go to Dashboard → Observe → Rules
2. Create a rule:
   • Name: e.g., "Critical Error Alert"
   • Conditions:
     • Error level (error, fatal)
     • Error count threshold
     • Time window
   • Actions: Which notification channels to use

Example Rules

User Context

Track which users are affected by errors:

import { setUser } from '@statly/observe';
 
// After user logs in
setUser({
  id: 'user_123',
  email: '[email protected]',
  username: 'johndoe',
});

User Impact Dashboard

• See how many users are affected by each issue
• Identify if errors are isolated or widespread
• Filter issues by specific users

Breadcrumbs

Breadcrumbs record the trail of events leading to an error:

import { addBreadcrumb } from '@statly/observe';
 
// Manual breadcrumb
addBreadcrumb({
  category: 'auth',
  message: 'User logged in',
  level: 'info',
});
 
// Automatic breadcrumbs captured:
// - Console logs
// - HTTP requests
// - UI clicks
// - Navigation

Viewing Breadcrumbs

In the issue details, breadcrumbs show the sequence of events:

12:00:00 - [navigation] User navigated to /checkout
12:00:05 - [http] POST /api/orders (200 OK)
12:00:06 - [ui] Clicked "Place Order" button
12:00:07 - [http] POST /api/payments (500 Error)
12:00:07 - [error] PaymentError: Card declined

Muting & Resolving

Muting Issues

Mute issues you're aware of but can't fix immediately:

1. Click the issue
2. Click Mute
3. Select duration or "Until further notice"

Muted issues won't trigger alerts.

Resolving Issues

Mark issues as resolved when fixed:

1. Click the issue
2. Click Resolve
3. Optionally select a release where it was fixed

If the error reoccurs, it will be automatically reopened.

Data Retention

Events older than your retention period are automatically deleted.