sentry-setup-logging

What this skill does

# SOURCE: getsentry/sentry-for-claude
# PATH: skills/sentry-setup-logging/SKILL.md
# DO NOT EDIT: This file is synced from external source


# Setup Sentry Logging

This skill helps configure Sentry's structured logging feature across multiple platforms and frameworks.

## When to Use This Skill

Invoke this skill when:
- User asks to "setup Sentry logging" or "add Sentry logs"
- User wants to "capture console logs in Sentry"
- User requests "structured logging with Sentry"
- User mentions they want to send logs to Sentry
- User asks about `Sentry.logger` or `sentry_sdk.logger`
- User wants to integrate their existing logging library with Sentry

## Platform Detection

Before configuring, detect the project's platform:

### JavaScript/TypeScript Detection
Check for these files:
- `package.json` - Read to identify framework and Sentry SDK version
- Look for `@sentry/nextjs`, `@sentry/react`, `@sentry/node`, `@sentry/browser`, etc.
- Check if SDK version is 9.41.0+ (required for logging)

### Python Detection
Check for:
- `requirements.txt`, `pyproject.toml`, `setup.py`, or `Pipfile`
- Look for `sentry-sdk` version 2.35.0+ (required for logging)

### Ruby Detection
Check for:
- `Gemfile` or `*.gemspec`
- Look for `sentry-ruby` gem version 5.24.0+ (required for logging)

## Required Information

Ask the user:

```
I'll help you set up Sentry Logging. First, let me check your project setup.

After detecting the platform, I need to know:

1. **Logging approach** - Which setup do you prefer?
   - Console Integration: Automatically capture existing console.log/print statements
   - Structured Logging: Use Sentry.logger for new structured log calls
   - Both: Set up both approaches

2. **Log levels** (optional): Which levels should be captured?
   - Default: info, warn, error
   - All: trace, debug, info, warn, error, fatal
```

## Configuration by Platform

---

## JavaScript/TypeScript Platforms

### Minimum SDK Versions
- All JS platforms: `9.41.0+`
- Consola integration: `10.12.0+`

### Step 1: Verify SDK Version

```bash
grep -E '"@sentry/(nextjs|react|node|browser)"' package.json
```

If version is below 9.41.0, inform user to upgrade:
```bash
npm install @sentry/nextjs@latest  # or appropriate package
```

### Step 2: Enable Logging in Init

Find the Sentry.init() call and add `enableLogs: true`.

**Locate init files:**
- Next.js: `instrumentation-client.ts`, `sentry.server.config.ts`, `sentry.edge.config.ts`
- React: `src/index.tsx`, `src/main.tsx`, or dedicated sentry config file
- Node.js: Entry point file or dedicated sentry config
- Browser: Entry point or config file

**Modify init:**

```javascript
import * as Sentry from "@sentry/nextjs"; // or @sentry/react, @sentry/node, etc.

Sentry.init({
  dsn: "YOUR_DSN_HERE",

  // Enable structured logging
  enableLogs: true,

  // ... other existing config
});
```

### Step 3: Setup Console Integration (Optional)

If user wants console log capture, add the integration:

```javascript
import * as Sentry from "@sentry/nextjs";

Sentry.init({
  dsn: "YOUR_DSN_HERE",
  enableLogs: true,

  integrations: [
    Sentry.consoleLoggingIntegration({
      levels: ["log", "warn", "error"] // Customize as needed
    }),
  ],
});
```

**Available console levels:** `debug`, `info`, `warn`, `error`, `log`, `assert`, `trace`

### Step 4: Setup Log Filtering (Optional)

If user wants to filter logs before sending:

```javascript
Sentry.init({
  dsn: "YOUR_DSN_HERE",
  enableLogs: true,

  beforeSendLog: (log) => {
    // Drop info-level logs
    if (log.level === "info") {
      return null;
    }
    // Modify or pass through
    return log;
  },
});
```

### Structured Logging Examples (JavaScript)

Provide these examples to the user:

