sentry-hello-world

What this skill does

# Sentry Hello World

## Overview

Send your first test events to Sentry — a captured message, a captured exception, and a fully-enriched error with user context, tags, and breadcrumbs — then verify each one appears in the Sentry dashboard. This skill covers both Node.js (`@sentry/node`) and Python (`sentry-sdk`).

## Prerequisites

- Completed `sentry-install-auth` setup (SDK installed, DSN configured)
- Valid `SENTRY_DSN` in environment variables
- `instrument.mjs` loaded before app code (Node.js) or `sentry_sdk.init()` called (Python)
- Network access to `*.ingest.sentry.io`

## Instructions

### Step 1 — Verify the SDK Is Active

Before sending test events, confirm the SDK initialized correctly. If `getClient()` returns `undefined`, the SDK was never initialized — go back to `sentry-install-auth`.

**TypeScript (Node.js):**

```typescript
import * as Sentry from '@sentry/node';

const client = Sentry.getClient();
if (!client) {
  console.error('Sentry SDK not initialized. Ensure instrument.mjs is loaded first.');
  console.error('Run with: node --import ./instrument.mjs your-script.mjs');
  process.exit(1);
}
console.log('Sentry SDK active — DSN configured');
```

**Python:**

```python
import sentry_sdk

client = sentry_sdk.Hub.current.client
if client is None or client.dsn is None:
    print("Sentry SDK not initialized. Call sentry_sdk.init() first.")
    exit(1)
print("Sentry SDK active — DSN configured")
```

### Step 2 — Capture a Test Message

`captureMessage` sends an informational event without a stack trace. Use it to verify basic connectivity between your app and Sentry.

**TypeScript:**

```typescript
import * as Sentry from '@sentry/node';

// captureMessage returns the event ID (a 32-char hex string)
const eventId = Sentry.captureMessage('Hello Sentry! SDK verification test.', 'info');
console.log(`Message sent — Event ID: ${eventId}`);

// Also test 'warning' level — appears with yellow indicator in dashboard
Sentry.captureMessage('Warning-level test message', 'warning');

// IMPORTANT: flush before process exits or events may be lost
await Sentry.flush(2000);
```

**Python:**

```python
import sentry_sdk

event_id = sentry_sdk.capture_message("Hello Sentry! SDK verification test.", level="info")
print(f"Message sent — Event ID: {event_id}")

sentry_sdk.capture_message("Warning-level test message", level="warning")

# Flush to ensure delivery before process exits
sentry_sdk.flush()
```

### Step 3 — Capture a Test Exception

`captureException` sends a full error with stack trace. Always pass an actual `Error` object (not a string) so Sentry generates a proper stack trace.

**TypeScript:**

```typescript
import * as Sentry from '@sentry/node';

try {
  throw new Error('Hello Sentry! This is a test exception.');
} catch (error) {
  const eventId = Sentry.captureException(error);
  console.log(`Exception sent — Event ID: ${eventId}`);
}

await Sentry.flush(2000);
```

**Python:**

```python
import sentry_sdk

try:
    raise ValueError("Hello Sentry! This is a test exception.")
except Exception as e:
    event_id = sentry_sdk.capture_exception(e)
    print(f"Exception sent — Event ID: {event_id}")

sentry_sdk.flush()
```

### Step 4 — Add User Context and Tags

Enrich events with identity and metadata so you can filter and search in the dashboard. `setUser` attaches to all subsequent events in the current scope. `setTag` creates indexed, searchable key-value pairs.

**TypeScript:**

```typescript
import * as Sentry from '@sentry/node';

// Attach user identity — appears in the "User" section of every event
Sentry.setUser({
  id: 'test-user-001',
  email: '[email protected]',
  username: 'developer',
});

// Tags are indexed and searchable — use for filtering in Issues view
Sentry.setTag('test_run', 'hello-world');
Sentry.setTag('team', 'platform');

// setContext adds structured data (not indexed, but visible in event detail)
Sentry.setContext('test_metadata', {
  ran_at: new Date().toISOString(),
  node_version: process.version,
  purpose: 'SDK verification',
});

// This event will carry user, tags, and context
Sentry.captureMessage('Test event with full context attached', 'info');

await Sentry.flush(2000);
```

