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://sk_live_xxx@statly.live/your-org

2. Install an SDK

npm install @statly/observe

import { init, captureException } from '@statly/observe';
 
init({
  dsn: 'https://sk_live_xxx@statly.live/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://sk_live_xxx@statly.live/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: 'user@example.com',
  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.

Logs

Statly Observe includes a powerful structured logging system that captures application logs with full context. Logs are automatically correlated with sessions and traces.

Quick Start

import { Logger } from '@statly/observe';
 
const logger = Logger.create({
  dsn: 'https://sk_live_xxx@statly.live/your-org',
  environment: 'production',
});
 
logger.info('User logged in', { userId: '123' });
logger.error('Payment failed', { orderId: 'ord_456', error: 'Card declined' });

Log Levels

Sessions

Logs are automatically grouped into sessions. A session represents a user's interaction with your application:

const logger = Logger.create({
  dsn: '...',
  sessionId: 'session_abc123', // Auto-generated if not provided
  user: {
    id: 'user_123',
    email: 'jane@example.com',
  },
});

View sessions in the dashboard at Dashboard → Observe → Logs → Sessions.

Distributed Tracing

Correlate logs across services using trace IDs:

logger.info('Processing order', {
  orderId: 'ord_456'
}, { traceId: 'trace_xyz789' });

Secret Scrubbing

The logger automatically scrubs sensitive data before sending:

• API keys and tokens
• Passwords and secrets
• Credit card numbers
• Social security numbers
• Email addresses (optional)

Configure custom scrubbing patterns:

const logger = Logger.create({
  dsn: '...',
  scrubPatterns: [
    /my-custom-secret-[a-z0-9]+/gi,
    /internal-token-\d+/g,
  ],
});

Log Sampling

Control costs by sampling logs per level:

const logger = Logger.create({
  dsn: '...',
  sampleRates: {
    trace: 0.01,  // 1% of trace logs
    debug: 0.1,   // 10% of debug logs
    info: 0.5,    // 50% of info logs
    warn: 1.0,    // 100% of warnings
    error: 1.0,   // 100% of errors
    fatal: 1.0,   // 100% of fatal
  },
});

Log Dashboard

The Logs dashboard provides:

• Real-time log stream with infinite scrolling
• Filter by level: trace, debug, info, warn, error, fatal
• Filter by environment: production, staging, development
• Search by message or metadata
• Session grouping: View all logs from a user session
• Trace correlation: Link to distributed traces

Navigate to Dashboard → Observe → Logs to view your logs.

Usage & Limits

Data Retention

Events older than your retention period are automatically deleted.