```javascript
// Basic logging with attributes
Sentry.logger.info("User logged in", {
  userId: "user_123",
  method: "oauth",
});

Sentry.logger.error("Payment failed", {
  orderId: "order_456",
  amount: 99.99,
  currency: "USD",
});

// Template literal formatting (creates searchable attributes)
Sentry.logger.info(
  Sentry.logger.fmt`User '${user.name}' purchased '${product.name}'`
);

// All available log levels
Sentry.logger.trace("Detailed trace info");
Sentry.logger.debug("Debug information");
Sentry.logger.info("Informational message");
Sentry.logger.warn("Warning message");
Sentry.logger.error("Error occurred");
Sentry.logger.fatal("Fatal error - application cannot continue");
```

### Third-Party Logger Integrations (JavaScript)

**Pino Integration:**
```javascript
import * as Sentry from "@sentry/node";
import pino from "pino";

Sentry.init({
  dsn: "YOUR_DSN_HERE",
  enableLogs: true,
  integrations: [Sentry.pinoIntegration()],
});

const logger = pino();
logger.info("This goes to Sentry");
```

**Winston Integration:**
```javascript
import * as Sentry from "@sentry/node";
import winston from "winston";

Sentry.init({
  dsn: "YOUR_DSN_HERE",
  enableLogs: true,
});

const sentryTransport = Sentry.createSentryWinstonTransport();
const logger = winston.createLogger({
  transports: [sentryTransport],
});
```

**Consola Integration (SDK 10.12.0+):**
```javascript
import * as Sentry from "@sentry/node";
import { consola } from "consola";

Sentry.init({
  dsn: "YOUR_DSN_HERE",
  enableLogs: true,
});

const sentryReporter = Sentry.createConsolaReporter({
  levels: ["error", "warn", "info"],
});
consola.addReporter(sentryReporter);
```

---

## Python Platform

### Minimum SDK Version
- `sentry-sdk` version `2.35.0+`

### Step 1: Verify SDK Version

```bash
pip show sentry-sdk | grep Version
```

If version is below 2.35.0:
```bash
pip install --upgrade sentry-sdk
```

### Step 2: Enable Logging in Init

Find `sentry_sdk.init()` and add `enable_logs=True`.

**Common locations:**
- Django: `settings.py`
- Flask: `app.py` or `__init__.py`
- FastAPI: `main.py`
- General: Entry point or dedicated config file

**Modify init:**

```python
import sentry_sdk

sentry_sdk.init(
    dsn="YOUR_DSN_HERE",

    # Enable structured logging
    enable_logs=True,

    # ... other existing config
)
```

### Step 3: Setup Standard Library Logging Integration (Optional)

To capture Python's stdlib logging:

```python
import logging
import sentry_sdk
from sentry_sdk.integrations.logging import LoggingIntegration

sentry_sdk.init(
    dsn="YOUR_DSN_HERE",
    enable_logs=True,
    integrations=[
        LoggingIntegration(
            sentry_logs_level=logging.WARNING  # Capture WARNING and above
        )
    ],
)
```

**Available levels:** `logging.DEBUG`, `logging.INFO`, `logging.WARNING`, `logging.ERROR`, `logging.CRITICAL`

### Step 4: Setup Log Filtering (Optional)

```python
def before_send_log(log, hint):
    # Drop info-level logs
    if log["severity_text"] == "info":
        return None
    return log

sentry_sdk.init(
    dsn="YOUR_DSN_HERE",
    enable_logs=True,
    before_send_log=before_send_log,
)
```

### Structured Logging Examples (Python)

```python
from sentry_sdk import logger as sentry_logger

# Basic logging with placeholder syntax
sentry_logger.info("User logged in: {user_id}", user_id="user_123")

sentry_logger.error(
    "Payment failed. Order: {order_id}. Amount: {amount}",
    order_id="order_456",
    amount=99.99
)

# Using attributes kwarg for additional context
sentry_logger.warning(
    "Rate limit approaching",
    attributes={
        "endpoint": "/api/users",
        "current_rate": 95,
        "limit": 100,
    }
)

# All available log levels
sentry_logger.trace("Detailed trace info")
sentry_logger.debug("Debug information")
sentry_logger.info("Informational message")
sentry_logger.warning("Warning message")
sentry_logger.error("Error occurred")
sentry_logger.fatal("Fatal error")
```

### Loguru Integration (Python)

```python
import sentry_sdk
from sentry_sdk.integrations.loguru import LoguruIntegration, LoggingLevels
from loguru import logger

sentry_sdk.init(
    dsn="YOUR_DSN_HERE",
    enable_logs=True,
    integrations=[
        LoguruIntegration(