1k-sentry

Original source / Raw SKILL.md

---
name: 1k-sentry
description: Sentry error tracking and monitoring for OneKey. Use when configuring Sentry, filtering errors, analyzing crash reports, or debugging production issues. Covers platform-specific setup (desktop/mobile/web/extension) and error filtering strategies.
---

# Sentry Integration

OneKey uses Sentry for error tracking across all platforms.

## Architecture Overview

```
apps/
├── desktop/app/sentry.ts          # Desktop main process
├── ext/                           # Extension (uses shared)
├── mobile/                        # Mobile (uses shared)
└── web/                           # Web (uses shared)

packages/shared/src/modules3rdParty/sentry/
├── index.ts                       # Web/Extension entry
├── index.native.ts                # React Native entry
├── index.desktop.ts               # Desktop renderer entry
├── basicOptions.ts                # Shared config & error filtering
└── instance.ts                    # Sentry client instance
```

## Platform Detection

```typescript
import platformEnv from '@onekeyhq/shared/src/platformEnv';

platformEnv.isDesktop    // Electron desktop app
platformEnv.isNative     // React Native (iOS/Android)
platformEnv.isWeb        // Web browser
platformEnv.isExtension  // Browser extension
platformEnv.isWebEmbed   // Embedded web components
```

## Common Tasks

### Filter/Ignore Errors

See: [references/rules/ignoring-errors.md](references/rules/ignoring-errors.md)

Key file: `packages/shared/src/modules3rdParty/sentry/basicOptions.ts`

### Analyze Crash Reports

1. Get crash details from Sentry dashboard
2. Identify error type, message, and stack trace
3. Check platform-specific context
4. Use related skills for fixes:
   - Native crashes → `/1k-patching-native-modules`
   - JS errors → Fix in codebase

### Add Custom Context

```typescript
import * as Sentry from '@sentry/react-native'; // or @sentry/browser

// Add breadcrumb
Sentry.addBreadcrumb({
  category: 'action',
  message: 'User clicked button',
  level: 'info',
});

// Set user context
Sentry.setUser({ id: 'user-id' });

// Set tags
Sentry.setTag('feature', 'swap');

// Capture exception with context
Sentry.captureException(error, {
  extra: { additionalData: 'value' },
});
```

## Key Files

| Purpose | File |
|---------|------|
| Error filtering | `packages/shared/src/modules3rdParty/sentry/basicOptions.ts` |
| Desktop main | `apps/desktop/app/sentry.ts` |
| Desktop renderer | `packages/shared/src/modules3rdParty/sentry/index.desktop.ts` |
| Web/Extension | `packages/shared/src/modules3rdParty/sentry/index.ts` |
| Native | `packages/shared/src/modules3rdParty/sentry/index.native.ts` |

## Error Filtering Quick Reference

```typescript
// Filter by error type
const FILTERED_ERROR_TYPES = new Set(['AxiosError', 'HTTPClientError']);

// Filter by exact message
const FILTER_ERROR_VALUES = ['AbortError: AbortError'];

// Filter by pattern (in isFilterErrorAndSkipSentry function)
if (error.value?.includes('PATTERN')) return true;
```

## Related Skills

- `/1k-patching-native-modules` - Fix native crashes found in Sentry
- `/1k-coding-patterns` - Error handling best practices


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/rules/ignoring-errors.md

```markdown
# Ignoring Sentry Errors

Follow this workflow to add new error filters to Sentry configuration.

## Key File

All error filtering logic is centralized in:
```
packages/shared/src/modules3rdParty/sentry/basicOptions.ts
```

## Workflow

### 1) Analyze the error

Identify the error pattern:
- **Error type** (e.g., `Error`, `TypeError`, `AxiosError`)
- **Error message/value** (the text content)
- **Platform** (desktop/mobile/web/extension or all)
- **Frequency** (sporadic vs constant)
- **Impact** (blocks users or just noise)

### 2) Choose filtering strategy

**Option A: Filter by error type** (recommended for known error classes)

Add to `FILTERED_ERROR_TYPES` Set:
```typescript
const FILTERED_ERROR_TYPES = new Set([
  'AxiosError',
  'HTTPClientError',
  // Add your error type here
  'YourErrorType',
]);
```

**Option B: Filter by exact message match**

Add to `FILTER_ERROR_VALUES` array:
```typescript
const FILTER_ERROR_VALUES = ['AbortError: AbortError', 'cancel timeout'];
```

**Option C: Filter by partial message match** (for dynamic messages)

Add to `isFilterErrorAndSkipSentry` function:
```typescript
// Platform-specific filter (group with existing platform checks)
if (platformEnv.isDesktop && error.value) {
  if (error.value.includes('YOUR_ERROR_PATTERN')) {
    return true;
  }
}

// Cross-platform filter
if (error.value && error.value.includes('YOUR_ERROR_PATTERN')) {
  return true;
}
```

### 3) Implementation pattern

For platform-specific errors, group checks to minimize redundant conditions:

```typescript
// Desktop-specific error filters (grouped)
if (platformEnv.isDesktop && error.value) {
  // Filter 1
  if (error.value.includes('Pattern1')) {
    return true;
  }
  // Filter 2 (check shorter string first for performance)
  if (
    error.value.includes('ShortPattern') &&
    error.value.includes('LongerPatternForSpecificity')
  ) {
    return true;
  }
}
```

### 4) Verify changes

```bash
yarn eslint packages/shared/src/modules3rdParty/sentry/basicOptions.ts --quiet
```

## Best Practices

1. **Check shorter strings first** - Better performance for `includes()` chains
2. **Group platform checks** - Avoid redundant `platformEnv` evaluations
3. **Add comments** - Explain why the error is being filtered
4. **Preserve local logging** - Filtered errors still get logged via `onError` callback
5. **Be specific** - Use multiple `includes()` for dynamic messages to avoid false positives

## Example: Filtering Electron webview errors

```typescript
// Filter Electron webview connection closed error (network interruption during webview loading)
// Check shorter string first for better performance
if (
  error.value.includes('ERR_CONNECTION_CLOSED') &&
  error.value.includes('GUEST_VIEW_MANAGER_CALL')
) {
  return true;
}
```

```