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

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

If version is below 9.41.0, inform user to upgrade:

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:

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:

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:

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:

// 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:

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:

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+):

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

pip show sentry-sdk | grep Version

If version is below 2.35.0:

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:

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:

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)

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)

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)

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(
            sentry_logs_level=LoggingLevels.WARNING.value
        )
    ],
)

logger.warning("This goes to Sentry")

---

Ruby Platform

Minimum SDK Version

• sentry-ruby version 5.24.0+

Step 1: Verify SDK Version

bundle show sentry-ruby
# or
gem list sentry-ruby

If version is below 5.24.0:

# In Gemfile
gem "sentry-ruby", ">= 5.24.0"

Then run bundle update sentry-ruby

Step 2: Enable Logging in Init

Find Sentry.init block and add config.enable_logs = true.

Common locations:

• Rails: config/initializers/sentry.rb
• Sinatra/other: Entry point or config file

Modify init:

Sentry.init do |config|
  config.dsn = "YOUR_DSN_HERE"

  # Enable structured logging
  config.enable_logs = true

  # ... other existing config
end

Step 3: Setup Standard Logger Integration (Optional)

To capture Ruby's stdlib Logger:

Sentry.init do |config|
  config.dsn = "YOUR_DSN_HERE"
  config.enable_logs = true
  config.enabled_patches = [:logger]
end

Structured Logging Examples (Ruby)

# Basic logging
Sentry.logger.info("User logged in")

# With named parameters (become searchable attributes)
Sentry.logger.debug("Cache miss for user %{user_id}", user_id: 123)

Sentry.logger.error(
  "Payment failed. Order: %{order_id}. Amount: %{amount}",
  order_id: "order_456",
  amount: 99.99
)

# 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")

---

Framework-Specific Notes

Next.js

• Enable logging in ALL init files: instrumentation-client.ts, sentry.server.config.ts, sentry.edge.config.ts
• Console integration works on both client and server
• Use Sentry.logger from @sentry/nextjs

React (Browser)

• Enable logging in client init file only
• Console integration captures browser console calls
• Use Sentry.logger from @sentry/react

Node.js

• Pino, Winston, and Consola integrations available
• Console integration captures server-side console calls
• Use Sentry.logger from @sentry/node

Django

• Add logging config in settings.py
• LoggingIntegration captures Django's logging
• Extra fields in log records become Sentry attributes

Flask

• Add logging config where you initialize the app
• Works with Flask's built-in logging

Rails

• Add to config/initializers/sentry.rb
• Enable :logger patch for stdlib Logger capture

---

Verification Steps

After setup, provide these verification instructions:

JavaScript Verification

// Add this temporarily to test
Sentry.logger.info("Sentry logging test", {
  test: true,
  timestamp: new Date().toISOString(),
});

console.log("Console capture test"); // If console integration enabled

Python Verification

from sentry_sdk import logger as sentry_logger

sentry_logger.info("Sentry logging test", test=True)

import logging
logging.warning("Standard logging test")  # If LoggingIntegration enabled

Ruby Verification

Sentry.logger.info("Sentry logging test")

Tell user to check their Sentry dashboard under Logs section to verify logs are arriving.

---

Common Issues and Solutions

Issue: Logs not appearing in Sentry

Solutions:

1. Verify SDK version meets minimum requirements
2. Ensure enableLogs: true (JS) or enable_logs=True (Python/Ruby) is set
3. Check DSN is correct
4. Verify you're looking at the Logs section (not Issues)
5. Check log level filtering isn't too restrictive

Issue: Too many logs being sent

Solutions:

1. Use beforeSendLog / before_send_log to filter
2. Reduce log levels captured in console integration
3. Only enable logging where needed (e.g., just server-side)

Issue: Console integration not capturing logs

Solutions:

1. Ensure integration is added to integrations array
2. Verify desired levels are included in levels array
3. Check for conflicts with other logging libraries

Issue: SDK version too old

Solutions:

• JavaScript: npm install @sentry/nextjs@latest
• Python: pip install --upgrade sentry-sdk
• Ruby: bundle update sentry-ruby

---

Summary Checklist

Provide this checklist after setup:

## Sentry Logging Setup Complete

### Configuration Applied:
- [ ] SDK version verified (meets minimum requirements)
- [ ] `enableLogs` / `enable_logs` added to Sentry.init()
- [ ] Console integration added (if requested)
- [ ] Log filtering configured (if requested)
- [ ] Third-party logger integration added (if applicable)

### Sample Code Provided:
- [ ] Structured logging examples for your platform
- [ ] Verification test code

### Next Steps:
1. Run your application
2. Trigger some test logs
3. Check Sentry dashboard > Logs section
4. Adjust log levels and filtering as needed

---

Quick Reference

Platform	SDK Version	Enable Flag	Logger API
JavaScript	9.41.0+	enableLogs: true	Sentry.logger.*
Python	2.35.0+	enable_logs=True	sentry_sdk.logger.*
Ruby	5.24.0+	config.enable_logs = true	Sentry.logger.*

Log Level	JavaScript	Python	Ruby
Trace	trace()	trace()	trace()
Debug	debug()	debug()	debug()
Info	info()	info()	info()
Warning	warn()	warning()	warning()
Error	error()	error()	error()
Fatal	fatal()	fatal()	fatal()