Crash Detection

Learn how to configure Sentry crash reporting in S2-Launcher to capture crash dumps, logs, and plugin call breadcrumbs.

S2-Launcher ships with built-in Sentry integration for crash detection and reporting. When enabled, it automatically sends crash dumps to your Sentry backend, along with logs and a full callstack of any plugin calls captured as breadcrumbs. By default, Sentry is disabled and must be opted into by editing the sentry.jsonc configuration file.

Configuration

The sentry.jsonc file is located alongside the crashpad-handler executable:

  • Windows: bin/win64/sentry.jsonc
  • Linux: bin/linuxsteamrt64/sentry.jsonc

Open the file and make the following changes to enable crash reporting.

Enable Sentry

Set "enabled" to true:

"enabled": true

Set Your DSN

Replace the placeholder DSN with your own project's DSN from sentry.io. You can find this under Project Settings → Client Keys (DSN):

"dsn": "https://your-sentry-dsn@sentry.io/your-project-id"

What Gets Reported

Once enabled, Sentry will capture the following for each crash:

  • Crash dumps: Full minidump files sent to your Sentry project, viewable in the Issues dashboard.
  • Logs: Session logs from the path configured in logs_path.
  • Plugin call breadcrumbs: The callstack of any plugin function calls leading up to the crash, recorded as Sentry breadcrumbs. This makes it easy to trace which plugin triggered a fault.

Full Configuration Reference

Below is the complete sentry.jsonc with all available options. Required fields are at the top; advanced options are commented out and can be uncommented as needed.

{
  // Required: Sentry DSN (Data Source Name)
  "dsn": "https://your-sentry-dsn@sentry.io/your-project-id",

  // Required: Directory paths
  "database_path": "../../${S2_GAME_NAME}/addons/plugify/crashes",
  "logs_path": "../../${S2_GAME_NAME}/addons/plugify/logs/sessions",

  // Basic release identification
  "environment": "production",
  "release": "${S2_VERSION}",

  // Custom tags
  "tags": {
    "product": "${PROJECT_DESCRIPTION}",
    "version": "${S2_VERSION}",
    "game": "${S2_GAME_NAME}"
  },

  // Custom attachments
  "attachments": [],

  // Sampling rate (0.0 to 1.0)
  "sample_rate": 1.0,

  // Debug and logging
  "debug": false,
  "listen_console": false,

  // Enable/disable Sentry
  "enabled": false,

  // Advanced options (uncomment to use):

  // Release distribution identifier
  // "dist": "",

  // Network configuration
  // "proxy": "",
  // "ca_certs": "",
  // "transport_thread_name": "",

  // Custom handler path (defaults to crashpad_handler if not specified)
  // "handler_path": "",

  // Tracing sample rate (0.0 to 1.0)
  // "traces_sample_rate": 0.0,

  // Limits
  // "max_breadcrumbs": 100,
  // "max_spans": 1000,
  // "shutdown_timeout": 2000,

  // Logging options
  // "enable_logging_when_crashed": true,
  // "logger_level": "debug",

  // Session tracking
  "auto_session_tracking": true,
  // "require_user_consent": false,

  // Stack trace processing
  "symbolize_stacktraces": true,

  // Crash reporter options
  // "system_crash_reporter_enabled": false,
  // "crashpad_wait_for_upload": false,
  // "crashpad_limit_stack_capture_to_sp": false,

  // Additional features
  // "attach_screenshot": false,
  // "propagate_traceparent": false,

  // Logging integration
  // "enable_logs": false,
  // "logs_with_attributes": false,
  // "logs_with_breadcrumbs": false
}

Key Options Explained

OptionDefaultDescription
enabledfalseMaster switch. Must be true for any reporting to occur.
dsn(placeholder)Your Sentry project DSN. Required for sending events.
database_path(game-relative)Where crash dumps are stored locally before upload.
logs_path(game-relative)Session log files attached to crash reports.
sample_rate1.0Fraction of events to send (1.0 = 100%). Lower to reduce volume.
symbolize_stacktracestrueResolves raw addresses into function names in stack traces.
auto_session_trackingtrueTracks session health (crashed vs. healthy) in Sentry.
debugfalseEnables verbose Sentry SDK output for troubleshooting.
logs_with_breadcrumbsfalseIncludes plugins callstack output in breadcrumbs.

Troubleshooting

  1. Crashes not appearing in Sentry:
    • Confirm "enabled": true is set in sentry.jsonc.
    • Verify the DSN is correct and the project exists on sentry.io.
    • Check that crashpad_handler.exe (Windows) or crashpad_handler (Linux) is present in the same directory as the launcher.
  2. Breadcrumbs missing:
    • Plugin calls are only recorded if the plugin manager was loaded before the crash. Ensure Plugify initialized successfully (plg --version in console).
  3. Local crash dumps not being written:
    • Verify the process has write permissions to the database_path directory.
    • The directory is created automatically, but the parent path must exist.
Edit this page on GitHub
Updating
Learn how to update Plugify and apply patches to maintain compatibility with game updates.
Profiling
Learn how to enable and use the built-in Tracy profiler to measure performance across plugins and language modules.