**Python:**

```python
import sentry_sdk
from datetime import datetime, timezone
import sys

sentry_sdk.set_user({"id": "test-user-001", "email": "[email protected]", "username": "developer"})

sentry_sdk.set_tag("test_run", "hello-world")
sentry_sdk.set_tag("team", "platform")

sentry_sdk.set_context("test_metadata", {
    "ran_at": datetime.now(timezone.utc).isoformat(),
    "python_version": sys.version,
    "purpose": "SDK verification",
})

sentry_sdk.capture_message("Test event with full context attached", level="info")

sentry_sdk.flush()
```

### Step 5 — Add Breadcrumbs

Breadcrumbs record a trail of events leading up to an error. They appear in the event detail view, giving you the chronological context of what happened before the crash.

**TypeScript:**

```typescript
import * as Sentry from '@sentry/node';

Sentry.addBreadcrumb({
  category: 'auth',
  message: 'User authenticated successfully',
  level: 'info',
});

Sentry.addBreadcrumb({
  category: 'http',
  message: 'GET /api/users returned 200',
  level: 'info',
  data: { status_code: 200, url: '/api/users', method: 'GET' },
});

Sentry.addBreadcrumb({
  category: 'ui',
  message: 'User clicked "Submit Order" button',
  level: 'info',
});

// This exception will carry all three breadcrumbs above
try {
  throw new Error('Order processing failed — breadcrumb trail attached');
} catch (error) {
  Sentry.captureException(error);
}

await Sentry.flush(2000);
```

**Python:**

```python
import sentry_sdk

sentry_sdk.add_breadcrumb(category="auth", message="User authenticated successfully", level="info")
sentry_sdk.add_breadcrumb(category="http", message="GET /api/users returned 200", level="info",
                          data={"status_code": 200, "url": "/api/users"})
sentry_sdk.add_breadcrumb(category="ui", message="User clicked Submit Order button", level="info")

try:
    raise RuntimeError("Order processing failed — breadcrumb trail attached")
except Exception as e:
    sentry_sdk.capture_exception(e)

sentry_sdk.flush()
```

### Step 6 — Verify in the Sentry Dashboard

1. Open **https://sentry.io** and select your project
2. Navigate to the **Issues** tab — test errors appear as grouped issues
3. Click an issue to inspect the event detail:
   - **Stack Trace** — file path, line number, and surrounding code context
   - **User** section — `id`, `email`, `username` from `setUser()`
   - **Tags** sidebar — `test_run: hello-world`, `team: platform`
   - **Breadcrumbs** tab — chronological trail of events before the error
   - **Additional Data** — custom context from `setContext()`
4. Use the search bar to filter: `test_run:hello-world` narrows to your test events
5. Confirm **Environment** matches your `SENTRY_ENVIRONMENT` value
6. Confirm **Release** matches your `SENTRY_RELEASE` value (if set)
7. Delete test issues when done: select issues > **Resolve** or **Delete**

## Examples

### Complete Verification Script (TypeScript)

Save as `test-sentry.mjs` and run with `node --import ./instrument.mjs test-sentry.mjs` to exercise all capabilities at once.

```typescript
// Run with: node --import ./instrument.mjs test-sentry.mjs
import * as Sentry from '@sentry/node';

async function main() {
  console.log('--- Sentry Hello World Verification ---\n');

  // 1. Verify SDK
  const client = Sentry.getClient();
  if (!client) {
    console.error('ERROR: Sentry SDK not initialized.');
    console.error('Run with: node --import ./instrument.mjs test-sentry.mjs');
    process.exit(1);
  }
  console.log('[OK] Sentry SDK active');

  // 2. Set user context and tags
  Sentry.setUser({ id: 'test-001', email: '[email protected]', username: 'developer' });
  Sentry.setTag('test_run', 'hello-world');
  Sentry.setTag('environment', process.env.SENTRY_ENVIRONMENT || 'test');
  console