diff --git a/.travis.yml b/.travis.yml index abd644651041c..50da0b99c4bad 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,7 +1,7 @@ sudo: false language: ruby rvm: - - 2.3.6 + - 2.5.1 node_js: - "node" cache: diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000000000..2fe185fd9c99f --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,4 @@ +{ + "editor.trimAutoWhitespace": false, + "files.trimTrailingWhitespace": false, +} \ No newline at end of file diff --git a/Gemfile b/Gemfile index 89499d9585965..d053c06a1b51d 100644 --- a/Gemfile +++ b/Gemfile @@ -1,6 +1,7 @@ source "https://rubygems.org" gem "jekyll", "3.8.2" +gem "nokogiri", "1.8.3" # If you have any plugins, put them here! group :jekyll_plugins do diff --git a/Gemfile.lock b/Gemfile.lock index 6271a6ec22ffd..7e6c46854df52 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -108,6 +108,7 @@ DEPENDENCIES jekyll-assets (= 3.0.11) jekyll-extlinks liquid-md5 + nokogiri (= 1.8.3) sprockets (~> 4.0.beta) terminal-notifier tzinfo-data diff --git a/_config.yml b/_config.yml index 003362abd1c20..5cd019964d585 100644 --- a/_config.yml +++ b/_config.yml @@ -7,6 +7,7 @@ baseurl: '' url: 'https://docs.sentry.io' twitter_username: getsentry home_url: https://sentry.io +release_service: https://release-registry.services.sentry.io # Build settings port: 9000 diff --git a/bin/build-with-platform-api b/bin/build-with-platform-api new file mode 100755 index 0000000000000..dd1f3f9181e76 --- /dev/null +++ b/bin/build-with-platform-api @@ -0,0 +1,6 @@ +#!/bin/bash +# usage: bin/build-with-platform-api +# +# Run the jekyll server + +bundle exec jekyll build --config _config.yml,_config.dev.yml $@ diff --git a/bin/server b/bin/server index b27622d8c8185..7d3938e756457 100755 --- a/bin/server +++ b/bin/server @@ -24,8 +24,8 @@ else echo "🐇 - Jekyll is running with the --incremental flag" fi - export JEKYLL_DISABLE_PLATFORM_API=${JEKYLL_DISABLE_PLATFORM_API:-true} - if [ "$JEKYLL_DISABLE_PLATFORM_API" = true ]; then + export JEKYLL_ENABLE_PLATFORM_API=${JEKYLL_ENABLE_PLATFORM_API:-false} + if [ "$JEKYLL_ENABLE_PLATFORM_API" = false ]; then echo "🐇 - Platform API generation (docs.sentry.io/_platforms) is disabled" fi @@ -41,4 +41,4 @@ rm -rf .jekyll-cache yarn (bundle check || bundle install) -./bin/webpack-watch & ./bin/jekyll-watch +./bin/webpack-watch & ./bin/jekyll-watch diff --git a/nginx.conf b/nginx.conf index 6f4f96fca0a2b..ceb0a0b651eb9 100644 --- a/nginx.conf +++ b/nginx.conf @@ -15,6 +15,26 @@ server { rewrite ^/(?:hosted|on-premise)/(.*)$ /$1$is_args$args redirect; + location = /clients/electron/ { + return 302 /platforms/javascript/electron/$is_args$args; + } + + location = /clients/rust/ { + return 302 /platforms/rust/$is_args$args; + } + + location = /clients/cordova/ { + return 302 /platforms/javascript/cordova/$is_args$args; + } + + location = /clients/minidump/ { + return 302 /platforms/minidump/$is_args$args; + } + + location = /learn/(data-forwarding|issue-owners|membership|notifications|pricing|sso|search|quotas)/ { + return 302 /product/$1/$is_args$args; + } + location = /clients/javascript/integrations/angular2/ { return 302 /clients/javascript/integrations/angular/$is_args$args; } diff --git a/src/_assets/css/_includes/index.scss b/src/_assets/css/_includes/index.scss new file mode 100644 index 0000000000000..996988b4da7a9 --- /dev/null +++ b/src/_assets/css/_includes/index.scss @@ -0,0 +1,11 @@ +.index-illustration { + float: right; + margin: 0 0 30px 30px; + width: 260px; + + img { + border: none; + box-shadow: none; + border-radius: 0; + } +} diff --git a/src/_assets/css/_includes/platform-specific-content.scss b/src/_assets/css/_includes/platform-specific-content.scss index 02d4552493aab..94f917c8bb469 100644 --- a/src/_assets/css/_includes/platform-specific-content.scss +++ b/src/_assets/css/_includes/platform-specific-content.scss @@ -5,3 +5,20 @@ display: block; } } + +.unsupported { + .unsupported-hint { + display: none; + } +} + +.unsupported.is-unsupported { + opacity: 0.5; + + .unsupported-hint { + display: block; + font-size: 0.9rem; + font-weight: bold; + margin-bottom: 0.3rem; + } +} diff --git a/src/_assets/css/_includes/type.scss b/src/_assets/css/_includes/type.scss index 538011274851b..6ff6890d9add0 100644 --- a/src/_assets/css/_includes/type.scss +++ b/src/_assets/css/_includes/type.scss @@ -60,6 +60,12 @@ } } +// Config keys +h3.config-key { + font-family: $font-family-monospace; + font-size: 1.3rem; +} + // Remove the bottom margin from the final direct child. // // Example: diff --git a/src/_assets/css/screen.scss b/src/_assets/css/screen.scss index d38606ec988fb..19d3e30fe19ce 100644 --- a/src/_assets/css/screen.scss +++ b/src/_assets/css/screen.scss @@ -21,3 +21,4 @@ @import '_includes/tracking-widget'; @import '_includes/loader'; @import '_includes/platform-link'; +@import '_includes/index'; diff --git a/src/_assets/img/on-fire.png b/src/_assets/img/on-fire.png new file mode 100644 index 0000000000000..48976a1c89397 Binary files /dev/null and b/src/_assets/img/on-fire.png differ diff --git a/src/_data/LEGACY_platform_icons.yml b/src/_data/LEGACY_platform_icons.yml index 4025c55f8e1c4..185114a16f134 100644 --- a/src/_data/LEGACY_platform_icons.yml +++ b/src/_data/LEGACY_platform_icons.yml @@ -7,41 +7,9 @@ - name: Node.js link: _documentation/clients/node/index.md platformicon: nodejs -- name: Electron - link: _documentation/clients/electron/index.md - platformicon: electron -- name: React Native - link: _documentation/clients/react-native/index.md - platformicon: react -- name: PHP - link: _documentation/clients/php/index.md - platformicon: php -- name: Ruby - link: _documentation/clients/ruby/index.md - platformicon: ruby -- name: Cocoa - link: _documentation/clients/cocoa/index.md - platformicon: apple -- name: Java - link: _documentation/clients/java/index.md - platformicon: java -- name: 'C#' - link: _documentation/clients/csharp/index.md - platformicon: csharp -- name: Rust - link: _documentation/clients/rust/index.md - platformicon: rust -- name: Go - link: _documentation/clients/go/index.md - platformicon: go -- name: Elixir - link: _documentation/clients/elixir/index.md - platformicon: elixir - name: Perl link: _documentation/clients/perl/index.md platformicon: perl -- name: Cordova - link: _documentation/clients/cordova/index.md - platformicon: cordova -- name: Minidump - link: _documentation/clients/minidump/index.md +- name: C# + link: _documentation/clients/csharp/index.md + platformicon: csharp diff --git a/src/_data/documentation_categories.yml b/src/_data/documentation_categories.yml index f6b39ff58aaf3..0fc2e867ddf16 100644 --- a/src/_data/documentation_categories.yml +++ b/src/_data/documentation_categories.yml @@ -7,14 +7,24 @@ slug: learn - title: Platforms - slug: clients + slug: platforms + +- title: Product Guides + slug: product - title: Integrations slug: integrations +- title: Legacy Clients + slug: clients + hide_when_inactive: true + - title: On-Premise slug: server +- title: Relay + slug: relay + - title: 'API Reference' slug: api diff --git a/src/_data/platform_icons.yml b/src/_data/platform_icons.yml new file mode 100644 index 0000000000000..365e35ce0767c --- /dev/null +++ b/src/_data/platform_icons.yml @@ -0,0 +1,95 @@ +- name: JavaScript + link: _documentation/platforms/javascript/index.md + platformicon: javascript + +- name: Browser JavaScript CDN + link: _documentation/platforms/javascript/browser.md + platformicon: javascript + +- name: Java + link: _documentation/clients/java/index.md + platformicon: java + +- name: Node.js + link: _documentation/platforms/javascript/node.md + platformicon: nodejs + +- name: .NET + link: _documentation/platforms/dotnet/index.md + platformicon: csharp + +- name: PHP + link: _documentation/clients/php/index.md + platformicon: php + +- name: Ruby + link: _documentation/clients/ruby/index.md + platformicon: ruby + +- name: Vue + link: _documentation/platforms/javascript/vue.md + platformicon: vue + +- name: Angular + link: _documentation/platforms/javascript/angular.md + platformicon: angularjs + +- name: Ember + link: _documentation/platforms/javascript/ember.md + platformicon: ember + +- name: React + link: _documentation/platforms/javascript/react.md + platformicon: react + +- name: React Native + link: _documentation/clients/react-native/index.md + platformicon: react + +- name: Cordova + link: _documentation/platforms/javascript/cordova.md + platformicon: cordova + +- name: Electron + link: _documentation/platforms/javascript/electron/index.md + platformicon: electron + +- name: Python + link: _documentation/platforms/python/index.md + platformicon: python + +- name: Django + link: _documentation/platforms/python/django.md + platformicon: django + +- name: Flask + link: _documentation/platforms/python/flask.md + platformicon: flask + +- name: Celery + link: _documentation/platforms/python/celery.md + platformicon: python + +- name: Rust + link: _documentation/platforms/rust/index.md + platformicon: rust + +- name: actix-web + link: _documentation/platforms/rust/actix.md + platformicon: rust + +- name: Minidump + link: _documentation/platforms/minidump/index.md + platformicon: generic + +- name: Elixir + link: _documentation/clients/elixir/index.md + platformicon: elixir + +- name: Cocoa + link: _documentation/clients/cocoa/index.md + platformicon: apple + +- name: Go + link: _documentation/clients/go/index.md + platformicon: go diff --git a/src/_data/platforms.yml b/src/_data/platforms.yml index 866aff419f121..81458aaeedf12 100644 --- a/src/_data/platforms.yml +++ b/src/_data/platforms.yml @@ -3,173 +3,277 @@ support_level: production type: framework name: Koa - doc_link: /clients/node/integrations/koa/ - wizard: ['_documentation/clients/node/index.md#installation', _documentation/clients/node/integrations/koa.md] + doc_link: /platforms/javascript/koa/ + wizard_parent: node + wizard: + - _documentation/platforms/javascript/koa.md - slug: node support_level: production type: language name: Node.js + wizard_parent: node + wizard: true + case_style: camelCase + fallback_platform: javascript +- + slug: node-legacy + support_level: production + type: language + name: Node.js doc_link: /clients/node/ - wizard: ['_documentation/clients/node/index.md#installation', '_documentation/clients/node/index.md#configuring-the-client', '_documentation/clients/node/index.md#reporting-errors'] + case_style: camelCase + fallback_platform: javascript + superseded_by: node - slug: express support_level: production type: framework name: Express - doc_link: /clients/node/integrations/express/ - wizard: ['_documentation/clients/node/index.md#installation', _documentation/clients/node/integrations/express.md] + doc_link: /platforms/javascript/express/ + wizard_parent: node + wizard: + - _documentation/platforms/javascript/express.md - slug: connect support_level: production type: framework name: Connect - doc_link: /clients/node/integrations/connect/ - wizard: ['_documentation/clients/node/index.md#installation', _documentation/clients/node/integrations/connect.md] + doc_link: /platforms/javascript/connect/ + wizard_parent: node + wizard: + - _documentation/platforms/javascript/connect.md - slug: cordova support_level: production type: language name: Cordova - doc_link: /clients/cordova/ - wizard: ['_documentation/clients/cordova/index.md#installation', '_documentation/clients/cordova/index.md#configuration'] + wizard_parent: cordova + wizard: true + case_style: camelCase + fallback_platform: javascript +- + slug: aspnetcore + support_level: production + type: framework + name: ASP.NET Core + wizard_parent: csharp + wizard: true + fallback_platform: csharp - slug: java support_level: production type: language name: Java doc_link: /clients/java/ - wizard: ['_documentation/clients/java/usage.md#installation', '_documentation/clients/java/usage.md#capture-an-error'] + wizard_parent: java + wizard: + - _documentation/clients/java/usage.md - slug: logging support_level: production type: framework name: java.util.logging doc_link: /clients/java/modules/jul/ - wizard: ['_documentation/clients/java/modules/jul.md#installation', '_documentation/clients/java/modules/jul.md#usage'] + wizard_parent: java + wizard: + - _documentation/clients/java/modules/jul.md - slug: logback support_level: production type: framework name: Logback doc_link: /clients/java/modules/logback/ - wizard: ['_documentation/clients/java/modules/logback.md#installation', '_documentation/clients/java/modules/logback.md#usage'] + wizard_parent: java + wizard: + - _documentation/clients/java/modules/logback.md - slug: android support_level: production type: framework name: Android doc_link: /clients/java/modules/android/ - wizard: ['_documentation/clients/java/modules/android.md#installation', '_documentation/clients/java/modules/android.md#usage'] + wizard_parent: java + wizard: + - _documentation/clients/java/modules/android.md - slug: log4j2 support_level: production type: framework name: 'Log4j 2.x' doc_link: /clients/java/modules/log4j2/ - wizard: ['_documentation/clients/java/modules/log4j2.md#installation', '_documentation/clients/java/modules/log4j2.md#usage'] + wizard_parent: java + wizard: + - _documentation/clients/java/modules/log4j2.md - slug: log4j support_level: production type: framework name: 'Log4j 1.x' doc_link: /clients/java/modules/log4j/ - wizard: ['_documentation/clients/java/modules/log4j.md#installation', '_documentation/clients/java/modules/log4j.md#usage'] + wizard_parent: java + wizard: + - _documentation/clients/java/modules/log4j.md - slug: appengine support_level: production type: framework name: 'Google App Engine' doc_link: /clients/java/modules/appengine/ - wizard: ['_documentation/clients/java/modules/appengine.md#installation', '_documentation/clients/java/modules/appengine.md#usage'] + wizard_parent: java + wizard: + - _documentation/clients/java/modules/appengine.md - slug: python support_level: production type: language name: Python + wizard_parent: python + wizard: true + case_style: snake_case +- + slug: python-legacy + support_level: production + type: language + name: Python Legacy doc_link: /clients/python/ - wizard: ['_documentation/clients/python/index.md#installation', '_documentation/clients/python/usage.md#capture-an-error', '_documentation/clients/python/usage.md#reporting-an-event'] + case_style: snake_case + superseded_by: python - slug: pyramid support_level: production type: framework name: Pyramid doc_link: /clients/python/integrations/pyramid/ - wizard: ['_documentation/clients/python/index.md#installation', '_documentation/clients/python/integrations/pyramid.md#pastedeploy-filter', '_documentation/clients/python/integrations/pyramid.md#logger-setup'] + wizard_parent: python + wizard: + - _documentation/clients/python/index.md + - _documentation/clients/python/integrations/pyramid.md + case_style: camelCase - slug: rq support_level: production type: framework name: RQ doc_link: /clients/python/integrations/rq/ - wizard: ['_documentation/clients/python/index.md#installation', '_documentation/clients/python/integrations/rq.md#usage', '_documentation/clients/python/integrations/rq.md#extended-setup'] + wizard_parent: python + wizard: + - _documentation/clients/python/index.md + - _documentation/clients/python/integrations/rq.md - slug: flask support_level: production type: framework name: Flask - doc_link: /clients/python/integrations/flask/ - wizard: ['_documentation/clients/python/index.md#installation', '_documentation/clients/python/integrations/flask.md#installation', '_documentation/clients/python/integrations/flask.md#setup'] + doc_link: /platforms/python/flask/ + wizard_parent: python + wizard: + - _documentation/platforms/python/flask.md - slug: django support_level: production type: framework name: Django - doc_link: /clients/python/integrations/django/ - wizard: ['_documentation/clients/python/index.md#installation', '_documentation/clients/python/integrations/django.md#setup'] + doc_link: /platforms/python/django/ + wizard_parent: python + wizard: + - _documentation/platforms/python/django.md - slug: celery support_level: production type: library name: Celery - doc_link: /clients/python/integrations/celery/ - wizard: ['_documentation/clients/python/index.md#installation', _documentation/clients/python/integrations/celery.md] + doc_link: /platforms/python/celery/ + wizard_parent: python + wizard: + - _documentation/platforms/python/celery.md - slug: tornado support_level: production type: framework name: Tornado doc_link: /clients/python/integrations/tornado/ - wizard: ['_documentation/clients/python/index.md#installation', '_documentation/clients/python/integrations/tornado.md#setup', '_documentation/clients/python/integrations/tornado.md#usage'] + wizard_parent: python + wizard: + - _documentation/clients/python/index.md + - _documentation/clients/python/integrations/tornado.md - slug: bottle support_level: production type: framework name: Bottle doc_link: /clients/python/integrations/bottle/ - wizard: ['_documentation/clients/python/index.md#installation', '_documentation/clients/python/integrations/bottle.md#setup', '_documentation/clients/python/integrations/bottle.md#usage'] + wizard_parent: python + wizard: + - _documentation/clients/python/index.md + - _documentation/clients/python/integrations/bottle.md - slug: pylons support_level: production type: framework name: Pylons doc_link: /clients/python/integrations/pylons/ - wizard: ['_documentation/clients/python/index.md#installation', '_documentation/clients/python/integrations/pylons.md#wsgi-middleware', '_documentation/clients/python/integrations/pylons.md#logger-setup'] + wizard_parent: python + wizard: + - _documentation/clients/python/index.md + - _documentation/clients/python/integrations/pylons.md - slug: swift support_level: production type: language name: Swift doc_link: /clients/cocoa/ - wizard: ['_documentation/clients/cocoa/index.md#installation', '_documentation/clients/cocoa/index.md#configuration', '_documentation/clients/cocoa/index.md#debug-symbols', '_documentation/clients/cocoa/dsym.md#upload-symbols-with-sentry-cli'] + wizard_parent: cocoa + wizard: + - _documentation/clients/cocoa/index.md + - _documentation/clients/cocoa/dsym.md version: 4.1.0 version_key: SENTRY_COCOA_TAG +- + slug: browser + support_level: production + type: language + name: Browser Javascript + wizard_parent: javascript + wizard: true + case_style: camelCase + fallback_platform: javascript + +- + slug: browsernpm + support_level: production + type: language + name: Browser Javascript NPM + doc_link: /clients/javascript/ + case_style: camelCase + fallback_platform: javascript - slug: javascript support_level: production type: language + wizard_parent: javascript + wizard: true + name: JavaScript + case_style: camelCase +- + slug: javascript-legacy + support_level: production + type: language name: JavaScript doc_link: /clients/javascript/ - wizard: ['_documentation/clients/javascript/index.md#installation', '_documentation/clients/javascript/index.md#configuring-the-client', '_documentation/clients/javascript/index.md#manually-reporting-errors'] version: 3.26.4 version_key: RAVEN_VERSION + case_style: camelCase + superseded_by: browser - slug: vue support_level: production type: framework name: Vue - doc_link: /clients/javascript/integrations/vue/ - wizard: ['_documentation/clients/javascript/integrations/vue.md#installation'] + doc_link: /platforms/javascript/vue/ + wizard_parent: javascript + wizard: + - _documentation/platforms/javascript/vue.md version: 3.26.4 version_key: RAVEN_VERSION - @@ -178,7 +282,9 @@ type: framework name: Backbone doc_link: /clients/javascript/integrations/backbone/ - wizard: ['_documentation/clients/javascript/integrations/backbone.md#installation', '_documentation/clients/javascript/integrations/backbone.md#configuring-the-client'] + wizard_parent: javascript + wizard: + - _documentation/clients/javascript/integrations/backbone.md version: 3.26.4 version_key: RAVEN_VERSION - @@ -186,8 +292,10 @@ support_level: production type: framework name: Ember - doc_link: /clients/javascript/integrations/ember/ - wizard: ['_documentation/clients/javascript/integrations/ember.md#installation'] + doc_link: /platforms/javascript/ember/ + wizard_parent: javascript + wizard: + - _documentation/platforms/javascript/ember.md version: 3.26.4 version_key: RAVEN_VERSION - @@ -195,8 +303,10 @@ support_level: production type: framework name: React - doc_link: /clients/javascript/integrations/react/ - wizard: ['_documentation/clients/javascript/integrations/react.md#installation', '_documentation/clients/javascript/integrations/react.md#configuring-the-client'] + doc_link: /platforms/javascript/react/ + wizard_parent: javascript + wizard: + - _documentation/platforms/javascript/react.md version: 3.26.4 version_key: RAVEN_VERSION - @@ -205,7 +315,9 @@ type: framework name: AngularJS doc_link: /clients/javascript/integrations/angularjs/ - wizard: ['_documentation/clients/javascript/integrations/angularjs.md#installation', '_documentation/clients/javascript/integrations/angularjs.md#angularjs-configuration'] + wizard_parent: javascript + wizard: + - _documentation/clients/javascript/integrations/angularjs.md version: 3.26.4 version_key: RAVEN_VERSION - @@ -213,8 +325,10 @@ support_level: production type: framework name: Angular - doc_link: /clients/javascript/integrations/angular/ - wizard: ['_documentation/clients/javascript/integrations/angular.md#installation', '_documentation/clients/javascript/integrations/angular.md#configuration'] + doc_link: /platforms/javascript/angular/ + wizard_parent: javascript + wizard: + - _documentation/platforms/javascript/angular.md version: 3.26.4 version_key: RAVEN_VERSION - @@ -222,114 +336,157 @@ support_level: production type: language name: Electron - doc_link: /clients/electron/ - wizard: ['_documentation/clients/electron/index.md#installation', '_documentation/clients/electron/index.md#configuring-the-client'] + wizard_parent: electron + wizard: true + case_style: camelCase + fallback_platform: javascript - slug: elixir support_level: production type: language name: Elixir doc_link: /clients/elixir/ - wizard: ['_documentation/clients/elixir/index.md#installation', '_documentation/clients/elixir/index.md#configuration', '_documentation/clients/elixir/usage.md#capturing-errors'] + wizard_parent: elixir + wizard: + - _documentation/clients/elixir/index.md + - _documentation/clients/elixir/usage.md + case_style: PascalCase - slug: cocoa support_level: beta type: language name: React-Native doc_link: /clients/react-native/ - wizard: ['_documentation/clients/react-native/index.md#installation', '_documentation/clients/react-native/index.md#client-configuration'] + wizard_parent: react-native + wizard: + - _documentation/clients/react-native/index.md - slug: objc support_level: production type: language name: Objective-C doc_link: /clients/cocoa/ - wizard: ['_documentation/clients/cocoa/index.md#installation', '_documentation/clients/cocoa/index.md#configuration', '_documentation/clients/cocoa/index.md#debug-symbols', '_documentation/clients/cocoa/dsym.md#upload-symbols-with-sentry-cli'] + wizard_parent: cocoa + wizard: + - _documentation/clients/cocoa/index.md + - _documentation/clients/cocoa/dsym.md version: 4.1.0 version_key: SENTRY_COCOA_TAG - slug: csharp + support_level: production + type: language + name: 'C#' + wizard_parent: csharp + wizard: true + case_style: PascalCase +- + slug: csharp-legacy support_level: community type: language name: 'C#' doc_link: /clients/csharp/ - wizard: ['_documentation/clients/csharp/index.md#installation', '_documentation/clients/csharp/index.md#capturing-exceptions'] + case_style: PascalCase + superseded_by: csharp - slug: go support_level: in-development type: language name: Go doc_link: /clients/go/ - wizard: ['_documentation/clients/go/index.md#installation', '_documentation/clients/go/index.md#configuring-the-client', '_documentation/clients/go/index.md#reporting-errors', '_documentation/clients/go/index.md#reporting-panics'] + wizard_parent: go + wizard: + - _documentation/clients/go/index.md - slug: http support_level: in-development type: framework name: net/http doc_link: /clients/go/integrations/http/ - wizard: ['_documentation/clients/go/integrations/http.md#installation', '_documentation/clients/go/integrations/http.md#setup'] + wizard_parent: go + wizard: + - _documentation/clients/go/integrations/http.md - slug: laravel support_level: production type: framework name: Laravel doc_link: /clients/php/integrations/laravel/ - wizard: ['_documentation/clients/php/integrations/laravel.md#laravel-5-x', '_documentation/clients/php/integrations/laravel.md#laravel-4-x', '_documentation/clients/php/integrations/laravel.md#lumen-5-x'] + wizard_parent: php + wizard: + - _documentation/clients/php/integrations/laravel.md - slug: php support_level: production type: language name: PHP doc_link: /clients/php/ - wizard: ['_documentation/clients/php/index.md#installation', '_documentation/clients/php/index.md#configuration', '_documentation/clients/php/usage.md#capturing-errors'] + wizard_parent: php + wizard: + - _documentation/clients/php/index.md + - _documentation/clients/php/usage.md - slug: monolog support_level: production type: framework name: Monolog doc_link: /clients/php/integrations/monolog/ - wizard: ['_documentation/clients/php/index.md#installation', _documentation/clients/php/integrations/monolog.md] + wizard_parent: php + wizard: + - _documentation/clients/php/index.md#installation + - _documentation/clients/php/integrations/monolog.md - slug: symfony2 support_level: production type: framework name: Symfony2 doc_link: /clients/php/integrations/symfony2/ - wizard: ['_documentation/clients/php/integrations/symfony2.md#symfony-2'] + wizard_parent: php + wizard: + - _documentation/clients/php/integrations/symfony2.md - slug: ruby support_level: production type: language name: Ruby doc_link: /clients/ruby/ - wizard: ['_documentation/clients/ruby/index.md#installation', '_documentation/clients/ruby/index.md#configuration', '_documentation/clients/ruby/index.md#reporting-failures'] + wizard_parent: ruby + wizard: + - _documentation/clients/ruby/index.md - slug: rack support_level: production type: framework name: Rack doc_link: /clients/ruby/integrations/rack/ - wizard: [_documentation/clients/ruby/integrations/rack.md] + wizard_parent: ruby + wizard: + - _documentation/clients/ruby/integrations/rack.md - slug: rails support_level: production type: framework name: Rails doc_link: /clients/ruby/integrations/rails/ - wizard: [_documentation/clients/ruby/integrations/rails.md] + wizard_parent: ruby + wizard: + - _documentation/clients/ruby/integrations/rails.md - slug: rust support_level: production type: language name: Rust - doc_link: /clients/rust/ - wizard: ['_documentation/clients/rust/index.md#installation', '_documentation/clients/rust/index.md#configuring-the-client', '_documentation/clients/rust/index.md#reporting-errors', '_documentation/clients/rust/index.md#catching-panics'] + wizard_parent: rust + wizard: true version: 0.6.0 version_key: SENTRY_VERSION + case_style: snake_case - slug: minidump support_level: production type: language name: Minidump - doc_link: /clients/minidump/ - wizard: ['_documentation/clients/minidump/index.md#platform-and-language-support', '_documentation/clients/minidump/index.md#creating-and-uploading-minidumps'] + doc_link: /platforms/minidump/ + wizard_parent: minidump + wizard: + - _documentation/platforms/minidump/index.md diff --git a/src/_includes/breadcrumbs.html b/src/_includes/breadcrumbs.html index 5bc081b42a524..f5e7b1544fc09 100644 --- a/src/_includes/breadcrumbs.html +++ b/src/_includes/breadcrumbs.html @@ -14,6 +14,23 @@ | where: "url", __url | first -%} + {%- assign __next_segment = __path[forloop.index] %} + {%- if __next_segment %} + {%- assign __next_url = __url | append: __next_segment | append: '/' %} + {%- assign __next_page = site.pages | concat: site.documentation + | where: "url", __next_url + | first + -%} + {%- else %} + {%- assign __next_page = page %} + {%- endif %} + {%- if __next_page and __next_page.sidebar_relocation %} + {%- assign __relocation_url = __slugs | pop | push: __next_page.sidebar_relocation | join: '/' | append: '/' %} + {%- assign __page = site.pages | concat: site.documentation + | where: "url", __relocation_url + | first + -%} + {%- endif %} {%- if __page -%}
  • {{ __page.breadcrumb | default: __page.title }}
    • {%- else -%} diff --git a/src/_includes/components/config_key.html b/src/_includes/components/config_key.html new file mode 100644 index 0000000000000..0fae5dd6553c5 --- /dev/null +++ b/src/_includes/components/config_key.html @@ -0,0 +1 @@ +{{ include.key }} diff --git a/src/_includes/components/platform_content.html b/src/_includes/components/platform_content.html index d7d3dec837324..c80edcf092d83 100644 --- a/src/_includes/components/platform_content.html +++ b/src/_includes/components/platform_content.html @@ -58,7 +58,7 @@
    - @@ -76,6 +76,7 @@ -%} {{ __platform.name }} {%- endfor -%} + Platform not listed?
    @@ -96,8 +97,8 @@ {%- capture __content -%} {% include_relative {{ __relative_path }} %} {%- endcapture -%} -
    - {{ __content | liquify | markdownify }} +
    + {{ __content | markdownify }}
    {%- endfor -%}
    diff --git a/src/_includes/head.html b/src/_includes/head.html index f12d453f40e20..762b12d1005f1 100644 --- a/src/_includes/head.html +++ b/src/_includes/head.html @@ -35,8 +35,10 @@ {% asset screen.css %} diff --git a/src/_includes/learn-sdk.md b/src/_includes/learn-sdk.md new file mode 100644 index 0000000000000..48d5164db3343 --- /dev/null +++ b/src/_includes/learn-sdk.md @@ -0,0 +1,8 @@ +{% capture __alert_content -%} +This page will provide you with details that are very specific to the platform, to learn how to use our unified +SDKs in general, please visit the [Learn section]({%- link _documentation/learn/quickstart.md -%}?platform={{ include.platform }}) +{%- endcapture -%} +{%- include components/alert.html + title="Learn about SDK usage" + content=__alert_content +%} \ No newline at end of file diff --git a/src/_includes/platform_icon_links.html b/src/_includes/platform_icon_links.html new file mode 100644 index 0000000000000..0dbbeb54e375a --- /dev/null +++ b/src/_includes/platform_icon_links.html @@ -0,0 +1,17 @@ +
    +
    + {%- for platform in site.data.platform_icons -%} + {% capture dynamic_link %}{% raw %}{% link {% endraw %}{{ platform.link }}{% raw %} %}{% endraw %}{% endcapture %} +
    + +
    + {%- include svg/platforms/{{ platform.platformicon | default: "generic" }}.svg -%} +
    +
    +

    {{ platform.name }}

    +
    +     +
    + {%- endfor -%} +
    +
    diff --git a/src/_includes/sidebar.html b/src/_includes/sidebar.html index 6e55c06d3bd45..803996c72d0f8 100644 --- a/src/_includes/sidebar.html +++ b/src/_includes/sidebar.html @@ -15,15 +15,9 @@ -%} {%- assign __tree = __collection.items -%} -{%- if page.collection -%} - {%- assign __page_category = page.path | split: '/' | slice: 1,1 | first -%} -{%- else -%} - {%- assign __page_category = site.document_tree[0].items[0].slug -%} -{%- endif -%} - {% include sidebar/tree.html data=__tree - templates="LEGACY_category,default" + templates="category,default" categories=site.data.documentation_categories is_category=true %} diff --git a/src/_includes/sidebar/LEGACY_category.html b/src/_includes/sidebar/LEGACY_category.html deleted file mode 100644 index 236dbcaf99a80..0000000000000 --- a/src/_includes/sidebar/LEGACY_category.html +++ /dev/null @@ -1,17 +0,0 @@ -{%- assign __category = include.categories - | where: 'slug', include.slug - | first --%} -{%- if include.document -%} - -
    - {{- __category.title -}} -
    -     -{%- else -%} -
    -
    - {{- __category.title -}} -
    -
    -{%- endif -%} diff --git a/src/_includes/sidebar/category.html b/src/_includes/sidebar/category.html index ce6c2e42f24c8..236dbcaf99a80 100644 --- a/src/_includes/sidebar/category.html +++ b/src/_includes/sidebar/category.html @@ -3,16 +3,14 @@ | first -%} {%- if include.document -%} - - {% include /svg/{{ __category.icon }}.svg %} -
    + +
    {{- __category.title -}}
    {%- else -%} -
    - {% include /svg/{{ __category.icon }}.svg %} -
    +
    +
    {{- __category.title -}}
    diff --git a/src/_includes/sidebar/tree.html b/src/_includes/sidebar/tree.html index 6329f3288453f..28ac007cab443 100644 --- a/src/_includes/sidebar/tree.html +++ b/src/_includes/sidebar/tree.html @@ -4,7 +4,15 @@ {%- assign __CONTEXT_items_at_current_depth = __items_at_current_depth -%}
      {%- for __item in include.data -%} -
    • +
    • {%- include sidebar/preserve_context.html -%} {%- assign __template_list = include.templates @@ -25,8 +33,6 @@ categories=include.categories -%} - {%- assign __item_category = __item.parent_path | split: '/' | slice: 1,1 | first -%} - {%- assign __new_template_list_length = __template_list.size | minus: 1 -%} diff --git a/src/_js/lib/PlatformContent.js b/src/_js/lib/PlatformContent.js index 1f782c9e29bb6..6ac616ea2c8de 100644 --- a/src/_js/lib/PlatformContent.js +++ b/src/_js/lib/PlatformContent.js @@ -1,23 +1,38 @@ import qs from 'query-string'; +const DEFAULT_PLATFORM = 'javascript'; const KEY = 'preferredPlatform'; -// Get the object associated with a given platform slug. +// Platform display priority: // -// slug - slug matching a platform in data/platforms.yml +// - `platform` in url +// - `preferredPlatform` in localStorage +// - default platform // -// Returns an object or null if no platform matches the slug. -const verifyPlatformSlug = function(slug) { - return window.supportedPlatforms.find(x => x === slug); +// `preferredPlatform` will update when: +// +// - `platform` in url is specified +// - A new platform is selected in the UI +// +// platform displayed may be forced by: +// +// - setting the `platform` in the url + +// Get the slug for the platform that should be displayed +// +// Returns a String. +const getPlatformSlug = function() { + return localStorage.getItem(KEY) || DEFAULT_PLATFORM; }; -// Update the url of hte page to reflect a current slug +// Get the object associated with a given platform slug. // // slug - slug matching a platform in data/platforms.yml // -// Returns nothing. -const updateLocationPlatform = function(slug) { - history.replaceState({}, '', updateUrlPlatform(location.href, slug)); +// Returns an object or null if no platform matches the slug. +const verifyPlatformSlug = function(slug) { + if (!slug) return false; + return window.supportedPlatforms.find(x => x === slug); }; // Add or update the platform slug of a url @@ -32,6 +47,43 @@ const updateUrlPlatform = function(url, slug) { return `${origin}?${qs.stringify(query)}`; }; +const syncRelatedElements = function() { + let platform = window.platformData[window.activePlatform]; + let style = platform && platform.case_style || 'canonical'; + + $('.config-key').each(function() { + let canonical = this.getAttribute('data-config-key'); + let intended = canonical; + switch (style) { + case 'snake_case': intended = canonical.replace(/-/g, '_'); break; + case 'camelCase': intended = canonical.split(/-/g).map((val, idx) => + idx == 0 ? val : val.charAt(0).toUpperCase() + val.substr(1) + ).join(''); break; + case 'PascalCase': intended = canonical.split(/-/g).map((val) => + val.charAt(0).toUpperCase() + val.substr(1) + ).join(''); break; + } + let elements = $(this).children(); + $(this).text(intended).prepend(elements); + }); + + $('.unsupported').each(function() { + let slugs = this.getAttribute('data-unsupported-platforms'); + let inverse = false; + if (!slugs) { + slugs = this.getAttribute('data-supported-platforms'); + inverse = true; + } + slugs = slugs.split(/\s+/g); + if ((slugs.indexOf(window.activePlatform) >= 0) != inverse) { + $(this).addClass('is-unsupported'); + $('div.unsupported-hint', this).text(`Not available for ${platform.name || 'this platform'}.`); + } else { + $(this).removeClass('is-unsupported'); + } + }); +}; + // Update UI state to show content for a given platform. If the platform does // not exist, // @@ -39,21 +91,35 @@ const updateUrlPlatform = function(url, slug) { // // Returns nothing. const showPlatform = function(slug) { - if (!verifyPlatformSlug(slug)) return; + if (verifyPlatformSlug(slug)) localStorage.setItem(KEY, slug); + slug = getPlatformSlug(); + + window.activePlatform = slug; + let platform = window.platformData[window.activePlatform]; $('[data-platform-specific-content]').each((i, el) => { const $block = $(el); - const $dropdownItems = $block.find('[data-toggle="platform"]'); - const $requested = $dropdownItems.filter(`[data-platform="${slug}"]`); - const $preferred = $dropdownItems.filter( - `[data-platform="${localStorage.getItem(KEY)}"]` - ); - let $active = $requested; + let $dropdownItems = $block.find('[data-toggle="platform"]'); + let $preferred = $dropdownItems.filter(`[data-platform="${slug}"]`); + let $active; + + const slugs = [slug, platform.fallback_platform]; + + for (const index in slugs) { + $active = $dropdownItems.filter(`[data-platform="${slugs[index]}"]`); + if ($active.length) { + if (index > 0) { // means we are in fallback platform + $active.data('platform', platform.slug); // But if we click on it we want to keep our inital platform + } + // We skip and don't use fallback platform + break; + } + } if (!$active.length) { $active = $preferred.length ? $preferred : $dropdownItems.eq(0); } - // Updat the active state of the dropdown items + // Update the active state of the dropdown items $dropdownItems.removeClass('active'); $dropdownItems.attr('aria-selected', false); $active.addClass('active'); @@ -68,49 +134,40 @@ const showPlatform = function(slug) { $activePane.addClass('show active'); // Update dropdown target title - $block.find('[data-toggle="dropdown"]').text($active.text()); + $block.find('[data-platform-switcher-target]').text($active.text()); }); -}; -// Add the current platform to all links on the page. -// -// slug - slug matching a platform in data/platforms.yml -// -// Returns nothing. -const addPlatformToLinks = function(slug) { - const validSlug = verifyPlatformSlug(slug); - if (!validSlug) return; - - $('a').each((i, el) => { - const $el = $(el); - const href = $el.attr('href'); - const isDocLink = /(^\/|docs.sentry.io)/.test(href); - if (isDocLink) $el.attr('href', updateUrlPlatform(href, validSlug)); - }); -}; + history.replaceState({}, '', updateUrlPlatform(location.href, slug)); -// Attach event listeners and set UI state based on the platform supplied via -// query param, stored in localStorage as the preferred platform, or the -// default platform, in that order. -// -// Returns nothing. -const init = function() { - $(document).on('click', '[data-toggle="platform"]', function(event) { - event.preventDefault(); - const $target = $(event.target); - const slug = $target.data('platform'); - localStorage.setItem(KEY, slug); - showPlatform(slug); - addPlatformToLinks(slug); - updateLocationPlatform(slug); + $('.config-key').each(function() { + if (!this.getAttribute('data-config-key')) { + this.setAttribute('data-config-key', $(this).text().trim()); + } }); - $(document).on('page.didUpdate', function(event) { - const queryPlatform = qs.parse(location.search).platform; - const preferredPlatform = localStorage.getItem(KEY); - showPlatform(queryPlatform || preferredPlatform); - addPlatformToLinks(queryPlatform); + $('.unsupported-hint').remove(); + $('.unsupported').each(function() { + $('
      ').prependTo(this); }); + + syncRelatedElements(); }; -export default { init }; +$(document).on('click', 'a[href^="?platform="]', function(event) { + event.preventDefault(); + const { query } = qs.parseUrl(this.href); + showPlatform(query.platform); +}); + +$(document).on('click', '[data-toggle="platform"]', function(event) { + event.preventDefault(); + showPlatform($(event.target).data('platform')); +}); + +$(document).on('page.didUpdate', function(event) { + // cameron help me. why do i need to do this -- mitsuhiko + $('a[href^="?platform"]').attr('data-not-dynamic', '1'); + + // Update the preferredPlatform based on the url. + showPlatform(qs.parse(location.search).platform); +}); diff --git a/src/_js/lib/Sidebar.js b/src/_js/lib/Sidebar.js index 2e916217bc20c..25e5e32b15079 100644 --- a/src/_js/lib/Sidebar.js +++ b/src/_js/lib/Sidebar.js @@ -1,35 +1,40 @@ -const filterDepth = depth => { - return (i, el) => { - const $parents = $(el).parentsUntil( - '[data-sidebar-root]', - '[data-sidebar-tree]' - ); - return $parents.length === depth; - }; -}; - $(document).on('page.didUpdate', function(event) { const $links = $('[data-sidebar-link]'); - let $active = $links.filter(`[href="${location.pathname}"]`); - const $categoryTree = $('[data-sidebar-tree]').filter(filterDepth(1)); - $active = !!$active.length - ? $active - : $categoryTree.first().siblings('[data-sidebar-link]'); + const $sections = $('[data-sidebar-root] > [data-sidebar-tree]').find( + '> [data-sidebar-branch]' + ); + + let $active = $links.filter(`[href="${location.pathname}"]`).last(); + + if (!$active.length) { + $active = $sections + .first() + .find('> [data-sidebar-tree]') + .find('> [data-sidebar-branch]') + .first() + .find('> [data-sidebar-link]'); + } $links.each((i, el) => { const $el = $(el); $el.toggleClass('active', $el.is($active)); }); - const $sectionTree = $('[data-sidebar-tree]').filter(filterDepth(0)); + $('[data-sidebar-branch]').each((i, el) => { + const $branch = $(el); + const $parentBranch = $branch + .parent() + .closest('[data-sidebar-branch],[data-sidebar-root]'); + const hideWhenNoActiveChild = + $branch.data('hide-when-inactive') !== undefined; + const parentTreeContainsActive = $parentBranch + .find('[data-sidebar-link]') + .is($active); - const $trees = $('[data-sidebar-tree]'); - $trees.each((i, el) => { - const $el = $(el); - const containsActive = !!$el.has($active.get(0)).length; - const isChildOfActive = $el.parent().is($active.parent()); - const isSection = $sectionTree.is($el); - const leaveVisble = containsActive || isChildOfActive || isSection; - $el.toggleClass('collapse', !leaveVisble); + const containsActive = $branch.find('[data-sidebar-link]').is($active); + + const leaveVisble = + containsActive || (parentTreeContainsActive && !hideWhenNoActiveChild); + $branch.toggleClass('collapse', !leaveVisble); }); }); diff --git a/src/_js/lib/User.js b/src/_js/lib/User.js index 21ebd33f97a57..e40f4132e4e33 100644 --- a/src/_js/lib/User.js +++ b/src/_js/lib/User.js @@ -98,7 +98,7 @@ const constructDSNObject = function(project = {}) { id: project.id || -1, group: escape(project.organizationName) || 'Example', PROJECT_NAME: escape(project.name) || 'Your Project', - PROJECT_ID: escape(project.projectSlug) || 'your-project', + PROJECT_ID: escape(project.projectSlug) || '<project-id>', ORG_NAME: escape(project.organizationSlug) || 'your-org', DSN: formatDsn(dsn, { public: false }), PUBLIC_DSN: formatDsn(dsn, { public: true }), diff --git a/src/_js/main.js b/src/_js/main.js index 07d6a7a640718..1d8d1d835f0a9 100644 --- a/src/_js/main.js +++ b/src/_js/main.js @@ -1,11 +1,11 @@ import Raven from 'raven-js'; import 'bootstrap'; -import PlatformContent from './lib/PlatformContent'; import UserContent from './lib/UserContent'; import Tracking from './lib/Tracking'; import User from './lib/User'; import DynamicLoad from './lib/DynamicLoad'; import Search from './lib/Search'; +import './lib/PlatformContent'; import './lib/HeaderLinker'; import './lib/Feedback'; import './lib/Sidebar'; @@ -24,7 +24,6 @@ $(document).on('page.didUpdate', function(event) { }); $(function() { - PlatformContent.init(); UserContent.init(); Tracking.init(); Search.init(); diff --git a/src/_layouts/doc.html b/src/_layouts/doc.html index 5e2798b5f4cb1..08d78547d2e20 100644 --- a/src/_layouts/doc.html +++ b/src/_layouts/doc.html @@ -26,6 +26,38 @@
      + {%- assign __is_active = page.url | url_starts_with: "/relay" %} + {%- if __is_active %} + {% capture __alert_content -%} + Relay is currently in alpha. Not all functionality is currently available and + the user experience did not receive the necessary polishing yet. + {%- endcapture -%} + {%- include components/alert.html + level="warning" + title="Alpha Functionality" + content=__alert_content + %} + {%- endif %} + + {%- for platform in site.data.platforms -%} + {%- if platform.superseded_by %} + {%- assign __is_active = page.url | url_starts_with: platform.doc_link %} + {%- if __is_active %} + {%- assign __new_platform = site.data.platforms | where: 'slug', platform.superseded_by | first %} + {% capture __alert_content -%} + This SDK has been superseded by a new unified one. The documentation here is + preserved for customers using the old client. For new projects have a look + at the new client documentation: + Unified {{ __new_platform.name }} SDK. + {%- endcapture -%} + {%- include components/alert.html + level="info" + title="Deprecated Client" + content=__alert_content + %} + {%- endif %} + {%- endif %} + {%- endfor %}

      {{ page.title }}

      diff --git a/src/_layouts/json.json b/src/_layouts/json.json deleted file mode 100644 index 342ae716a7ed6..0000000000000 --- a/src/_layouts/json.json +++ /dev/null @@ -1 +0,0 @@ -{{ page.json | jsonify }} diff --git a/src/_plugins/case_variations.rb b/src/_plugins/case_variations.rb new file mode 100644 index 0000000000000..5688fa6bafa7d --- /dev/null +++ b/src/_plugins/case_variations.rb @@ -0,0 +1,31 @@ +module Jekyll + class CaseVariationsTag < Liquid::Tag + + def initialize(tag_name, key, options) + super + @key = key + end + + def render_variation(variation, value) + %Q( + #{value} + ) + end + + def render(context) + parts = @key.split(/-/) + snake_case = @key.gsub('-', '_') + camel_case = parts.each_with_index { |val, idx| + idx == 0 ? val : val.capitalize! + }.join('') + pascal_case = parts.map { |v| v.capitalize }.join('') + [ + render_variation("canonical", @key), + render_variation("snake_case", snake_case), + render_variation("camelCase", camel_case), + render_variation("PascalCase", pascal_case), + ].join("\n") + end + end +end +Liquid::Template.register_tag('case_variations'.freeze, Jekyll::CaseVariationsTag) diff --git a/src/_plugins/document_path_tree.rb b/src/_plugins/document_path_tree.rb index 700bd2698e4e3..f0335494aeb7b 100644 --- a/src/_plugins/document_path_tree.rb +++ b/src/_plugins/document_path_tree.rb @@ -1,6 +1,5 @@ - Jekyll::Hooks.register :site, :pre_render, priority: :low do |site| - def treeFor(docs, root) + def tree_for(docs, root) tree = [] groups = docs.group_by do |doc| @@ -24,7 +23,7 @@ def treeFor(docs, root) docs_without_index = docs_for_group.reject {|doc| doc.path.include? "#{new_root}index." } - items = new_root.nil? ? nil : treeFor(docs_without_index, new_root) + items = new_root.nil? ? nil : tree_for(docs_without_index, new_root) if !items.nil? items.sort_by! do |i| @@ -49,10 +48,33 @@ def treeFor(docs, root) tree end - mapped = site.collections.map {|c| c[1].docs} documents = mapped.flatten() - tree = treeFor(documents, "") + tree = tree_for(documents, "") + + # relocate some items + def adjacent_move(item, stack) + # TODO: we might have to support direct parent as well + parent = stack[stack.size - 2] + if !parent.nil? && !item["document"].nil? + other_sidebar = item["document"].data["sidebar_relocation"] + if !other_sidebar.nil? && parent["items"] + parent["items"].each do |parent_item| + if parent_item["slug"] == other_sidebar + parent_item["items"].push item + return nil + end + end + end + end + + if !item["items"].nil? + item["items"] = item["items"].map { |child| adjacent_move(child, stack + [item]) }.compact + end + item + end + + tree = tree.map { |item| adjacent_move(item, []) } tree.each do |collection| config_slug = "#{collection["name"]}_categories" diff --git a/src/_plugins/make_map_by.rb b/src/_plugins/make_map_by.rb new file mode 100644 index 0000000000000..d3bcaad3fefbb --- /dev/null +++ b/src/_plugins/make_map_by.rb @@ -0,0 +1,13 @@ +module Jekyll + module MakeMapByFilters + def make_map_by(input, key) + rv = {} + input.each do |item| + rv[item[key]] = item + end + rv + end + end +end + +Liquid::Template.register_filter(Jekyll::MakeMapByFilters) diff --git a/src/_plugins/platform_api.rb b/src/_plugins/platform_api.rb index 1738a7d12163b..1eb8a39f6cd95 100644 --- a/src/_plugins/platform_api.rb +++ b/src/_plugins/platform_api.rb @@ -1,127 +1,175 @@ -require 'json' - -module Jekyll - - class CategoryPage < Page - def initialize(site, base, dir, platform) - @site = site - @base = base - @dir = dir - @name = "#{platform["slug"]}.json" - self.process(@name) - self.read_yaml(File.join(base, '_layouts'), 'json.json') - keys = ["support_level","type","name","doc_link","body"] - self.data['json'] = platform.select {|key,_| keys.include? key} - self.data['json']['doc_link'] = "#{site.config["url"]}#{self.data['json']['doc_link']}" - end +require "nokogiri" +require "json" + +# The platform api is generated based on the `wizard` key in platforms.yml. This +# key can either be an array of documents with optional section slugs, or `true` +# which sets the value to `_documentation/quickstart.md` and renders only +# the content for that platform. +# +# In the targeted files, the wizard section is indicated by a comment, like so: +# +# +# +# Slugs are optional and are only useful for documents where only one of many +# sections must be referenced, or when sections must be reordered. +# +# When a file is specified without a section, all wizard blocks will be +# concatinated. If a section is specified, only the matching block will be used. +# +# Example: +# +# wizard: true +# wizard: +# - _documentation/path/to/doc.md +# - _documentation/path/to/doc-with-section.md#section-name + +class PlatformAPIError < StandardError +end + +class CategoryPage < Jekyll::Page + def initialize(site, base, dir, platform, name) + @site = site + @base = base + @dir = dir + @name = name + @data ||= {} + self.process(@name) + keys = ["support_level","type","name","doc_link","body"] + payload = platform.select {|key,_| keys.include? key} + self.output = payload.to_json end +end - class IndexPage < Page - def initialize(site, base, dir, payload) - @site = site - @base = base - @dir = dir - @name = "_index.json" - self.process(@name) - self.read_yaml(File.join(base, '_layouts'), 'json.json') - self.data['json'] = payload - end +class IndexPage < Jekyll::Page + def initialize(site, base, dir, payload, name) + @site = site + @base = base + @dir = dir + @name = name + @data ||= {} + self.process(@name) + self.output = payload.to_json end +end - class CategoryPageGenerator < Generator - safe true - - def get_headings(md) - headings = [] - enabled = true - # Make an index of all headings and their line numbers in the file - md.each_line.with_index do |line, i| - enabled = !enabled if line =~ /^```/ - if enabled && line =~ /^(#+)/ - headings << { - line: i, - level: $1.size, - # Remove initial hash or trailing attribute list - slug: Utils.slugify(line.gsub(/(^#+ |\s?\{.*\}$)/,'')) - } - end +Jekyll::Hooks.register :site, :post_render, priority: :high do |site| + if ENV["JEKYLL_ENABLE_PLATFORM_API"] != "false" + puts "Compiling platform API" + + index_payload = { + :platforms => {} + } + + site.data["platforms"].each do |platform| + next if platform["wizard"].nil? || platform["wizard_parent"].nil? + + # Create entry for _platforms/_index.json + file_name = "#{platform["slug"]}.json" + group_slug = platform["wizard_parent"] + is_self = group_slug === platform["slug"] + grouped_file = group_slug === platform["slug"] ? file_name : "#{group_slug}/#{file_name}" + + # This is a workaround to match javascript to browser docs now + if platform["wizard"] === true and platform["slug"] == "javascript" + platform["slug"] = "browser" + is_self = true + grouped_file = file_name end - headings - end - - def generate(site) - return if ENV["JEKYLL_DISABLE_PLATFORM_API"] == "true" + + platform_slug = is_self ? "_self" : platform["slug"] + doc_link = platform["wizard"] === true ? "/quickstart?platform=#{platform["slug"]}" : platform["doc_link"] + platform["doc_link"] = "#{site.config["url"]}#{ doc_link }" + + index_payload[:platforms][group_slug] ||= {} + index_payload[:platforms][group_slug][platform_slug] = { + :type => platform["type"], + :details => grouped_file, + :doc_link => platform["doc_link"], + :name => platform["name"] + } - # Create an index of all the sections in every document - docs = {} - site.collections["documentation"].docs.each do |doc| - content = doc.to_s - sections = { - :document => content - } - headings = get_headings(content) - headings.each do |heading| - startLine = heading[:line] - close = headings.find {|h| h[:line] > startLine && heading[:level] >= h[:level]} - if !close.nil? - endLine = close[:line] - sections[heading[:slug]] = content.lines[startLine, endLine - startLine].join - else - sections[heading[:slug]] = content.lines[startLine..-1].join - end - end + documentation = site.collections["documentation"].docs - docs[doc.relative_path] = sections + directives = case platform["wizard"] + when TrueClass + ["_documentation/learn/quickstart.md"] + when Array + platform["wizard"] + when NilClass + else + raise PlatformAPIError, "Unsupported value for `wizard` in #{platform["slug"]}: Must be `true` or an array of file paths." end - indexPayload = { - :platforms => {} - } + # Create entry for _platforms/.json or _platforms//.json + wizard_snippets = directives.map do |directive| + file_path, section_id = directive.split "#" + document = documentation.find { |d| d.relative_path === file_path } + blocks = document.content.scan(/([\s\S]+?)/) - # Generate each file - site.data["platforms"].each do |platform| - body = "" - platform["wizard"].each do |wiz| - file, section = wiz.split '#' - section ||= :document - if docs[file][section].nil? - raise "Cannot find section '#{section}' in #{file}" - end - body += docs[file][section] + body = if section_id.nil? + blocks.map { |b| b[1] }.join + else + match = blocks.find { |b| b[0] === section_id } + raise PlatformAPIError, "Could not find wizard section '#{section_id}' in #{file_path}" if match.nil? + match[1] end - platform["body"] = site.find_converter_instance( - Jekyll::Converters::Markdown - ).convert(body) - - pathData = Pathname(platform["doc_link"]).each_filename.to_a + body = body.gsub(/[\s\S]+?/, "") + + # Strip out platform content that doesn't relate to the current platform + noko_doc = Nokogiri::HTML(body) + noko_doc.css(".platform-specific-content").each do |node| + platform_content = node.css("[data-slug='#{platform["slug"]}']").children + raise PlatformAPIError, "Could not find platform content for '#{platform["slug"]}' in #{file_path}" if platform_content.empty? + node.replace platform_content + end + + noko_doc.css("a").each do |node| + node["href"] = Jekyll.configuration({})["url"] + node["href"] + end - if pathData.size > 2 - dir = "_platforms/#{pathData[1]}" - indexKey = platform["slug"] - else - dir = "_platforms" - indexKey = "_self" + # Extract nested highlights so sentry CSS can target the `pre`s + noko_doc.css(".highlighter-rouge").each do |node| + highlighted_content = node.css("pre.highlight") + node.replace highlighted_content end - platformKey = pathData[1] + noko_doc.css("body").children.to_s + end + + platform["body"] = wizard_snippets.join.strip - detailName = "#{platform["slug"]}.json" + dir = is_self ? "_platforms" : "_platforms/#{group_slug}" - # In which the javascript guy pretends to ruby - indexPayload[:platforms][platformKey] ||= {} - indexPayload[:platforms][platformKey][indexKey] ||= {} - indexPayload[:platforms][platformKey][indexKey] = { + # The first two cases are legacy structure for docs + case platform['slug'] + when "cocoa" + index_payload[:platforms]["react-native"] ||= {} + index_payload[:platforms]["react-native"]["_self"] = { :type => platform["type"], - :details => pathData.size > 2 ? File.join(pathData[1], detailName) : detailName, - :doc_link => "#{site.config["url"]}#{platform["doc_link"]}", + :details => file_name, + :doc_link => platform["doc_link"], :name => platform["name"] } - - site.pages << CategoryPage.new(site, site.source, dir, platform) + site.pages << CategoryPage.new(site, site.source, "_platforms", platform, file_name) + index_payload[:platforms]["react-native"].delete "cocoa" + when "objc" + index_payload[:platforms]["cocoa"] ||= {} + index_payload[:platforms]["cocoa"]["_self"] = { + :type => platform["type"], + :details => file_name, + :doc_link => platform["doc_link"], + :name => platform["name"] + } + site.pages << CategoryPage.new(site, site.source, "_platforms", platform, file_name) + site.pages << CategoryPage.new(site, site.source, dir, platform, file_name) + else + site.pages << CategoryPage.new(site, site.source, dir, platform, file_name) end - - site.pages << IndexPage.new(site, site.source, "_platforms", indexPayload) end + + site.pages << IndexPage.new(site, site.source, "_platforms", index_payload, "_index.json") + else + puts "Platform API is disabled. Run with JEKYLL_ENABLE_PLATFORM_API=true to enable" end end diff --git a/src/_plugins/release_registry.rb b/src/_plugins/release_registry.rb new file mode 100644 index 0000000000000..0be404f8ce435 --- /dev/null +++ b/src/_plugins/release_registry.rb @@ -0,0 +1,75 @@ +require 'net/http' + +module Jekyll + class ReleaseRegistryTag < Liquid::Tag + CACHE = {} + + def initialize(tag_name, text, tokens) + super + @params = text.split(/\s+/) + end + + def entity + raise NotImplementedError.new + end + + private + + def name + @params[0] + end + + def version + @params[1] || "latest" + end + + def get_info + self.class::CACHE[[entity, name, version]] ||= + begin + uri = URI("#{server}/#{entity}/#{name}/#{version}") + JSON.parse(Net::HTTP.get(uri)) + rescue Exception => e + raise RuntimeError.new("WARN: Failed to fetch version '#{version}' for '#{name}': #{e}") + end + end + + def server + # XXX: This prints out the configuration path every time it's accessed. + @server ||= Jekyll.configuration({})['release_service'] + end + end + + class PackageVersionTag < ReleaseRegistryTag + def entity + "packages" + end + + def render(context) + get_info["version"] + end + end + + class SdkVersionTag < ReleaseRegistryTag + def entity + "sdks" + end + + def render(context) + get_info["version"] + end + end + + class SdkRepoUrlTag < ReleaseRegistryTag + def entity + "sdks" + end + + def render(context) + get_info["repo_url"] + end + end +end + +Liquid::Template.register_tag('package_version', Jekyll::PackageVersionTag) +Liquid::Template.register_tag('sdk_version', Jekyll::SdkVersionTag) +Liquid::Template.register_tag('sdk_repo_url', Jekyll::SdkRepoUrlTag) diff --git a/src/_plugins/select_filters.rb b/src/_plugins/select_filters.rb new file mode 100644 index 0000000000000..2e4ddd5a90ae7 --- /dev/null +++ b/src/_plugins/select_filters.rb @@ -0,0 +1,17 @@ +module Jekyll + module SelectFilters + def map_select(input, arg) + keys = arg.split(/\s*,\s*/) + input.map do |x| + x.select { |k| keys.include? k.to_s } + end + end + + def select(input, arg) + keys = arg.split(/\s*,\s*/) + input.select { |k| keys.include? k.to_s } + end + end +end + +Liquid::Template.register_filter(Jekyll::SelectFilters) diff --git a/src/_plugins/unsupported.rb b/src/_plugins/unsupported.rb new file mode 100644 index 0000000000000..84f38b8842538 --- /dev/null +++ b/src/_plugins/unsupported.rb @@ -0,0 +1,29 @@ +module Jekyll + class UnsupportedTag < Liquid::Block + + def initialize(tag_name, text, tokens) + super + @slugs = text.split(/\s+/) + end + + def platform_attr + "unsupported-platforms" + end + + def render(context) + site = context.registers[:site] + converter = site.find_converter_instance(::Jekyll::Converters::Markdown) + content = converter.convert(super(context)) + %Q(
      #{content}
      ) + end + end + + class SupportedTag < UnsupportedTag + def platform_attr + "supported-platforms" + end + end +end + +Liquid::Template.register_tag('unsupported', Jekyll::UnsupportedTag) +Liquid::Template.register_tag('supported', Jekyll::SupportedTag) diff --git a/src/_plugins/url_starts_with.rb b/src/_plugins/url_starts_with.rb new file mode 100644 index 0000000000000..4848e869dbe4f --- /dev/null +++ b/src/_plugins/url_starts_with.rb @@ -0,0 +1,11 @@ +module Jekyll + module LiquifyFilter + def url_starts_with(input, arg) + arg = arg.chomp('/') + prefix = input[0..arg.length] + prefix == arg || prefix == arg + '/' + end + end +end + +Liquid::Template.register_filter(Jekyll::LiquifyFilter) diff --git a/src/_plugins/wizard.rb b/src/_plugins/wizard.rb new file mode 100644 index 0000000000000..1686e69bc2395 --- /dev/null +++ b/src/_plugins/wizard.rb @@ -0,0 +1,24 @@ +module Jekyll + class WizardTag < Liquid::Block + + def initialize(tag_name, text, tokens) + super + @flag = text + @flag.chomp! + @flag.strip! + end + + def render(context) + site = context.registers[:site] + converter = site.find_converter_instance(::Jekyll::Converters::Markdown) + content = converter.convert(super(context)) + + case @flag + when "hide" then %Q(#{content}) + else %Q(#{content}) + end + end + end +end + +Liquid::Template.register_tag('wizard', Jekyll::WizardTag) diff --git a/src/collections/_documentation/clientdev/attributes.md b/src/collections/_documentation/clientdev/attributes.md index 783caf41fe9bc..47cdde90e388e 100644 --- a/src/collections/_documentation/clientdev/attributes.md +++ b/src/collections/_documentation/clientdev/attributes.md @@ -1,11 +1,15 @@ --- title: Attributes -sidebar_order: 1 +sidebar_order: 10 --- -Attributes are simple data that Sentry understands to provide the most basic information about events. These are things like the unique ID of an event, the human readable message etc. +Attributes are simple data that Sentry understands to provide the most basic +information about events. These are things like the unique ID of an event, the +human readable message etc. -Attributes are separate from [_Interfaces_]({%- link _documentation/clientdev/interfaces/index.md -%}) which provide very specific and tailored data such as exception data, stacktraces, etc. +Attributes are separate from [_Interfaces_]({%- link +_documentation/clientdev/interfaces/index.md -%}) which provide very specific +and tailored data such as exception data, stacktraces, etc. ## Required Attributes @@ -13,9 +17,8 @@ The following attributes are required for all events: `event_id` -: Hexadecimal string representing a uuid4 value. - - The length is exactly 32 characters (no dashes!) +: Hexadecimal string representing a uuid4 value. The length is exactly 32 + characters. Dashes are not allowed. ```json { @@ -25,11 +28,9 @@ The following attributes are required for all events: `timestamp` -: Indicates when the logging record was created (in the Sentry SDK). - - The Sentry server assumes the time is in UTC. - - The timestamp should be in ISO 8601 format, without a timezone. +: Indicates when the logging record was created (in the Sentry SDK). The Sentry + server assumes the time is in UTC. The timestamp should be in ISO 8601 format, + without a timezone. ```json { @@ -49,7 +50,8 @@ The following attributes are required for all events: `platform` -: A string representing the platform the SDK is submitting from. This will be used by the Sentry interface to customize various components in the interface. +: A string representing the platform the SDK is submitting from. This will be + used by the Sentry interface to customize various components in the interface. ```json { @@ -77,7 +79,9 @@ The following attributes are required for all events: `sdk` -: Information about the SDK sending the event. Note that the `integrations` key is optional and used to list any of the SDK and language specific integrations that the user is actively using. +: Information about the SDK sending the event. Note that the `integrations` key + is optional and used to list any of the SDK and language specific integrations + that the user is actively using. ```json { @@ -93,7 +97,8 @@ The following attributes are required for all events: ## Optional Attributes -Additionally, there are several optional values which Sentry recognizes and are highly encouraged: +Additionally, there are several optional values which Sentry recognizes and are +highly encouraged: `level` @@ -117,18 +122,23 @@ Additionally, there are several optional values which Sentry recognizes and are - `info` - `debug` -`culprit` +`transaction` -: The name of the transaction (or culprit) which caused this exception. +: The name of the transaction which caused this exception For example, in a web app, this might be the route name: `/welcome/` ```json { - "culprit": "my.module.function_name" + "transaction": "/users//" } ``` +`culprit` + +: The name of the culprit which caused this exception. This attribute is + deprecated. + `server_name` : Identifies the host SDK from which the event was recorded. @@ -143,7 +153,8 @@ Additionally, there are several optional values which Sentry recognizes and are : The release version of the application. - This value will generally be something along the lines of the git SHA for the given project. + This value will generally be something along the lines of the git SHA for the + given project. ```json { @@ -164,18 +175,9 @@ Additionally, there are several optional values which Sentry recognizes and are } ``` - ```json - { - "tags": [ - ["ios_version", "4.0"], - ["context", "production"] - ] - } - ``` - `environment` -: The environment name, such as ‘production’ or ‘staging’. +: The environment name, such as `production` or `staging`. ```json { @@ -212,22 +214,30 @@ Additionally, there are several optional values which Sentry recognizes and are `fingerprint` -: An array of strings used to dictate the deduplication of this event. - - A value of `{% raw %}{{ default }}{% endraw %}` will be replaced with the built-in behavior, thus allowing you to extend it, or completely replace it. +: A list of strings used to dictate the deduplication of this event. A value + of `{% raw %}{{ default }}{% endraw %}` will be replaced with the built-in + behavior, thus allowing you to extend it, or completely replace it. ```json { - "fingerprint": ["myrpc", "POST", "/foo.bar"] + "fingerprint": [ + "myrpc", + "POST", + "/foo.bar" + ] } ``` ```json {% raw %}{ - "fingerprint": ["{{ default }}", "http://example.com/my.url"] + "fingerprint": [ + "{{ default }}", + "http://example.com/my.url" + ] }{% endraw %} ``` - {% version_added Protocol: version ‘7’ %} + {% version_added Protocol: 7 %} -For information about overriding grouping see [Customize Grouping with Fingerprints]({%- link _documentation/learn/rollups.md -%}#custom-grouping). +For information about overriding grouping see [Customize Grouping with +Fingerprints]({%- link _documentation/learn/rollups.md -%}#custom-grouping). diff --git a/src/collections/_documentation/clientdev/context.md b/src/collections/_documentation/clientdev/context.md deleted file mode 100644 index b43ff224662f5..0000000000000 --- a/src/collections/_documentation/clientdev/context.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: 'Context Management' -sidebar_order: 2 ---- - -All SDKs should have the concept of concurrency safe context storage. What this means depends on the language. The basic idea is that a user of the SDK can call a method to safely provide additional context information from whererever the user has access to the client object. - -This is implemented as a thread local in most languages, but in some (such as JavaScript) it might be global under the assumption that this is something that makes sense in the environment. - -## User’s Perspective {#user-s-perspective} - -From the user’s perspective of the Sentry SDK there should be two types of APIs: - -`SentryClient.context`: - -: Given a Sentry SDK object it should be possible to get a reference to the underlying context object for manual updating. This might not always be something that makes sense in the context of the language, so it’s sometimes reasonable to hide this. - - If it is possible in the language, then it’s encouraged that this be a thread local accessor so as not to break concurrent environments. For instance the Python SDK has a different context for each thread to support concurrent web frameworks and multithreaded environments. - - If the context is exposed it needs to provide two methods: - - - `merge()`: to merge in a new nested dictionary of data over the existing data. - - `clear()`: to clear the context entirely. This is necessary so that reuse of threads is safe and old data does not leak into the reused context. - -`SentryClient.*_context`: - -: These are methods that update the context according to the name of the method. Which of those methods exist is up to the SDK developer, however as a general rule these should exist: - - - `user_context` - - `tags_context` - - `http_context` - - `extra_context` - -Ideally a user never needs to be concerned with clearing the context. Framework integrations should do this automatically as far as possible. For instance if a SDK integration is configured for a web framework it should automatically hook the framework in a way where it will clear the context at the end of every request and ideally also already invoke things like `http_context` automatically. - -## Context Clearing - -For most SDKs there should be a method to clear the context. This is especially imporant in multithreaded environments where threads might be re-used. It is preferred that the context be cleared automatically if that is something the SDK can provide. As mentioned earlier the framework integrations in the SDKs should do this whenever possible. - -For manual clearing `client.context.clear()` is the preferred method. If the context cannot be directly exposed, `client.clearContext()` or a method with a similar name should exist. - -## Common Context Methods - -It is recommended that the following methods exist: - -`client.user_context(data)`: - -: Updates the user context for future events. - - Equivalent to this: - - ```javascript - client.context.merge({'user': data}) - ``` - -`client.http_context(data)`: - -: Updates the HTTP context for future events. - - Equivalent to this: - - ```javascript - client.context.merge({'request': data}) - ``` - -`client.extra_context(data)`: - -: Update the extra context for future events. - - Equivalent to this: - - ```javascript - client.context.merge({'extra': data}) - ``` - -`client.tags_context(data)`: - -: Update the tags context for future events. - - Equivalent to this: - - ```javascript - client.context.merge({'tags': data}) - ``` - -For some SDKs it also makes sense to provide additional helpers to bind the HTTP context and similar things to common language patterns. For instance if you expect a CGI/WSGI/Rack environment you could provide `client.cgi_context` / `client.wsgi_context` methods. diff --git a/src/collections/_documentation/clientdev/data-handling.md b/src/collections/_documentation/clientdev/data-handling.md index 17be1d2174a15..cc7a534709d78 100644 --- a/src/collections/_documentation/clientdev/data-handling.md +++ b/src/collections/_documentation/clientdev/data-handling.md @@ -1,42 +1,23 @@ --- title: 'Data Handling' -sidebar_order: 3 +sidebar_order: 30 --- -## Sensitive Data - -SDKs should provide some mechanism for scrubbing data. Ideally through an extensible interface that the user can customize the behavior of. +Data handling is the standardized context in how we want SDKs help users filter data. -This is generally done as part of the SDK configuration: - -```php -client = Client(..., { - 'processors': ['processor.className'], -}) -``` +## Sensitive Data -Each processor listed would be some sort of extensible class or a function callback. It would have a single designated method that is passed the data (after it’s been populated), and would then return the data fully intact, or modified with various bits filtered out. +In older SDKs you might sometimes see elaborate constructs to allow the user to strip away sensitive data. Newer SDKs no longer have this feature as it turned out to be too hard to maintain per-SDK. Instead, only two simple config options are left: -For example, if you simply supported callbacks for processors, it might look like this: +- [_send-default-pii_]({%- link _documentation/learn/configuration.md -%}#send-default-pii) is **disabled by default**, meaning that data that is naturally sensitive is not sent by default. That means, for example: -```php -function my_processor($data) { - foreach ($data['extra'] as $key => $value) { - if (strpos($value, 'password')) { - $data[$key] = '********'; - } - } -} -``` + - When attaching HTTP requests to events, "raw" bodies (bodies which cannot be parsed as JSON or formdata) are removed, and known sensitive headers such as `Authentication` or `Cookies` are removed too. -We recommend scrubbing the following values: + - User-specific information (e.g. the current user ID according to the used webframework) is not sent at all. -- Values where the keyname matches ‘password’, ‘passwd’, or ‘secret’. -- Values that match the regular expression of `r'^(?:\d[ -]*?){13,16}$'` (credit card-like). -- Session cookies. -- The Authentication header (HTTP). + - Note that if a user explicitly sets a request on the scope, nothing is stripped from that request. The above rules only apply to integrations that come with the SDK. -Keep in mind that if your SDK is passing extra interface data (e.g. HTTP POST variables) you will also want to scrub those interfaces. Given that, it is a good idea to simply recursively scrub most variables other than predefined things (like HTTP headers). +- [_before-send_]({%- link _documentation/learn/configuration.md -%}#before-send) can be used to register a callback with custom logic to remove sensitive data. ## Variable Size diff --git a/src/collections/_documentation/clientdev/features.md b/src/collections/_documentation/clientdev/features.md index 55a23b4e7b532..a6894b0568f08 100644 --- a/src/collections/_documentation/clientdev/features.md +++ b/src/collections/_documentation/clientdev/features.md @@ -1,24 +1,33 @@ --- title: 'Expected Features' +sidebar_order: 4 --- -The following is a description of features that are commonly expected in Sentry SDKs. +The following is a description of features that are commonly expected in Sentry SDKs. Make sure to also +have consulated the [unified API design]({% link _documentation/clientdev/unified-api.md %}) documentation +which explains the common API design. -## Uncaught exception handler +## Background Sending -Ability for the SDK to be set as a hook to record any uncaught exceptions. At the language level this is typically a global hook provided by the language itself. For framework intergations this is typically part of middleware or some other system. +Events should be transmitted in the background thread or similar system. This queue must be flushed when the +application shuts down with a specific timeout. This feature is typically user facing and explained +as part of [shutdown and draining]({% link _documentation/learn/draining.md %}). -## Setting Attributes +## Uncaught Exception Handler -Ability to set attributes on events sent to Sentry. They should be configurable “globally” on the client itself (so that they are sent with all future events) and also per event. Important examples are being able to set the `release`, `environment`, `tags` and `extra`. [See the attributes page]({%- link _documentation/clientdev/attributes.md -%}#attributes) for more information and examples. +Ability for the SDK to be set as a hook to record any uncaught exceptions. At the language level this is typically a global hook provided by the language itself. For framework intergations this might be part of middleware or some other system. -## Automatic Attributes +This behavior is typically provided by a default integration that can be disabled. -Automatic addition of useful attributes such as `tags` or `extra`. Typically means the SDK hooks into a framework so that it can set attributes that are known to be useful for most users. +## Scopes -## Context system +Scopes should be provided by SDKs to set common attributes and context data on events sent to Sentry emitted from the current scope. They should be inherited to lower scopes so that they can be set "globally" on startup. Note that some attributes can only be set in the client options (`release`, `environment`) and not on scopes. -A system for storing data that has to do with a given context. What context means depends on the application, for a web framework it is most likely a single request/response cycle. For a mobile application there is often just one single context that represents the single user and their actions. Context can be difficult to implement because it often has to deal with threads or concurrency and can involve deep integration with frameworks. [See the context page]({%- link _documentation/clientdev/context.md -%}#context) for more information. +What scope means depends on the application, for a web framework it is most likely a single request/response cycle. For a mobile application there is often just one single scope that represents the single user and their actions. Scoping can be difficult to implement because it often has to deal with threads or concurrency and can involve deep integration with frameworks. [See the scopes page]({%- link _documentation/clientdev/unified-api.md -%}#scope) for more information. + +## Automatic Context Data + +Automatic addition of useful attributes such as `tags` or `extra` or specific `contexts`. Typically means the SDK hooks into a framework so that it can set attributes that are known to be useful for most users. ## Breadcrumbs @@ -35,26 +44,22 @@ sample_rate = options.get('sample_rate', 1.0) # assuming random() returns a value between 0.0 (inclusive) and 1.0 (exclusive) if random() < sample_rate: - client.send(data) + transport.capture_event(event) ``` ## HTTP 429 Retry-After backoff Respect Sentry’s HTTP 429 Retry-After header when the user goes over their limits. Events should be dropped during backoff. -## Ignore patterns - -The user should be able to define exceptions that are ignored/dropped based on the error message or type. - ## In-App frames Stack parsing can tell which frames should be identified as part of the user’s application (as opposed to part of the language, a library, or a framework), either automatically or by user configuration at startup, often declared as a package/module prefix. -## Surrounding source in stacktrace +## Surrounding Source in Stacktrace Lines of source code to provide context in stacktraces. This is easier in interpreted languages, may be hard or impossible in compiled ones. -## Variable values +## Local Variables Local variable names and values for each stack frame, where possible. Restrictions apply on some platforms, for example it’s may only be possible to collect the values of parameters passed into each function, or it may be completely impossible to collect this information at all. @@ -62,33 +67,29 @@ Local variable names and values for each stack frame, where possible. Restrictio Turn compiled or obfuscated code/method names in stacktraces back into the original. Desymbolication always requires Sentry backend support. Not necessary for many languages. -## Configuration via the runtime environment - -Whether static client configuration can set/overridden by the runtime environment _without changing code_. For example, a _SENTRY_RELEASE=1.3_ environment variable that configures the client. Important so that users can package/compile their applications once and adjust Sentry config without rebuilding (very common now for all languages because of the popularity of containers). Not available or doesn’t make sense on some runtimes (browsers, mobile). - -## Retrieve last event ID +## Retrieve Last Event ID Ability to get the ID of the last event sent. Event IDs are useful for correlation, logging, customers rolling their own feedback forms, etc. -## User feedback +## User Feedback On user-facing platforms such as mobile or the browser this means first class support for requesting user feedback when an error occurs. On backend platforms, SDKs should document how to use the last event ID to prompt the user for feedback themselves. -## Pre-send hook +## Before-Send Hook -Hook called with the event **and** thrown exception (where applicable) that allow the user to decide whether an event should be sent or not. +Hook called with the event (and on some platforms the hint) that allow the user to decide whether an event should be sent or not. This can also be used to further modify the event. -## Post-send hook +## Before-Breadcrumb Hook -Hook called on success **or** error, and passed the event and exception so that users can peform actions based on events actually being sent. +Hook called with the breadcrumb (and on some platforms the hint) that allow the user to decide whether and how an breadcrumb should be sent. -## List loaded libraries +## List Loaded Libraries Include a list of loaded libraries (and versions) when sending an event. -## Buffer to disk +## Buffer to Disk Write events to disk before attempting to send, so that they can be retried in the event of a temporary network failure. Needs to implement a cap on the number of stored events. @@ -96,4 +97,4 @@ This is mostly useful on mobile clients where connectivity is often not availabl ## HTTP Proxy -Ability to use an HTTP proxy. Often easy to implement using the existing HTTP client. +Ability to use an HTTP proxy. Often easy to implement using the existing HTTP client. This should be picked up from the system config if possible or exlicit config in the client options. diff --git a/src/collections/_documentation/clientdev/index.md b/src/collections/_documentation/clientdev/index.md index 72d52a4c7e1c8..03587190a7b57 100644 --- a/src/collections/_documentation/clientdev/index.md +++ b/src/collections/_documentation/clientdev/index.md @@ -3,11 +3,14 @@ title: 'SDK Reference' sidebar_order: 7 --- -The following is a guide for implementing a new Sentry SDK. It covers the protocol for event submission as well as guidelines for how clients should typically look and behave. +The following is a guide for implementing a new Sentry SDK based on the new +[Unified API]({% link _documentation/clientdev/unified-api.md %}). It covers +the protocol for event submission as well as guidelines for how clients should +typically look and behave. - [Overview]({%- link _documentation/clientdev/overview.md -%}) +- [Unified API]({%- link _documentation/clientdev/unified-api.md -%}) - [Expected Features]({%- link _documentation/clientdev/features.md -%}) - [Attributes]({%- link _documentation/clientdev/attributes.md -%}) - [Interfaces]({%- link _documentation/clientdev/interfaces/index.md -%}) - [Data Handling]({%- link _documentation/clientdev/data-handling.md -%}) -- [Context Management]({%- link _documentation/clientdev/context.md -%}) diff --git a/src/collections/_documentation/clientdev/interfaces/breadcrumbs.md b/src/collections/_documentation/clientdev/interfaces/breadcrumbs.md index ca13703842c64..4f274fa2e2362 100644 --- a/src/collections/_documentation/clientdev/interfaces/breadcrumbs.md +++ b/src/collections/_documentation/clientdev/interfaces/breadcrumbs.md @@ -3,64 +3,92 @@ title: 'Breadcrumbs Interface' sidebar_order: 5 --- -The breadcrumbs interface specifies a series of application events, or “breadcrumbs”, that occurred before the main event. +The breadcrumbs interface specifies a series of application events, or +“breadcrumbs”, that occurred before the main event. Its canonical name is +`"breadcrumbs"`. -The value of the interface is an array of breadcrumb objects. Breadcrumb entries are ordered from oldest to newest. The last breadcrumb in the array should be the last entry before the main event fired. +This interface is an object with a sole `values` key containing an ordered list +of breadcrumb objects. The entries are ordered from oldest to newest. +Consequently, the last entry in the array should be the last entry before the +event occurred. -Each breadcrumb has a few properties of which at least `timestamp` and `category` must be provided. The rest is optional and depending on what is provided the rendering might be different. +Each breadcrumb has a few properties of which at least `timestamp` and +`category` must be provided. The rest is optional and depending on what is +provided the rendering might be different: `timestamp` -: A timestamp representing when the breadcrumb occurred. This can be either an ISO datetime string, or a Unix timestamp. +: **Required**. A timestamp representing when the breadcrumb occurred. This can +be either an ISO datetime string, or a Unix timestamp. `type` -: The type of breadcrumb. The default type is `default` which indicates no specific handling. Other types are currently `http` for HTTP requests and `navigation` for navigation events. More about types later. +: _Optional_. The type of breadcrumb. The default type is `default` which +indicates no specific handling. Other types are currently `http` for HTTP +requests and `navigation` for navigation events. More about types later. -`message` +`category` -: If a message is provided it’s rendered as text and the whitespace is preserved. Very long text might be abbreviated in the UI. +: _Optional_. A dotted string indicating what the crumb is or where it comes +from. Typically it is a module name or a descriptive string. For instance, +_ui.click_ could be used to indicate that a click happend in the UI or _flask_ +could be used to indicate that the event originated in the Flask framework. -`data` +`message` -: Data associated with this breadcrumb. Contains a sub-object whose contents depend on the breadcrumb `type`. See descriptions of breadcrumb types below. Additional parameters that are unsupported by the type are rendered as a key/value table. +: _Optional_. If a message is provided it is rendered as text with all +whitespace preserved. Very long text might be truncated in the UI. -`category` +`data` -: Categories are dotted strings that indicate what the crumb is or where it comes from. Typically it’s a module name or a descriptive string. For instance _ui.click_ could be used to indicate that a click happend in the UI or _flask_ could be used to indicate that the event originated in the Flask framework. +: _Optional_. Arbitrary data associated with this breadcrumb. Contains a +dictionary whose contents depend on the breadcrumb `type`. See descriptions of +breadcrumb types below. Additional parameters that are unsupported by the type +are rendered as a key/value table. `level` -: This defines the level of the event. If not provided it defaults to `info` which is the middle level. In the order of priority from highest to lowest the levels are `critical`, `error`, `warning`, `info` and `debug`. Levels are used in the UI to emphasize and deemphasize the crumb. +: _Optional_. This defines the severity level of the breadcrumb. Allowed values +are, from highest to lowest: `critical`, `error`, `warning`, `info` and `debug`. +Levels are used in the UI to emphasize and deemphasize the crumb. Defaults to +`info`. + +## Examples ```json -"breadcrumbs": [ - { - "timestamp": 1461185753845, - "message": "Something happened", - "category": "log", - "data": { - "foo": "bar", - "blub": "blah" +"breadcrumbs": { + "values": [ + { + "timestamp": 1461185753845, + "message": "Something happened", + "category": "log", + "data": { + "foo": "bar", + "blub": "blah" + } + }, + { + "timestamp": "2016-04-20T20:55:53.847Z", + "type": "navigation", + "data": { + "from": "/login", + "to": "/dashboard" + } } - }, { - "timestamp": 1461185753847, - "type": "navigation", - "data": { - "from": "/login", - "to": "/dashboard" - } - } + ] ] ``` ## Breadcrumb Types -Below are descriptions of individual breadcrumb types, and what their `data` properties look like. +Below are descriptions of individual breadcrumb types, and what their `data` +properties look like. -`default` +### `default` -Describes an unspecified breadcrumb. This is typically a generic log message or something similar. The `data` part is entirely undefined and as such completely rendered as a key/value table. +Describes an generic breadcrumb. This is typically a log message or user +generated breadcrumb. The `data` part is entirely undefined and as such +completely rendered as a key/value table. ```json { @@ -73,19 +101,20 @@ Describes an unspecified breadcrumb. This is typically a generic log message or } ``` -`navigation` +### `navigation` -Describes a navigation breadcrumb. A navigation event can be a URL change in a web application, or a UI transition in a mobile or desktop application, etc. +Describes a navigation breadcrumb. A navigation event can be a URL change in a +web application, or a UI transition in a mobile or desktop application, etc. Its `data` property has the following sub-properties: `from` -: A string representing the original application state / location. +: **Required**. A string representing the original application state / location. `to` -: A string representing the new application state / location. +: **Required**. A string representing the new application state / location. ```json { @@ -98,27 +127,29 @@ Its `data` property has the following sub-properties: } ``` -`http` +### `http` -Describes an HTTP request breadcrumb. This represents an HTTP request transmitted from your application. This could be an AJAX request from a web application, or a server-to-server HTTP request to an API service provider, etc. +Describes an HTTP request breadcrumb. This represents an HTTP request +transmitted from your application. This could be an AJAX request from a web +application, or a server-to-server HTTP request to an API service provider, etc. Its `data` property has the following sub-properties: `url` -: The request URL. +: _Optional_. The request URL. `method` -: The HTTP request method. +: _Optional_. The HTTP request method. `status_code` -: The HTTP status code of the response. +: _Optional_. The HTTP status code of the response. `reason` -: A text that describes the status code. +: _Optional_. A text that describes the status code. ```json { diff --git a/src/collections/_documentation/clientdev/interfaces/contexts.md b/src/collections/_documentation/clientdev/interfaces/contexts.md index 8a469ab004a6c..d118ce340b781 100644 --- a/src/collections/_documentation/clientdev/interfaces/contexts.md +++ b/src/collections/_documentation/clientdev/interfaces/contexts.md @@ -3,22 +3,26 @@ title: 'Contexts Interface' sidebar_order: 6 --- -The context interfaces provide additional context data. Typically this is data related to the current user, the current HTTP request. +The context interfaces provide additional context data. Typically this is data +related to the current user, the current HTTP request. Its canonical name is `"contexts"`. -The `contexts` type can be used to defined almost arbitrary contextual data on the event. It accepts an object of key, value pairs. The key is the “alias” of the context and can be freely chosen. However as per policy it should match the type of the context unless there are two values for a type. +The `contexts` type can be used to defined almost arbitrary contextual data on +the event. It accepts an object of key, value pairs. The key is the “alias” of +the context and can be freely chosen. However as per policy it should match the +type of the context unless there are two values for a type. Example: -```php +```json "contexts": { - "os": { - "type": "os", - "name": "Windows" - } + "os": { + "type": "os", + "name": "Windows" + } } ``` -If `type` is omitted it uses the alias as type. +If `type` is omitted it uses the key name as type. Unknown data for the contexts is rendered as a key/value list. @@ -28,162 +32,195 @@ The following types are known: `device` -: This describes the device that caused the event. This is most appropriate for mobile applications. +: This describes the device that caused the event. This is most appropriate for + mobile applications. Attributes: `name`: - : The name of the device. This is typically a hostname. + : _Optional_. The name of the device. This is typically a hostname. `family`: - : The family of the device. This is normally the common part of model names across generations. For instance `iPhone` would be a reasonable family, so would be `Samsung Galaxy`. + : _Optional_. The family of the device. This is normally the common part of + model names across generations. For instance `iPhone` would be a reasonable + family, so would be `Samsung Galaxy`. `model`: - : The model name. This for instance can be `Samsung Galaxy S3`. + : _Optional_. The model name. This for instance can be `Samsung Galaxy S3`. `model_id`: - : An internal hardware revision to identify the device exactly. + : _Optional_. An internal hardware revision to identify the device exactly. `arch`: - : The CPU architecture. + : _Optional_. The CPU architecture. `battery_level`: - : If the device has a battery this can be an floating point value defining the battery level (in the range 0-100). + : _Optional_. If the device has a battery, this can be an floating point value + defining the battery level (in the range 0-100). `orientation`: - : This can be a string `portrait` or `landscape` to define the orientation of a device. + : _Optional_. This can be a string `portrait` or `landscape` to define the + orientation of a device. `simulator`: - : A boolean defining whether this device is a simulator or an actual device. + : _Optional_. A flag indicating whether this device is a simulator or an + actual device. `memory_size`: - : Total system memory available in bytes. + : _Optional_. Total system memory available in bytes. `free_memory`: - : Free system memory in bytes. + : _Optional_. Free system memory in bytes. `usable_memory`: - : Memory usable for the app in bytes. + : _Optional_. Memory usable for the app in bytes. `storage_size`: - : Total device storage in bytes. + : _Optional_. Total device storage in bytes. `free_storage`: - : Free device storage in bytes. + : _Optional_. Free device storage in bytes. `external_storage_size`: - : Total size of an attached external storage in bytes (e.g.: android SDK card). + : _Optional_. Total size of an attached external storage in bytes (e.g.: + android SDK card). `external_free_storage`: - : Free size of an attached external storage in bytes (e.g.: android SDK card). + : _Optional_. Free size of an attached external storage in bytes (e.g.: + android SDK card). `boot_time`: - : A formatted UTC timestamp when the system was booted, e.g.: `"2018-02-08T12:52:12Z"`. + : _Optional_. A formatted UTC timestamp when the system was booted, e.g.: + `"2018-02-08T12:52:12Z"`. `timezone`: - : The timezone of the device, e.g.: `Europe/Vienna`. + : _Optional_. The timezone of the device, e.g.: `Europe/Vienna`. `os` -: Describes the operating system on which the event was created. In web contexts, this is the operating system of the browser (normally pulled from the User-Agent string). +: Describes the operating system on which the event was created. In web + contexts, this is the operating system of the browser (normally pulled from + the User-Agent string). Attributes: `name`: - : The name of the operating system. + : _Optional_. The name of the operating system. `version`: - : The version of the operating system. + : _Optional_. The version of the operating system. `build`: - : The internal build revision of the operating system. + : _Optional_. The internal build revision of the operating system. `kernel_version`: - : If known, this can be an independent kernel version string. Typically this is something like the entire output of the `uname` tool. + : _Optional_. An independent kernel version string. This is typically the + entire output of the `uname` syscall. `rooted`: - : An optional boolean that defines if the OS has been jailbroken or rooted. + : _Optional_. A flag indicating whether the OS has been jailbroken or rooted. + + `raw_description`: + + : _Optional_. An unprocessed description string obtained by the operating + system. For some well-known runtimes, Sentry will attempt to parse `name` + and `version` from this string, if they are not explicitly given. + `runtime` -: Describes a runtime in more detail. Typically this context is used multiple times if multiple runtimes are involved (for instance if you have a JavaScript application running on top of JVM) +: Describes a runtime in more detail. Typically this context is used multiple + times if multiple runtimes are involved (for instance if you have a JavaScript + application running on top of JVM) Attributes: `name`: - : The name of the runtime. + : _Optional_. The name of the runtime. `version`: - : The version identifier of the runtime. + : _Optional_. The version identifier of the runtime. + + `raw_description`: + + : _Optional_. An unprocessed description string obtained by the runtime. For + some well-known runtimes, Sentry will attempt to parse `name` and `version` + from this string, if they are not explicitly given. `app` -: Describes the application. As opposed to the runtime, this is the actual application that was running and carries meta data about the current session. +: Describes the application. As opposed to the runtime, this is the actual + application that was running and carries meta data about the current session. Attributes: `app_start_time`: - : Formatted UTC timestamp when the application was started by the user. + : _Optional_. Formatted UTC timestamp when the application was started by the + user. `device_app_hash`: - : Application specific device identifier. + : _Optional_. Application specific device identifier. `build_type`: - : String identifying the kind of build, e.g. `testflight`. + : _Optional_. String identifying the kind of build, e.g. `testflight`. `app_identifier`: - : Version-independent application identifier, often a dotted bundle ID. + : _Optional_. Version-independent application identifier, often a dotted + bundle ID. `app_name`: - : Human readable application name, as it appears on the platform. + : _Optional_. Human readable application name, as it appears on the platform. `app_version`: - : Human readable application version, as it appears on the platform. + : _Optional_. Human readable application version, as it appears on the + platform. `app_build`: - : Internal build identifier, as it appears on the platform. + : _Optional_. Internal build identifier, as it appears on the platform. `browser` -: Carries information about the browser or user agent for web-related errors. This can either be the browser this event ocurred in, or the user agent of a web request that triggered the event. +: Carries information about the browser or user agent for web-related errors. + This can either be the browser this event ocurred in, or the user agent of a + web request that triggered the event. Attributes: `name`: - : Display name of the browser application. + : _Optional_. Display name of the browser application. `version`: - : Version string of the browser. + : _Optional_. Version string of the browser. diff --git a/src/collections/_documentation/clientdev/interfaces/index.md b/src/collections/_documentation/clientdev/interfaces/index.md index 0c068c85205bc..e5e9032b2c6d9 100644 --- a/src/collections/_documentation/clientdev/interfaces/index.md +++ b/src/collections/_documentation/clientdev/interfaces/index.md @@ -1,32 +1,37 @@ --- title: Interfaces -sidebar_order: 1 +sidebar_order: 20 --- -Any additional value in the payload of an event which is not an attribute ([_Attributes_]({%- link _documentation/clientdev/attributes.md -%})) is assumed to be a data interface, where the key is the Python path to the interface class name, and the value is the data expected by the interface. Interfaces are used in a variety of ways including storing stacktraces, HTTP request information, and other metadata. +Any additional value in the payload of an event which is not an attribute (see +[_Attributes_]({%- link _documentation/clientdev/attributes.md -%})) is assumed +to be a data interface, where the key is the canonical interface short name, and +the value is the data expected by the interface (usually a dictionary). +Interfaces are used in a variety of ways including storing stacktraces, HTTP +request information, and other metadata. -For the most part interfaces are an evolving part of Sentry. Like with attributes, SDKs are expected to assume more can appear at any point in the future. More than that however, for on-premise installations of Sentry the interfaces can be customized so SDK libraries should ideally be written in a way that custom interfaces can be emitted. - -Interfaces are typically identified by their full canonical path as it exists in Sentry. For built-in interfaces we also provide aliases which should be used instead. For instance the full canonical path for the stacktrace interface is `sentry.interfaces.Stacktrace` which is also available under the alias `stacktrace`. +For the most part, interfaces are an evolving part of Sentry. Like with +attributes, SDKs are expected to assume that more interfaces will be added at +any point in the future. ## Core Data -- [Exception Interface]({%- link _documentation/clientdev/interfaces/exception.md -%}) -- [Message Interface]({%- link _documentation/clientdev/interfaces/message.md -%}) -- [Stacktrace Interface]({%- link _documentation/clientdev/interfaces/stacktrace.md -%}) -- [Template Interface]({%- link _documentation/clientdev/interfaces/template.md -%}) +- [Exception Interface]({%- link _documentation/clientdev/interfaces/exception.md -%}) +- [Log Entry Interface]({%- link _documentation/clientdev/interfaces/message.md -%}) +- [Stacktrace Interface]({%- link _documentation/clientdev/interfaces/stacktrace.md -%}) +- [Template Interface]({%- link _documentation/clientdev/interfaces/template.md -%}) -## Context +## Scope -- [Breadcrumbs Interface]({%- link _documentation/clientdev/interfaces/breadcrumbs.md -%}) -- [Contexts Interface]({%- link _documentation/clientdev/interfaces/contexts.md -%}) -- [HTTP Interface]({%- link _documentation/clientdev/interfaces/http.md -%}) -- [Threads Interface]({%- link _documentation/clientdev/interfaces/threads.md -%}) -- [User Interface]({%- link _documentation/clientdev/interfaces/user.md -%}) +- [Breadcrumbs Interface]({%- link _documentation/clientdev/interfaces/breadcrumbs.md -%}) +- [Contexts Interface]({%- link _documentation/clientdev/interfaces/contexts.md -%}) +- [HTTP Interface]({%- link _documentation/clientdev/interfaces/http.md -%}) +- [Threads Interface]({%- link _documentation/clientdev/interfaces/threads.md -%}) +- [User Interface]({%- link _documentation/clientdev/interfaces/user.md -%}) ## Misc -- [Debug Interface]({%- link _documentation/clientdev/interfaces/debug.md -%}) -- [Exception Mechanism Interface]({%- link _documentation/clientdev/interfaces/mechanism.md -%}) -- [Repos Interface]({%- link _documentation/clientdev/interfaces/repos.md -%}) -- [SDK Interface]({%- link _documentation/clientdev/interfaces/sdk.md -%}) +- [Debug Interface]({%- link _documentation/clientdev/interfaces/debug.md -%}) +- [Exception Mechanism Interface]({%- link _documentation/clientdev/interfaces/mechanism.md -%}) +- [Repos Interface]({%- link _documentation/clientdev/interfaces/repos.md -%}) +- [SDK Interface]({%- link _documentation/clientdev/interfaces/sdk.md -%}) diff --git a/src/collections/_documentation/clientdev/interfaces/sdk.md b/src/collections/_documentation/clientdev/interfaces/sdk.md index c92de4926a387..e4b29189d28bf 100644 --- a/src/collections/_documentation/clientdev/interfaces/sdk.md +++ b/src/collections/_documentation/clientdev/interfaces/sdk.md @@ -3,19 +3,49 @@ title: 'SDK Interface' sidebar_order: 13 --- -An interface which describes the SDK used to capture and transmit the event. +An interface which describes the SDK and its configuration used to capture and +transmit the event. `name` -: The name of the SDK. +: **Required**. The name of the SDK. Its format is `sentry.ecosystem[.flavor]` +where the _flavor_ is optional and should only be set if it has its own SDK. `version` -: The version of the SDK. +: **Required**. The semantic version of the SDK. The version should always be +sent without a `v` prefix. + +`integrations` + +: _Optional_. A list of integrations with the platform or a framework that were +explicitly actived by the user. This does not include default integrations. + +`packages` + +: _Optional_. A list of packages that were installed as part of this SDK or the +activated integrations. Each package consists of a `name` in the format +`source:identifier` and a semver `version`. If the source is a git repository, +a checkout link and git reference (branch, tag or sha) should be used. + +## Example ```json "sdk": { - "name": "sentry-php", - "version": "1.0.0" + "name": "sentry.javscript.react-native", + "version": "1.0.0", + "integrations": [ + "redux" + ], + "packages": [ + { + "name": "npm:@sentry/react-native", + "version": "0.39.0" + }, + { + "name": "git:https://github.com/getsentry/sentry-cocoa.git", + "version": "4.1.0" + } + ] } ``` diff --git a/src/collections/_documentation/clientdev/overview.md b/src/collections/_documentation/clientdev/overview.md index 61498dd317676..9c01383c6b12c 100644 --- a/src/collections/_documentation/clientdev/overview.md +++ b/src/collections/_documentation/clientdev/overview.md @@ -1,5 +1,6 @@ --- title: Overview +sidebar_order: 1 --- The following is a guide for implementing a new Sentry SDK. It covers the protocol for event submission as well as guidelines for how clients should typically look and behave. @@ -25,7 +26,6 @@ Additionally, the following features are highly encouraged: - Automated error capturing (e.g. uncaught exception handlers) - Logging framework integration - Non-blocking event submission -- Basic data sanitization (e.g. filtering out values that look like passwords) - Context data helpers (e.g. setting the current user, recording breadcrumbs) - Event sampling - Honor Sentry’s HTTP 429 Retry-After header @@ -41,98 +41,73 @@ Generally, using an SDK consists of three steps for the end user, which should l 1. Creation of the SDK (sometimes this is hidden from the user): ```javascript - var myClient = new SentryClient('{DSN}'); + Sentry.init({dsn: '___DSN___'}); ``` + + ```python + sentry_sdk.init('___DSN___') + ``` + 2. Capturing an event: ```javascript - var resultId = myClient.captureException(myException); + var resultId = Sentry.captureException(myException); ``` -3. Using the result of an event capture: ```python - println('Your exception was recorded as %s', resultId); + result_id = sentry_sdk.capture_exception(my_exception); ``` +3. Using the result of an event capture: -The constructor ideally allows several configuration methods. The first argument should always be the DSN value (if possible), followed by an optional secondary argument which is a map of options: - -```javascript -client = new SentryClient('{DSN}', { - 'tags': {'foo': 'bar'} -}) -``` - -{% capture __alert_content -%} -If an empty DSN is passed, you should treat it as valid option which signifies disabling the SDK. -{%- endcapture -%} -{%- include components/alert.html - title="Note" - content=__alert_content -%} - -Which options you support is up to you, but ideally you would provide defaults for generic values that can be passed to the capture methods. - -Once you accept the options, you should output a logging message describing whether the SDK has been configured actively (as in, it will send to the remote server), or if it has been disabled. This should be done with whatever standard logging module is available for your platform. - -Additionally, you should provide methods (depending on the platform) which allow for capturing of a basic message and an exception-type: + ```javascript + alert(`Your exception was recorded as ${resultId}`); + ``` -- `SentryClient.captureMessage(message)` -- `SentryClient.captureException(exception)` + ```python + println('Your exception was recorded as %s', result_id); + ``` -The above methods should also allow optional arguments (or a map of arguments). For example: +`init` ideally allows several configuration methods. The first argument should always be the DSN value (if possible): ```javascript -client.captureException(myException, { - 'tags': {'foo': 'bar'}, +Sentry.init({ + 'dsn': '___DSN___', + 'foo': 'bar' }) ``` -If your platform supports block statements, it is recommended that you provide something like the following: - -``` -with client.captureExceptions(tags={'foo': 'bar'}): - # do something that will cause an error - 1 / 0 -``` - {% capture __alert_content -%} -In the above example, we’re passing any options that would normally be passed to the capture methods along with the block wrapper. +If an empty DSN is passed, you should treat it as valid option which signifies disabling the SDK. {%- endcapture -%} {%- include components/alert.html title="Note" content=__alert_content %} -Finally, provide a CLI to test your SDK’s configuration. Python example: +Additionally, you should provide global functions which allow for capturing of +a basic message or exception: -```bash -raven test {DSN} -``` - -Ruby example: - -```bash -rake raven:test {DSN} -``` +- `Sentry.captureMessage(message)` +- `Sentry.captureException(exception)` ## Parsing the DSN SDKs are encouraged to allow arbitrary options via the constructor, but must allow the first argument as a DSN string. This string contains the following bits: ``` -'{PROTOCOL}://{PUBLIC_KEY}:{SECRET_KEY}@{HOST}/{PATH}{PROJECT_ID}' +'{PROTOCOL}://{PUBLIC_KEY}:{SECRET_KEY}@{HOST}/{PROJECT_ID}' ``` The final endpoint you’ll be sending requests to is constructed per the following: ``` -'{URI}/api/{PROJECT ID}/store/' +'{URI}/api/{PROJECT_ID}/store/' ``` For example, given the following constructor: ```javascript -new SentryClient('https://public:secret@sentry.example.com/1') +Sentry.init({dsn: 'https://public:secret@sentry.example.com/1'}) ``` You should parse the following settings: @@ -149,7 +124,9 @@ The resulting POST request would then transmit to: ``` {% capture __alert_content -%} -If any of configuration values are not present, the SDK should notify the user immediately that they’ve misconfigured the SDK. +Note that the secret part of the DSN is optional and effectively deprecated at this point. While clients are +still supposed to honor it if supplied future versions of Sentry will entirely ignore it. The DSN parsing +code must not require the secret key to be set. {%- endcapture -%} {%- include components/alert.html title="Note" @@ -163,22 +140,27 @@ The body of the post is a string representation of a JSON object. For example, w ```json { "event_id": "fc6d8c0c43fc4630ad850ee518f1b9d0", - "culprit": "my.module.function_name", + "transaction": "my.module.function_name", "timestamp": "2011-05-02T17:41:36", "tags": { "ios_version": "4.0" }, - "exception": [{ + "exception": {"values":[{ "type": "SyntaxError", "value": "Wattttt!", "module": "__builtins__" - }] + }]} } ``` -The body of the event can carry attributes or interface values. The difference between them is that attributes are very barebones key/value pairs (for the most part) and interfaces are rich styled interface elements. Examples of attribute are `event_id` or `tags` whereas the `exception` key is an interface. +The body of the event can carry attributes or interface values. The difference +between them is that attributes are very barebones key/value pairs (for the +most part) and interfaces are rich styled interface elements. Examples of +attribute are `event_id` or `tags` whereas the `exception` key is an interface. -For a list of all supported attributes see [_Attributes_]({%- link _documentation/clientdev/attributes.md -%}). For a list of built-in interfaces see [_Interfaces_]({%- link _documentation/clientdev/interfaces/index.md -%}). +For a list of all supported attributes see [_Attributes_]({%- link +_documentation/clientdev/attributes.md -%}). For a list of built-in interfaces +see [_Interfaces_]({%- link _documentation/clientdev/interfaces/index.md -%}). ## Authentication @@ -192,6 +174,9 @@ X-Sentry-Auth: Sentry sentry_version=5, sentry_secret= ``` +The `secret_secret` must only be included if a secret key portion was contained in the DSN. Future versions +of the protocol will fully deprecate the secret key. + {% capture __alert_content -%} You should include the SDK version string in the User-Agent portion of the header, and it will be used if `sentry_client` is not sent in the auth header. {%- endcapture -%} @@ -230,13 +215,9 @@ In situations where it’s not possible to send the custom `X-Sentry-Auth` heade : The secret key which should be provided as part of the SDK configuration. - {% capture __alert_content -%} - You should only pass the secret key if you’re communicating via secure communication to the server. Client-side behavior (such as JavaScript) should use CORS, and only pass the public key. - {%- endcapture -%} - {%- include components/alert.html - title="Note" - content=__alert_content - %} + This key is effectively deprecated but for the time being should still be + emitted by SDKs as some older Sentry versions required it in most situations. + The secret key will be phased out entirely in future versions of Sentry. ## A Working Example @@ -263,11 +244,15 @@ X-Sentry-Auth: Sentry sentry_version=7, "culprit": "my.module.function_name", "timestamp": "2011-05-02T17:41:36", "message": "SyntaxError: Wattttt!", - "exception": [{ - "type": "SyntaxError", - "value": "Wattttt!", - "module": "__builtins__" - }] + "exception": { + "values": [ + { + "type": "SyntaxError", + "value": "Wattttt!", + "module": "__builtins__" + } + ] + } } ``` @@ -300,9 +285,7 @@ Client request error: Missing client version identifier ``` {% capture __alert_content -%} -The X-Sentry-Error header will always be present with the precise error message and it is the preferred way to identify the root cause. - -If it’s not available, it’s likely the request was not handled by the API server, or a critical system failure has occurred. +The X-Sentry-Error header will not always be present but it can be used to debug clients. When it can be emitted it will contain the precise error message. This header is a good way to identify the root cause. {%- endcapture -%} {%- include components/alert.html title="Note" @@ -311,68 +294,18 @@ If it’s not available, it’s likely the request was not handled by the API se ## Handling Failures -It is **highly encouraged** that your SDK handles failures from the Sentry server gracefully. This means taking care of several key things: - -- Soft failures when the Sentry server fails to respond in a reasonable amount of time (e.g. 3s) -- Exponential backoff when Sentry fails (don’t continue trying if the server is offline) -- Failover to a standard logging module on errors. - -For example, the Python SDK will log any failed requests to the Sentry server to a named logger, `sentry.errors`. It will also only retry every few seconds, based on how many consecutive failures its seen. The code for this is simple: - -```python -def should_try(self): - if self.status == self.ONLINE: - return True - interval = min(self.retry_number, 6) ** 2 - return time.time() - self.last_check > interval -``` - -## Tags - -Tags are key/value pairs that describe an event. They should be configurable in the following contexts: - -- Environment (SDK-level) -- Thread (block-level) -- Event (as part of capture) - -Each of these should inherit its parent. So for example, if you configure your SDK as so: - -```python -client = Client(..., { - 'tags': {'foo': 'bar'}, -}) -``` - -And then you capture an event: - -```python -client.captureMessage('test', { - 'tags': {'foo': 'baz'}, -}) -``` - -The SDK should send the following upstream for `tags`: - -```python -{ - "tags": [ - ["foo", "bar"], - ["foo", "baz"] - ], -} -``` - -## Contextual Data +It is **highly encouraged** that your SDK handles failures from the Sentry server gracefully. SDKs are expected to honor the 429 status code and to not try sending until the retry-after kicks in. It's acceptable for SDKs to drop events if Sentry is unavailable instead of retrying. -You should also provide relevant contextual interfaces. These should last for the lifecycle of a request, and the general interface is “bind some kind of context”, and then at the end of a request lifecycle, clear any present context. +## Concurrency (Scope and Hubs) -This interface consists of _*_context_ methods, access to the _context_ dictionary as well as a _clear_ and _merge_ context method. Method methods exist usually depend on the SDK. The following methods generally make sense: +SDKs are supposed to provide standardized concurrency handling through the +concept of hubs and scopes. This is explained in more details in the +[_Concurrency_]({%- link _documentation/clientdev/unified-api.md -%}#concurrency) chapter of the unified API docs. -- `client.user_context` -- `client.tags_context` -- `client.http_context` -- `client.extra_context` -- `client.context.merge` -- `client.context.clear` +## Layer of Integratiom -For more information about this (specifically about how to deal with concurrency) please make sure to read [_Context Management_]({%- link _documentation/clientdev/context.md -%}). +SDKs when possible are supposed to integrate on a low level which will capture as much of the runtime +as possible. This means that if an SDK can hook the runtime or a framework directly this is preferred +over requiring users to subclass specific base classes (or mix in helpers). For instance the Python +SDK will monkey patch core functionality in frameworks to automatically pick up on errors and to integrate +scope handling. diff --git a/src/collections/_documentation/clientdev/unified-api.md b/src/collections/_documentation/clientdev/unified-api.md new file mode 100644 index 0000000000000..486a1d7c4b181 --- /dev/null +++ b/src/collections/_documentation/clientdev/unified-api.md @@ -0,0 +1,168 @@ +--- +title: 'Unified API' +sidebar_order: 2 +--- + +New Sentry SDKs should follow the unified API, use consistent terms to refer to concepts. This +documentation explains what the unified API is and why it exits. + +## Motivation + +Sentry has a wide range of SDKs that have been developed over the years by different developers +and based on different ideas. This has lead to the situation that the feature sets across the +SDKs are different, use different concepts and terms which has lead to the situation that it's +often not clear how to achive the same thing on different platforms. + +Additionally those SDKs were purely centered around error reporting through explicit clients which +meant that certain integrations (such as breadcrumbs) were often not possible. + +## Terminology + +- **minimal**: A separate "facade" package that re-exports a subset of the SDK's functionality through interfaces or proxies. That package does not directly depend on the SDK, instead it should make every operation a noop if the SDK is not installed. + + The purpose of such a package is to allow random libraries to record breadcrumbs and set context data while not having a hard dependency on the SDK. + +- **hub**: An object that manages the state. An implied global thread local or similar hub exists that can be used by default. Hubs can be created manually. + +- **scope**: A scope holds data that should implicitly be sent with sentry events. It can hold context data, extra parameters, level overrides, fingerprints etc. + +- **client**: A client is an object that is configured once and can be bound to the hub. The user can then auto discover the client and dispatch calls to it. Users typically do not need to work with the client directly. They either do it via the hub or static convenience functions. + +- **client options**: Are parameters that are language and runtime specific and used to configure the client. This can be release and environment but also things like which integrations to configure, how in-app works etc. + +- **context**: Contexts give extra data to sentry. There are the special contexts (user and similar) and the generic ones (runtime, os, device) etc. Check out [_Contexts_]({%- link _documentation/clientdev/interfaces/contexts.md -%}) for valid keys. *Note: In older SDKs you might encounter an unrelated concept of context, which is now deprecated by scopes* + +- **tags**: Tags can be arbitrary string→string pairs by which events can be searched. Contexts are converted into tags. + +- **extra**: Truly arbitrary data attached by client users. + +- **transport**: The transport is an internal construct of the client that abstracts away the event sending. Typically the transport runs in a separate thread and gets events to send via a queue. The transport is responsible for sending, retrying and handling rate limits. The transport might also persist unsent events across restarts if needed. + +- **integration**: Code that provides middlewares, bindings or hooks into certain frameworks or environments, along with code that inserts those bindings and activates them. Usage for integrations does not follow a common interface. + +## "Static API" + +The static API functions is the most common user facing API. A user just imports these functions and can start +emitting events to sentry or configuring scopes. These shortcut functions should be exported in the top-level +namespace of your package. Behind the scenes they use scopes use hubs and scopes (see [Concurrency](#concurrency) for more information) if available on that platform: + +- `capture_event(event, hint)`: Takes an already assembled event and dispatches it to the currently active hub. The event object can be a plain dictionary or a typed object whatever makes more sense in the SDK. It should follow the native protocol as close as possible ignoring platform specific renames (case styles etc.). + + For the hint parameter see [hints](#hints). + +- `capture_exception(error)`: Report an error or exception object. Depending on the platform different parameters are possible. The most obvious version accepts just an error object but also variations are possible where no error is passed and the current exception is used. + +- `capture_message(message, level)`: Reports a message. The level can be optional in language with default parameters in which case it should default to `info`. + +- `add_breadcrumb(crumb, hint)`: Adds a new breadcrumb to the scope. If the total number of breadcrumbs exceeds the `max_breadcrumbs` setting, the oldest breadcrumb should be removed in turn. This works like the Hub api with regards to what `crumb` can be. + + For the hint parameter see [hints](#hints). + +- `configure_scope(callback)`: Calls a callback with a scope object that can be reconfigured. This is used to attach contextual data for future events in the same scope. + +- `last_event_id()`: Should return the last event ID emitted by the current scope. This is for instance used to implement user feedback dialogs. + +## Concurrency + +All SDKs should have the concept of concurrency safe context storage. What this means depends on the language. The basic idea is that a user of the SDK can call a method to safely provide additional context information for all events that are about to be recorded. + +This is implemented as a thread local stack in most languages, but in some (such as JavaScript) it might be global under the assumption that this is something that makes sense in the environment. + +Here are some common concurrench patterns: + +* **Thread bound hub**: in that pattern each thread gets its own "hub" which internally manages a stack of scopes. If that pattern is followed one thread (the one that calls `init()`) becomes the "main" hub which is used as the based for newly spawned threads which will get a hub that is based on the main hub (but otherwise independent). + +* **Internally scoped hub**: On some platforms such as .NET ambient data is available in which case the Hub can internally manage the scopes. + +* **Dummy hub**: On some platforms concurrency just doesn't inherently exists. In that case the hub might be entirely absent or just be a singleton without concurrenty management. + +## Hub + +Under normal circumstances the hub consists of a client and a stack of scopes. + +The SDK maintains two variables: The *main hub* (a global variable) and the *current hub* (a variable local to the current thread or execution context, also sometimes known as async local or context local) + +The `init()` you saw in the [_Overview_]({%- link _documentation/clientdev/overview.md -%}) typically creates / reinitializes the global hub which is propagated to all new threads/execution contexts, or a hub is created per thread/execution context. + +- `Hub::new(client, scope)`: Creates a new hub with the given client and scope. The client can be reused between hubs. The scope should be owned by the hub (make a clone if necessary) + +- `Hub::new_from_top(hub)` / alternatively native constructor overloads: Creates a new hub by cloning the top stack of another hub. + +- `get_current_hub()` / `Hub::current()` / `Hub::get_current()`: Global function or static function to return the current (threads) hub + +- `get_main_hub()` / `Hub::main()` / `Hub::get_main()`: In languages where the main thread is special ("Thread bound hub" model) this returns the main thread’s hub instead of the current thread’s hub. This might not exist in all languages. + +- `Hub::capture_event` / `Hub::capture_message` / `Hub::capture_exception` Capture message / exception call into capture event. `capture_event` merges the event passed with the scope data and dispatches to the client. + +- `Hub::push_scope()`: Pushes a new scope layer that inherits the previous data. This should return a disposable or stack guard for languages where it makes sense. When the "internally scoped hub" concurrency model is used calls to this are often necessary as otherwise a scope might be accidentally incorrectly shared. + +- `Hub::with_scope(func)` (optional): In Python this could be a context manager, in Ruby a block function. Pushes and pops a scope for integration work. + +- `Hub::pop_scope()` (optional): Only exists in languages without better resource management. Better to have this function on a return value of `push_scope` or to use `with_scope`. This is also sometimes called `pop_scope_unsafe` to indicate that this method should not be used directly. + +- `Hub::configure_scope(callback)`: Invokes the callback with a mutable reference to the scope for modifiations This can also be a `with` statement in languages that have it (Python). + +- `Hub::add_breadcrumb(crumb, hint)`: Adds a breadcrumb to the current scope. + + - The argument supported should be: + - function that creates a breadcrumb + - an already created breadcrumb object + - a list of breadcrumbs optionally + - In languages where we do not have a basic form of overloading only a raw breadcrumb object should be accepted. + + For the hint parameter see [hints](#hints). + +- `Hub::client()` / `Hub::get_client()` (optional): Accessor or getter that returns the current client or `None`. + +- `Hub::bind_client(new_client)`: Binds a different client to the hub. If the hub is also the owner of the client that was created by `init` it needs to keep a reference to it still if the hub is the object responsible for disposing it. + +- `Hub::unbind_client()` (optional): Optional way to unbind for languages where `bind_client` does not accept nullables. + +- `Hub::last_event_id()`: Should return the last event ID emitted by the current scope. This is for instance used to implement user feedback dialogs. + +- `Hub::run(hub, callback)` `hub.run(callback)`, `run_in_hub(hub, callback)` (optional): Runs a callback with the hub bound as the current hub. + +### Scope + +A scope holds data that should implicitly be sent with sentry events. It can hold context data, extra parameters, level overrides, fingerprints etc. + +The user should be able to modify the current scope easily (to set extra, tags, current user), through a global function `configureScope`. `configure_scope` takes a callback function to which it passes the current scope. Here's an example from another place in the docs: + +```javascript +Sentry.configure_scope((scope) => { + scope.setExtra("character_name": "Mighty Fighter"); +}); +``` + +Why not just have a `get_current_scope()` function instead of this indirection? If the SDK is disabled (e.g. by not providing a DSN), modifying a scope is pointless because there will never be any events to send. In that situation `configure_scope` may choose not to call the callback. This is also used to more efficiently flush out scope changes in some languages. When a `with` statement is used that always executes the scope needs to be a dummy scope object. + +- `scope.set_user(data)`: Shallow merges user configuration (`email`, `username`, …). Removing user data is SDK-defined, either with a `remove_user` function or by passing nothing as data. + +- `scope.set_extra(key, value)`: Sets the extra key to an arbitrary value, overwriting a potential previous value. Removing a key is SDK-defined, either with a `remove_extra` function or by passing nothing as data. + +- `scope.set_tag(key, value)`: Sets the tag to a string value, overwriting a potential previous value. Removing a key is SDK-defined, either with a `remove_tag` function or by passing nothing as data. + +- `scope.set_context(key, value)`: Sets the context key to a value, overwriting a potential previous value. Removing a key is SDK-defined, either with a `remove_context` function or by passing nothing as data. The types are sdk specified. + +- `scope.set_fingerprint(fingerprint[])`: Sets the fingerprint to group specific events together + +- `scope.add_event_processor(processor)`: Registers an event processor function. It takes an event and returns a new event or `None` to drop it. This is the basis of many integrations. + +- `scope.add_error_processor(processor)`: Registers an error processor function. It takes an event and exception object and returns a new event or `None` to drop it. This can be used to extract additional information out of an exception object that the SDK cannot extract itself. + +- `scope.clear()`: resets a scope to default values (prevents inheriting). This never clears registered event processors. + +- `scope.apply_to_event(event[, max_breadcrumbs])`: Applies the scope data to the given event object. This also applies the event processors stored in the scope internally. Some implementations might want to set a max breadcrumbs count here. + +## Hints + +Optionally a second parameter is supported to event capturing and breadcrumb adding: a hint. + +A hint is SDK specific but provides high level information about the origin of +the event. For instance if an exception was captured the hint might carry the +original exception object. Not all SDKs are required to provide this. The +parameter however is reserved for this purpose. + +## Options + +Many options are standardized across SDKs. For a list of these refer to [the main options documentation]({% link _documentation/learn/configuration.md %}). diff --git a/src/collections/_documentation/clients/cocoa/dsym.md b/src/collections/_documentation/clients/cocoa/dsym.md index 323561e972f5b..8bc0341f11b26 100644 --- a/src/collections/_documentation/clients/cocoa/dsym.md +++ b/src/collections/_documentation/clients/cocoa/dsym.md @@ -95,6 +95,7 @@ api_host: 'https://mysentry.invalid/' content=__alert_content %} + ### Upload Symbols with _sentry-cli_ Your project’s dSYM can be upload during the build phase as a “Run Script”. For this you need to st the _DEBUG_INFORMATION_FORMAT_ to be _DWARF with dSYM File_. By default, an Xcode project will only have _DEBUG_INFORMATION_FORMAT_ set to _DWARF with dSYM File_ in _Release_ so make sure everything is set in your build settings properly. @@ -133,6 +134,7 @@ export SENTRY_URL=https://mysentry.invalid/ title="On Prem" content=__alert_content %} + ### Manually with _sentry-cli_ diff --git a/src/collections/_documentation/clients/cocoa/index.md b/src/collections/_documentation/clients/cocoa/index.md index 29820c98de883..93df0998cf048 100644 --- a/src/collections/_documentation/clients/cocoa/index.md +++ b/src/collections/_documentation/clients/cocoa/index.md @@ -1,10 +1,12 @@ --- title: Cocoa sidebar_order: 1 +sidebar_relocation: platforms --- This is the documentation for our official clients for Cocoa (Swift and Objective-C). Starting with version `3.0.0` we’ve switched our interal code from Swift to Objective-C to maximize compatiblity. Also we trimmed the public API of our sdk to a minimum. Some of the lesser used features that where present before are gone now, check out [Migration Guide]({%- link _documentation/clients/cocoa/migration.md -%}#migration) or [Advanced Usage]({%- link _documentation/clients/cocoa/advanced.md -%}#advanced) for details. + ## Installation The SDK can be installed using [CocoaPods](http://cocoapods.org) or [Carthage](https://github.com/Carthage/Carthage). This is the recommended client for both Swift and Objective-C. @@ -84,7 +86,7 @@ Before you can start capturing crashes you will need to tell Sentry about the de - [With Bitcode]({%- link _documentation/clients/cocoa/dsym.md -%}#dsym-with-bitcode) - [Without Bitcode]({%- link _documentation/clients/cocoa/dsym.md -%}#dsym-without-bitcode) - + ## Testing a Crash If you would like to test the crash reporting you will need to cause a crash. While, the seemingly obvious method would be make it crash on launch, this will not give the Sentry client a chance to actually submit the crash report. Instead, we recommend triggering a crash from a button tap. diff --git a/src/collections/_documentation/clients/csharp/index.md b/src/collections/_documentation/clients/csharp/index.md index c8c40d2052433..f01d5d7ac6ae1 100644 --- a/src/collections/_documentation/clients/csharp/index.md +++ b/src/collections/_documentation/clients/csharp/index.md @@ -4,6 +4,7 @@ title: 'C#' Raven is the C# client for Sentry. Raven relies on the most popular logging libraries to capture and convert logs before sending details to a Sentry instance. + ## Installation A [NuGet Package](https://www.nuget.org/packages/SharpRaven) is available for SharpRaven if you don’t want to compile it yourself. @@ -29,6 +30,7 @@ catch (Exception exception) ravenClient.Capture(new SentryEvent(exception)); } ``` + ## Logging Non-Exceptions diff --git a/src/collections/_documentation/clients/electron/config.md b/src/collections/_documentation/clients/electron/config.md deleted file mode 100644 index 2f70456818e88..0000000000000 --- a/src/collections/_documentation/clients/electron/config.md +++ /dev/null @@ -1,229 +0,0 @@ ---- -title: Configuration ---- - -To get started, you need to initialize the Electron SDK and declare your Sentry DSN: - -```javascript -const { init } = require('@sentry/electron'); -init({ dsn: '___PUBLIC_DSN___' }); -``` - -This code snippet has to be executed in every process you start in Electron. Besides the main process, this includes renderers and other sub processes. Be sure to initilalize the SDK as early as possible, so it can also catch errors that happen during startup. - -We recommend to put the initialization in a separate JavaScript module, to keep configuration options consistent. This also allows to use it as preload script when creating new `BrowserWindow` instances: - -```javascript -mainWindow = new BrowserWindow({ - width: 800, - height: 600, - webPreferences: { - preload: path.join(__dirname, 'sentry.js') - } -}); -``` - -After this, the SDK is ready to capture any uncaught exception and native crashes that occur in those processes. - -## Node Integration - -The SDK requires some NodeJS APIs to operate properly. When creating windows without Node integration, the SDK must be loaded in a preload script, as described above. Doing so also ensures that the SDK is loaded as early as possible. - -```javascript -mainWindow = new BrowserWindow({ - width: 800, - height: 600, - webPreferences: { - nodeIntegration: false, - preload: path.join(__dirname, 'sentry.js') - } -}); -``` - -## Sandbox Mode - -[Sandbox mode](https://electronjs.org/docs/api/sandbox-option) fully isolates the renderer processes from the operating system using OS-specific methods. Since most node APIs require system access, they are not available in sandbox mode, most notably `require()`. See the linked documentation for a detailed description of sandbox restrictions. - -The Electron SDK can still be used from within a preload script. However, it needs to be bundled into a single file using bundlers like Webpack or Rollup due to the missing `require()` function. Please refer to the respective documentation your chosen tool for all possible configuration options. - -The SDK is written in a way that prevents bundlers from processing any code that is only meant to be executed in the main process. The only remaining external dependency is `electron`, which must be explicitly excluded from inlining. For Webpack, this would be: - -```javascript -module.exports = { - externals: { - electron: 'commonjs electron', - }, - // ... -}; -``` - -Or for Rollup: - -```javascript -export default { - external: ['electron'], - plugins: [commonjs()], - // ... -}; -``` - -## Options - -To customize SDK behavior, simply pass additional options to the `init()` call. All available options are documented below: - -`enableJavaScript` - -: Enables JavaScript error reporting. Default: `true` - - Based on the process type, this configures our JavaScript SDKs with sane defaults. In the main process (`process.type: 'browser'`), it uses the Node SDK. In renderer processes (`process.type: 'renderer'`), it uses the JavaScript SDK. - - If you need to use a specific configuration option of one of these SDKs, you can include it in the options object directly, as it will be passed down by `init`. - - ```javascript - { - enableJavaScript: true - } - ``` - -`enableNative` - -: Enables reporting of native crashes. Default: `true` - - This enables and configures the [Electron CrashReporter](https://electronjs.org/docs/api/crash-reporter) to generate memory dumps when the app or a renderer crashes. Those dumps will be uploaded to Sentry for processing once the app restarts. Metadata, such as context information or breadcrumbs are automatically included. - - For more information on native crashes, see [_Native Usage_]({%- link _documentation/clients/electron/native.md -%}). - - ```javascript - { - enableNative: true - } - ``` - -`release` - -: Explicitly set the version of your application to track it in Sentry. - - Note that the release ID must be unique within your organization. This is required to enable proper source map support. For more information, see [_Source Maps_]({%- link _documentation/clients/electron/sourcemaps.md -%}). - - ```javascript - { - release: '721e41770371db95eee98ca2707686226b993eda' - } - ``` - -`environment` - -: Track the application environment in Sentry. - - This can be useful to distinguish prereleases and special builds from production apps. This works similar to tags. - - ```javascript - { - environment: 'production' - } - ``` - -`maxBreadcrumbs` - -: Set the maximum number of breadcrumbs captured by default. You can increase this to be as high as `100`. Defaults to `30` - - Note that breadcrumbs are kept in memory and periodically flushed in a cache file. This way, breadcrumbs can even be included when the entire application crashes. However, in very high-concurrency situations there is potential for significant memory and disk usage. If you find your application to generate large breadcrumbs, consider reducing `maxBreadcrumbs` the option. - - ```javascript - { - maxBreadcrumbs: 20 - } - ``` - -`shouldSend` - -: A callback invoked during event submission, allowing to cancel it. If unspecified, all events will be sent to Sentry. - - This function is called for both captured errors and messages before all other callbacks. Note that the SDK might perform other actions after calling this function. Use `beforeSend` for notifications on events instead. - - ```javascript - { - shouldSend: function (data) { - return Math.random() > 0.5; - } - } - ``` - -`beforeSend` - -: A callback function that allows mutation of the event payload right before being sent to Sentry. - - This function is called after `shouldSend` and immediately precedes the actual event submission. You must return valid event payload from this callback. If you wish to cancel event submission instead, use `shouldSend`. - - ```javascript - { - beforeSend: function (data) { - // add a user context - data.user = { - id: 1337, - name: 'janedoe', - email: 'janedoe@example.com' - }; - return data; - } - } - ``` - -`afterSend` - -: A callback invoked after the event has been submitted. The second parameter contains a status that indicates whether submission was successful. - - ```javascript - { - afterSend: function (data, status) { - // status can be one of: - // - "unknown": The status could not be determined - // - "skipped": The event was skipped due to configuration or callbacks - // - "success": The event was sent to Sentry successfully - // - "rate_limit": The client is currently rate limited and will try again later - // - "invalid": The event could not be processed - // - "failed": A server-side error ocurred during submission - } - } - ``` - -`shouldAddBreadcrumb` - -: A callback allowing to skip breadcrumbs. - - This function is called for both manual and automatic breadcrumbs before all other callbacks. Note that the SDK might perform other actions after calling this function. Use `beforeBreadcrumb` for notifications on breadcrumbs instead. - - ```javascript - { - shouldAddBreadcrumb: function (data) { - return Math.random() > 0.5; - } - } - ``` - -`beforeBreadcrumb` - -: A callback function that allows mutation of the breadcrumb before adding it. - - This function is called after `shouldAddBreadcrumb`. You must return valid breadcrumb from this callback. If you wish to omit this breadcrumb instead, use `shouldAddBreadcrumb`. - - ```javascript - { - beforeBreadcrumb: function (data) { - data.level = "fatal"; - return data; - } - } - ``` - -`afterBreadcrumb` - -: A callback invoked after a breadcrumb has been added. - - ```javascript - { - afterBreadcrumb: function (data) { - // ... - } - } - ``` diff --git a/src/collections/_documentation/clients/electron/javascript.md b/src/collections/_documentation/clients/electron/javascript.md deleted file mode 100644 index c4f39045a08bf..0000000000000 --- a/src/collections/_documentation/clients/electron/javascript.md +++ /dev/null @@ -1,175 +0,0 @@ ---- -title: 'JavaScript Usage' -sidebar_order: 1 ---- - -Using Sentry from JavaScript code works exactly the same as in any other JavaScript environment. However, the Electron SDK conveniently configures the right SDK when you initialize it: - -- In the main process, it uses the _Node SDK_. -- In renderers, it uses the _Browser SDK_. - -{% capture __alert_content -%} -There is no need to include `@sentry/node` or `@sentry/browser` in addition to the Electron SDK. It includes all their features and even configures them with sane defaults. If you prefer to override some of their settings, you can specify them in addition to the options listed in [_Configuration_]({%- link _documentation/clients/electron/config.md -%}) when calling `init()`. -{%- endcapture -%} -{%- include components/alert.html - title="Tip" - content=__alert_content -%} - -In this document, we assume that the entire SDK is imported into a `Sentry` variable and in scope. Depending on your language level, you might need different syntax for this: - -```javascript -// Node -const Sentry = require('@sentry/electron'); - -// ES2015+ -import * as Sentry from '@sentry/electron'; - -// TypeScript -import * as Sentry from '@sentry/electron'; -``` - -## Reporting Correctly - -By default, the Electron SDK tries to capture meaningful stack traces, but the concurrent Electron’s processes make this difficult. The easiest solution is to prevent errors from bubbling all the way up the stack. - -Depending on the circumstances, there are different methods to report errors: - -### try … catch - -The simplest way, is to try and explicitly capture and report potentially problematic code with a `try...catch` block and `captureException`. - -```javascript -try { - doSomething(a[0]); -} catch(e) { - captureException(e); -} -``` - -{% capture __alert_content -%} -Always throw an actual `Error` object. It’s impossible to retrieve a stack trace from a string. If this happens, the SDK transmits the error as a plain message. For example: - -```javascript -throw new Error('broken'); // good -throw 'broken'; // bad -``` -{%- endcapture -%} -{%- include components/alert.html - title="Do not throw strings!" - content=__alert_content -%} - -### Custom Messages - -If you wish to send a non-error event instead, use `captureMessage`. This will show up with a different level in Sentry: - -```javascript -Sentry.captureMessage('My custom event'); -``` - -## Tracking Users - -While a user is logged in, you can tell Sentry to associate errors with user data: - -```javascript -Sentry.configureScope(scope => { - scope.setUser({ - id: '42', - email: 'user@example.org' - }); -}); -``` - -This data is generally submitted with each error or message and allows you to figure out which users are affected by problems. If at any point the user becomes unauthenticated, call `scope.setUser({})` with an empty object to remove their data. - -## Tagging Events - -Sentry allows to filter and search for issues by tags. You can set global tags to be merged in with future exceptions or messages via `scope.setTag`: - -```javascript -Sentry.configureScope(scope => { - scope.setTag('key', 'value'); -}); -``` - -Tags given in `scope.setTag` are merged with existing tags. If you need to remove a tag, then set it explicitly to `null` or `undefined`. - -## Passing Additional Data - -In addition to user context and tags, you can pass arbitrary to associate with future events. Note that the objects you pass in must be JSON-serializable: - -```javascript -Sentry.configureScope(scope => { - scope.setExtra('my', {data: 2}); -}); -``` - -Data given in `scope.setExtra` is shallow-merged with existing extras. To remove a top-level key from extras, explicitly set it to `null` or `undefined`. - -## Recording Breadcrumbs - -Breadcrumbs are browser and application lifecycle events that are helpful in understanding the state of the application leading up to a crash. - -In renderers, the SDK instruments browser built-ins and DOM events to automatically collect a few useful breadcrumbs for you: - -- fetch and XMLHttpRequests -- URL / address bar changes -- UI clicks and keypress DOM events -- console log statements -- previous errors - -In the main process, the SDK also automatically captures breadcrumbs for: - -- HTTP/HTTPS requests -- console log statements - -You can also record your own breadcrumbs: - -```javascript -Sentry.addBreadcrumb({ - message: 'Item added to shopping cart', - category: 'action', - data: { - isbn: '978-1617290541', - cartSize: '3' - } -}); -``` - -For more on configuring breadcrumbs, see [_Configuration_]({%- link _documentation/clients/electron/config.md -%}). To learn more about what types of data can be collected via breadcrumbs, see the [breadcrumbs client API specification]({%- link _documentation/learn/breadcrumbs.md -%}). - -## Receiving Source Context - -The Electron SDK supports [Source Maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). If you upload source maps in addition to your minified files that data becomes available in Sentry. This applies to the main process as well as renderer processes. For more information see [_Source Maps_]({%- link _documentation/clients/electron/sourcemaps.md -%}). - -{% capture __alert_content -%} -Without uploading sourcemaps or source code to Sentry, you might not see source context in issues at all. In the main process, the SDK will try to read source files from the app, but this process will not work in renderers necessarily. -{%- endcapture -%} -{%- include components/alert.html - title="Note" - content=__alert_content -%} - -## Uncaught Exceptions - -The default behavior for dealing with globally unhandled exceptions and Promise rejections differs by process. - -In the main process, such unhandled errors Sentry will capture before showing the default dialog electron always shows. To override this behavior, declare a custom `onFatalError` callback when configuring the SDK, for example if you want your app to exit do: - -```javascript -Sentry.init({ - dsn: '___PUBLIC_DSN___', - onFatalError: function (err) { - if (!sendErr) { - console.log('Successfully sent fatal error to Sentry:'); - console.error(err.stack); - } - - console.log('This is thy sheath; there rust, and let me die.'); - process.exit(1); - } -}); -``` - -Renderer processes do not crash on unhandled errors and there is no `onFatalError` configuration option. Instead, the SDK automatically captures them and sends them to Sentry. This also applies to Promises and polyfills that report a global `unhandledrejection` DOM event. diff --git a/src/collections/_documentation/clients/electron/sourcemaps.md b/src/collections/_documentation/clients/electron/sourcemaps.md deleted file mode 100644 index f6062fbef2a5c..0000000000000 --- a/src/collections/_documentation/clients/electron/sourcemaps.md +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: 'Source Maps' -sidebar_order: 3 ---- - -Sentry supports un-minifying JavaScript via Source Maps. This lets you view source code context obtained from stack traces in their original form, which is particularly useful for debugging minified code (e.g. UglifyJS), or transpiled code from a higher-level language (e.g. TypeScript). - -Even when using plain JavaScript, you must upload your source files to allow Sentry to display source context for stack traces from renderer processes. This is caused by restrictions of [sandboxing](https://electronjs.org/docs/api/sandbox-option) or disabling Node integration. - -## Specifying the Release - -To upload source map artifacts to Sentry, you have to specify the `release` in the SDK configuration and during the upload. Releases are global within your organization and might incorporate multiple of your projects. To isolate it, prefix the release version with an App id. Sentry will use this release name to associate digested event data with the files you’ve uploaded. - -```javascript -Sentry.init({ - dsn: '___PUBLIC_DSN___', - release: 'myapp-1.2.3' -}); -``` - -## Generating Source Maps - -Most modern JavaScript transpilers support source maps. Below are instructions for common tools. - -To allow Sentry to match source code references to uploaded source maps or source files, make sure your tool outputs files relative to your project root folder and prefixes them either with `/` or with `~/`. Some tools do this automatically (e.g. Webpack), or have a configuration option (e.g. TypeScript). For others, please see the section on rewriting source maps before uploading. - -The SDK will rewrite stack traces before sending them to Sentry. If your application generates manual stack traces for some reason, make sure stack frames always contain relative paths from the project root starting with `~/` or `app:///`. - -### UglifyJS - -UglifyJS is a popular tool for minifying your source code for production. It can dramatically reduce the size of your files by eliminating whitespace, rewriting variable names, removing dead code branches, and more. - -If you are using UglifyJS to minify your source code, the following command will additionally generate a source map that maps the minified code back to the original source: - -```sh -$ uglifyjs app.js \ - -o app.min.js.map \ - --source-map url=app.min.js.map,includeSources -``` - -### Webpack - -Webpack is a powerful build tool that resolves and bundles your JavaScript modules into files fit for running in the browser. It also supports various _loaders_ to transpile higher-level languages, reference stylesheets, or include static assets. - -We have created a convenient [webpack plugin](https://github.com/getsentry/sentry-webpack-plugin) that configures source maps and uploads them to Sentry during the build. This is the recommended way for uploading sources to Sentry. First, install the plugin via: - -```sh -$ npm install --save-dev @sentry/webpack-plugin -$ yarn add --dev @sentry/webpack-plugin -``` - -To allow the plugin to upload source maps automatically, create a `.sentryclirc` or configure environment variables as described in the [CLI configuration docs]({%- link _documentation/learn/cli/configuration.md -%}). Then, add the plugin to your `webpack.config.js`: - -```javascript -const SentryWebpackPlugin = require('@sentry/webpack-plugin'); - -module.exports = { - // other configuration - plugins: [ - new SentryWebpackPlugin({ - include: '.', - ignoreFile: '.sentrycliignore', - ignore: ['node_modules', 'webpack.config.js'], - configFile: 'sentry.properties' - }) - ] -}; -``` - -Alternatively, if you prefer to upload source maps manually, Webpack just needs to be configured to output source maps: - -```javascript -module.exports = { - output: { - path: path.join(__dirname, 'dist'), - filename: "[name].js", - sourceMapFilename: "[name].js.map" - } - // other configuration -}; -``` - -{% capture __alert_content -%} -In case you use [SourceMapDevToolPlugin](https://webpack.js.org/plugins/source-map-dev-tool-plugin) for more fine grained control of source map generation, leave `noSources` turned off, so Sentry can display proper source code context in event stack traces. -{%- endcapture -%} -{%- include components/alert.html - title="Note" - content=__alert_content -%} - -### TypeScript - -The TypeScript compiler can output source maps. Configure the `sourceRoot` property to `/` to strip the build path prefix from generated source code references. This allows Sentry to match source files relative to your source root folder: - -```json -{ - "compilerOptions": { - "sourceMap": true, - "inlineSources": true, - "sourceRoot": "/" - } -} -``` - -## Uploading Source Maps to Sentry - -Except for webpack, the recommended way to upload source maps is using [Sentry CLI]({%- link _documentation/learn/cli/index.md -%}). If you have used _Sentry Wizard_ to set up your project, it has already created all necessary configuration to upload source maps. Otherwise, follow the [CLI configuration docs]({%- link _documentation/learn/cli/configuration.md -%}) to set up your project. - -Sentry uses **Releases** to match the correct source maps to your events. To create a new release, run the following command (e.g. during publishing): - -```sh -$ sentry-cli releases new -``` - -Note the release name must be **unique within your organization** and match the `release` option in your SDK initialization code. Then, use the `upload-sourcemaps` command to scan a folder for source maps, process them and upload them to Sentry: - -```sh -$ sentry-cli releases files upload-sourcemaps /path/to/files -``` - -This command will upload all files ending in _.js_ and _.map_ to the specified release. If you wish to change these extensions – e.g. to upload typescript sources – use the `--ext` option: - -```sh -$ sentry-cli releases files upload-sourcemaps --ext ts,map /path/to/files -``` - -{% capture __alert_content -%} -Unfortunately, it can be quite challenging to ensure that source maps are actually valid and uploaded correctly. To ensure that everything is working as intended, you can add the `--validate` flag when uploading source maps. It attempts to parse the source maps and verify source references locally. Note that this flag might produce false positives if you have references to external source maps. -{%- endcapture -%} -{%- include components/alert.html - title="Validating Sourcemaps with Sentry CLI" - content=__alert_content -%} - -Until now, the release is in a draft state (“_unreleased_”). Once all source maps have been uploaded and your app has been published successfully, finalize the release with the following command: - -```sh -$ sentry-cli releases finalize -``` - -For convenience, you can alternatively pass the `--finalize` flag to the `new` command which will immediately finalize the release. diff --git a/src/collections/_documentation/clients/elixir/index.md b/src/collections/_documentation/clients/elixir/index.md index 7c7bdb7c75d7c..fe2350298302f 100644 --- a/src/collections/_documentation/clients/elixir/index.md +++ b/src/collections/_documentation/clients/elixir/index.md @@ -1,10 +1,12 @@ --- title: Elixir sidebar_order: 4 +sidebar_relocation: platforms --- The Elixir SDK for Sentry. + ## Installation Edit your mix.exs file to add it as a dependency and add the `:sentry` package to your applications: @@ -63,6 +65,7 @@ If using an environment with Plug or Phoenix add the following to your router: use Plug.ErrorHandler use Sentry.Plug ``` + ## Filtering Events diff --git a/src/collections/_documentation/clients/elixir/usage.md b/src/collections/_documentation/clients/elixir/usage.md index 8edbd929863b6..691d5c02abf6b 100644 --- a/src/collections/_documentation/clients/elixir/usage.md +++ b/src/collections/_documentation/clients/elixir/usage.md @@ -3,6 +3,7 @@ title: Usage sidebar_order: 1 --- + ## Capturing Errors If you use the error logger and setup Plug/Phoenix then you are already done, all errors will bubble up to sentry. @@ -17,6 +18,7 @@ rescue Sentry.capture_exception(my_exception, [stacktrace: System.stacktrace(), extra: %{extra: information}]) end ``` + ## Optional Attributes diff --git a/src/collections/_documentation/clients/go/index.md b/src/collections/_documentation/clients/go/index.md index 8b7f9acd0b21d..f1d0f7fd01553 100644 --- a/src/collections/_documentation/clients/go/index.md +++ b/src/collections/_documentation/clients/go/index.md @@ -1,6 +1,7 @@ --- title: Go sidebar_order: 5 +sidebar_relocation: platforms --- {% capture __alert_content -%} @@ -14,6 +15,7 @@ The Go SDK is maintained and supported by Sentry but currently under development Raven-Go provides a Sentry client implementation for the Go programming language. + ## Installation Raven-Go can be installed like any other Go library through `go get`: @@ -59,6 +61,7 @@ raven.CapturePanic(func() { // do all of the scary things here }, nil) ``` + ## Additional Context diff --git a/src/collections/_documentation/clients/go/integrations/http.md b/src/collections/_documentation/clients/go/integrations/http.md index e81e184a992dc..ae3d821cf3f93 100644 --- a/src/collections/_documentation/clients/go/integrations/http.md +++ b/src/collections/_documentation/clients/go/integrations/http.md @@ -4,6 +4,7 @@ title: net/http Raven Go provides middleware that can be used with the stdlib `net/http` library to automatically handle panics that occur during an http request. + ## Installation Simply install `raven-go` through `go get`: @@ -36,3 +37,4 @@ func root(w http.ResponseWriter, r *http.Request) { } http.HandleFunc("/", raven.RecoveryHandler(root)) ``` + diff --git a/src/collections/_documentation/clients/index.md b/src/collections/_documentation/clients/index.md index 01f6d5c29ef09..01044cd5f6c03 100644 --- a/src/collections/_documentation/clients/index.md +++ b/src/collections/_documentation/clients/index.md @@ -1,8 +1,8 @@ --- -title: SDKs -sidebar_order: 2 +title: Legacy Clients +sidebar_order: 4 --- -To report to Sentry you’ll need to use a language-specific SDK. The Sentry team builds and maintains these for most popular languages, but there’s also a large ecosystem supported by the community. If your favorite language isn’t listed below, we encourage you to start a discussion about supporting it on our [community forum](https://forum.sentry.io). +Some of the clients that report to Sentry have been replaced by newer SDKs or are no longer maintained. We document them here for users who are still using those clients but they are recommended against for new projects. {% include LEGACY_platform_icon_links.html %} diff --git a/src/collections/_documentation/clients/java/index.md b/src/collections/_documentation/clients/java/index.md index 6ac454181cf39..0ddcef596fa08 100644 --- a/src/collections/_documentation/clients/java/index.md +++ b/src/collections/_documentation/clients/java/index.md @@ -1,6 +1,7 @@ --- title: Java sidebar_order: 6 +sidebar_relocation: platforms --- Sentry for Java is the official Java SDK for Sentry. At its core it provides a raw client for sending events to Sentry, but it is highly recommended that you use one of the included library or framework integrations listed below if at all possible. diff --git a/src/collections/_documentation/clients/java/modules/android.md b/src/collections/_documentation/clients/java/modules/android.md index ce9bb165c93e4..49af74bb08255 100644 --- a/src/collections/_documentation/clients/java/modules/android.md +++ b/src/collections/_documentation/clients/java/modules/android.md @@ -13,6 +13,7 @@ An `UncaughtExceptionHandler` is configured so that crash events will be stored The `AndroidEventBuilderHelper` is enabled by default, which will automatically enrich events with data about the current state of the device, such as memory usage, storage usage, display resolution, connectivity, battery level, model, Android version, whether the device is rooted or not, etc. + ## Installation Using Gradle (Android Studio) in your `app/build.gradle` add: @@ -22,6 +23,7 @@ compile 'io.sentry:sentry-android:1.7.5' ``` For other dependency managers see the [central Maven repository](https://search.maven.org/#artifactdetails%7Cio.sentry%7Csentry-android%7C1.7.5%7Cjar). + ## Initialization @@ -58,6 +60,7 @@ public class MainActivity extends Activity { You can optionally configure other values such as `environment` and `release`. [See the configuration page]({%- link _documentation/clients/java/config.md -%}#configuration) for ways you can do this. + ## Usage Now you can use `Sentry` to capture events anywhere in your application: @@ -109,6 +112,7 @@ public class MyClass { } } ``` + ## ProGuard diff --git a/src/collections/_documentation/clients/java/modules/appengine.md b/src/collections/_documentation/clients/java/modules/appengine.md index 6c1f9eee954a9..7535b530e8c89 100644 --- a/src/collections/_documentation/clients/java/modules/appengine.md +++ b/src/collections/_documentation/clients/java/modules/appengine.md @@ -7,6 +7,7 @@ The `sentry-appengine` library provides [Google App Engine](https://cloud.google The source can be found [on Github](https://github.com/getsentry/sentry-java/tree/master/sentry-appengine). + ## Installation Using Maven: @@ -38,6 +39,7 @@ For other dependency managers see the [central Maven repository](https://search. This module provides a new `SentryClientFactory` implementation which replaces the default async system with a Google App Engine compatible one. You’ll need to configure Sentry to use the `io.sentry.appengine.AppEngineSentryClientFactory` as its factory. The queue size and thread options will not be used as they are specific to the default Java threading system. + ## Queue Name diff --git a/src/collections/_documentation/clients/java/modules/jul.md b/src/collections/_documentation/clients/java/modules/jul.md index 26fc5d6349dfc..e91adbb7abba6 100644 --- a/src/collections/_documentation/clients/java/modules/jul.md +++ b/src/collections/_documentation/clients/java/modules/jul.md @@ -9,6 +9,7 @@ The source for `sentry` can be found [on Github](https://github.com/getsentry/se **Note:** The old `raven` library is no longer maintained. It is highly recommended that you [migrate]({%- link _documentation/clients/java/migration.md -%}) to `sentry` (which this documentation covers). [Check out the migration guide]({%- link _documentation/clients/java/migration.md -%}) for more information. If you are still using `raven` you can [find the old documentation here](https://github.com/getsentry/sentry-java/blob/raven-java-8.x/docs/modules/raven.rst). + ## Installation Using Maven: @@ -59,6 +60,7 @@ $ java -Djava.util.logging.config.file=/path/to/app.properties MyClass ``` Next, **you’ll need to configure your DSN** (client key) and optionally other values such as `environment` and `release`. [See the configuration page]({%- link _documentation/clients/java/config.md -%}#configuration) for ways you can do this. + ## In Practice diff --git a/src/collections/_documentation/clients/java/modules/log4j.md b/src/collections/_documentation/clients/java/modules/log4j.md index 96a46f6305659..94e9441f124d6 100644 --- a/src/collections/_documentation/clients/java/modules/log4j.md +++ b/src/collections/_documentation/clients/java/modules/log4j.md @@ -9,6 +9,7 @@ The source can be found [on Github](https://github.com/getsentry/sentry-java/tre **Note:** The old `raven-log4j` library is no longer maintained. It is highly recommended that you [migrate]({%- link _documentation/clients/java/migration.md -%}) to `sentry-log4j` (which this documentation covers). [Check out the migration guide]({%- link _documentation/clients/java/migration.md -%}) for more information. If you are still using `raven-log4j` you can [find the old documentation here](https://github.com/getsentry/sentry-java/blob/raven-java-8.x/docs/modules/log4j.rst). + ## Installation Using Maven: @@ -89,6 +90,7 @@ Alternatively, using the `log4j.xml` format: ``` Next, **you’ll need to configure your DSN** (client key) and optionally other values such as `environment` and `release`. [See the configuration page]({%- link _documentation/clients/java/config.md -%}#configuration) for ways you can do this. + ## Additional Data diff --git a/src/collections/_documentation/clients/java/modules/log4j2.md b/src/collections/_documentation/clients/java/modules/log4j2.md index 4e4c09e2fcaab..d3685d7b093d9 100644 --- a/src/collections/_documentation/clients/java/modules/log4j2.md +++ b/src/collections/_documentation/clients/java/modules/log4j2.md @@ -9,6 +9,7 @@ The source can be found [on Github](https://github.com/getsentry/sentry-java/tre **Note:** The old `raven-log4j2` library is no longer maintained. It is highly recommended that you [migrate]({%- link _documentation/clients/java/migration.md -%}) to `sentry-log4j2` (which this documentation covers). [Check out the migration guide]({%- link _documentation/clients/java/migration.md -%}) for more information. If you are still using `raven-log4j2` you can [find the old documentation here](https://github.com/getsentry/sentry-java/blob/raven-java-8.x/docs/modules/log4j2.rst). + ## Installation Using Maven: @@ -63,6 +64,7 @@ Example configuration using the `log4j2.xml` format: ``` Next, **you’ll need to configure your DSN** (client key) and optionally other values such as `environment` and `release`. [See the configuration page]({%- link _documentation/clients/java/config.md -%}#configuration) for ways you can do this. + ## Additional Data diff --git a/src/collections/_documentation/clients/java/modules/logback.md b/src/collections/_documentation/clients/java/modules/logback.md index 186c2eb290ac4..a76c972e369a9 100644 --- a/src/collections/_documentation/clients/java/modules/logback.md +++ b/src/collections/_documentation/clients/java/modules/logback.md @@ -9,6 +9,7 @@ The source can be found [on Github](https://github.com/getsentry/sentry-java/tre **Note:** The old `raven-logback` library is no longer maintained. It is highly recommended that you [migrate]({%- link _documentation/clients/java/migration.md -%}) to `sentry-logback` (which this documentation covers). [Check out the migration guide]({%- link _documentation/clients/java/migration.md -%}) for more information. If you are still using `raven-logback` you can [find the old documentation here](https://github.com/getsentry/sentry-java/blob/raven-java-8.x/docs/modules/logback.rst). + ## Installation Using Maven: @@ -67,6 +68,7 @@ Example configuration using the `logback.xml` format: ``` Next, **you’ll need to configure your DSN** (client key) and optionally other values such as `environment` and `release`. [See the configuration page]({%- link _documentation/clients/java/config.md -%}#setting-the-dsn) for ways you can do this. + ## Additional Data diff --git a/src/collections/_documentation/clients/java/usage.md b/src/collections/_documentation/clients/java/usage.md index d6363a4d1bbf4..1543de6f3ffdc 100644 --- a/src/collections/_documentation/clients/java/usage.md +++ b/src/collections/_documentation/clients/java/usage.md @@ -5,6 +5,7 @@ sidebar_order: 2 **Note:** The following page provides examples on how to configure and use Sentry directly. It is **highly recommended** that you use one of the [provided integrations]({%- link _documentation/clients/java/modules/index.md -%}#integrations) if possible. Once the integration is configured you can _also_ use Sentry’s static API, as shown below, in order to do things like record breadcrumbs, set the current user, or manually send events. + ## Installation Using Maven: @@ -30,7 +31,9 @@ libraryDependencies += "io.sentry" % "sentry" % "1.7.5" ``` For other dependency managers see the [central Maven repository](https://search.maven.org/#artifactdetails%7Cio.sentry%7Csentry%7C1.7.5%7Cjar). + + ## Capture an Error To report an event manually you need to initialize a `SentryClient`. It is recommended that you use the static API via the `Sentry` class, but you can also construct and manage your own `SentryClient` instance. An example of each style is shown below: @@ -140,6 +143,7 @@ public class MyClass { } } ``` + ### Building More Complex Events diff --git a/src/collections/_documentation/clients/javascript/index.md b/src/collections/_documentation/clients/javascript/index.md index 2798b1659e264..b6df36e5d5418 100644 --- a/src/collections/_documentation/clients/javascript/index.md +++ b/src/collections/_documentation/clients/javascript/index.md @@ -7,6 +7,7 @@ Raven.js is the official browser JavaScript client for Sentry. It automatically **Note**: If you’re using Node.js on the server, you’ll need [raven-node]({%- link _documentation/clients/node/index.md -%}). + ## Installation The easiest way to load Raven.js is to load it directly from our CDN. This script tag should be included after other libraries are loaded, but before your main application code (e.g. app.js): @@ -52,6 +53,7 @@ try { ``` There are more ways to report errors. For a complete guide on this see [Reporting Errors Correctly]({%- link _documentation/clients/javascript/usage.md -%}#raven-js-reporting-errors). + ## Adding Context diff --git a/src/collections/_documentation/clients/javascript/integrations/angular.md b/src/collections/_documentation/clients/javascript/integrations/angular.md index 1c9ea27d50120..213eb00fbc916 100644 --- a/src/collections/_documentation/clients/javascript/integrations/angular.md +++ b/src/collections/_documentation/clients/javascript/integrations/angular.md @@ -11,6 +11,7 @@ Additionally, Raven.js can be configured to catch any Angular-specific (2.x) exc Raven.js ships with a [TypeScript declaration file](https://github.com/getsentry/raven-js/blob/master/packages/raven-js/typescript/raven.d.ts), which helps static checking correctness of Raven.js API calls, and facilitates auto-complete in TypeScript-aware IDEs like Visual Studio Code. + ## Installation Raven.js should be installed via npm. @@ -107,3 +108,4 @@ export class AppModule { } ``` Once you’ve completed that step, you are done. + diff --git a/src/collections/_documentation/clients/javascript/integrations/angularjs.md b/src/collections/_documentation/clients/javascript/integrations/angularjs.md index 7c8c72ef9105e..d43044ff01489 100644 --- a/src/collections/_documentation/clients/javascript/integrations/angularjs.md +++ b/src/collections/_documentation/clients/javascript/integrations/angularjs.md @@ -11,6 +11,7 @@ Additionally, the Raven.js AngularJS plugin will catch any AngularJS-specific ex **Note**: This documentation is for Angular 1.x. See also: [_Angular 2.x_]({%- link _documentation/clients/javascript/integrations/angular.md -%}) + ## Installation Raven.js and the Raven.js Angular plugin are distributed using a few different methods. @@ -126,3 +127,4 @@ angular.module(moduleName, [ module.exports = moduleName; ``` + diff --git a/src/collections/_documentation/clients/javascript/integrations/backbone.md b/src/collections/_documentation/clients/javascript/integrations/backbone.md index c69dd8c4e8d80..95df48e03bbb8 100644 --- a/src/collections/_documentation/clients/javascript/integrations/backbone.md +++ b/src/collections/_documentation/clients/javascript/integrations/backbone.md @@ -3,6 +3,7 @@ title: Backbone sidebar_order: 8 --- + ## Installation Start by adding the `raven.js` script tag to your page. It should be loaded as early as possible. @@ -21,3 +22,4 @@ Raven.config('___PUBLIC_DSN___').install() ``` At this point, Raven is ready to capture any uncaught exception. + diff --git a/src/collections/_documentation/clients/javascript/integrations/ember.md b/src/collections/_documentation/clients/javascript/integrations/ember.md index 9efa52ae4f4eb..0750e9b0e1e0d 100644 --- a/src/collections/_documentation/clients/javascript/integrations/ember.md +++ b/src/collections/_documentation/clients/javascript/integrations/ember.md @@ -9,6 +9,7 @@ On its own, Raven.js will report any uncaught exceptions triggered from your app Additionally, the Raven.js Ember plugin will catch any Ember-specific exceptions reported through Ember’s [onerror](https://guides.emberjs.com/v3.0.2/configuring-ember/debugging/#toc_implement-an-ember-onerror-hook-to-log-all-errors-in-production). hook and any [RSVP promises](https://guides.emberjs.com/v3.2.0/configuring-ember/debugging/#toc_errors-within-an-code-rsvp-promise-code) that would otherwise be swallowed. + ## Installation Raven.js and the Raven.js Ember plugin are distributed using a few different methods. @@ -80,3 +81,4 @@ These examples assume that Ember is exported globally as `window.Ember`. You can ```javascript Raven.addPlugin(Raven.Plugins.Ember, Ember); ``` + diff --git a/src/collections/_documentation/clients/javascript/integrations/react.md b/src/collections/_documentation/clients/javascript/integrations/react.md index fb317a6494e67..8acbdbc204c9f 100644 --- a/src/collections/_documentation/clients/javascript/integrations/react.md +++ b/src/collections/_documentation/clients/javascript/integrations/react.md @@ -3,6 +3,7 @@ title: React sidebar_order: 10 --- + ## Installation Start by adding the `raven.js` script tag to your page. It should be loaded as early as possible, before your main javascript bundle. @@ -21,7 +22,7 @@ Raven.config('___PUBLIC_DSN___').install() ``` At this point, Raven is ready to capture any uncaught exception. - + ## Expanded Usage If you’re using React 16 or above, [Error Boundaries](https://reactjs.org/blog/2017/07/26/error-handling-in-react-16.html) are an important tool for defining the behavior of your application in the face of errors. Be sure to send errors they catch to Sentry using `Raven.captureException`, and optionally this is also a great opportunity to surface [User Feedback]({%- link _documentation/learn/user-feedback.md -%}) diff --git a/src/collections/_documentation/clients/javascript/integrations/vue.md b/src/collections/_documentation/clients/javascript/integrations/vue.md index 20301cc8c823a..e8dab6b672294 100644 --- a/src/collections/_documentation/clients/javascript/integrations/vue.md +++ b/src/collections/_documentation/clients/javascript/integrations/vue.md @@ -18,6 +18,7 @@ On its own, Raven.js will report any uncaught exceptions triggered from your app Additionally, the Raven.js Vue plugin will capture the name and props state of the active component where the error was thrown. This is reported via Vue’s _config.errorHandler_ hook. + ## Installation Raven.js and the Raven.js Vue plugin are distributed using a few different methods. @@ -96,3 +97,5 @@ Raven .addPlugin(RavenVue, Vue) .install(); ``` + + diff --git a/src/collections/_documentation/clients/node/index.md b/src/collections/_documentation/clients/node/index.md index 98363ca10d182..2b3a04cad573f 100644 --- a/src/collections/_documentation/clients/node/index.md +++ b/src/collections/_documentation/clients/node/index.md @@ -7,6 +7,7 @@ raven-node is the official Node.js client for Sentry. **Note**: If you’re using JavaScript in the browser, you’ll need [raven-js](https://docs.sentry.io/clients/javascript). + ## Installation Raven is distributed via `npm`: @@ -14,7 +15,9 @@ Raven is distributed via `npm`: ```bash $ npm install raven --save ``` + + ## Configuring the Client Next you need to initialize the Raven client and configure it to use your [Sentry DSN]({%- link _documentation/learn/quickstart.md -%}#configure-the-dsn): @@ -27,7 +30,9 @@ Raven.config('___PUBLIC_DSN___').install(); At this point, Raven is set up to capture and report any uncaught exceptions. You can optionally pass an object of configuration options as the 2nd argument to _Raven.config_. For more information, see [_Configuration_]({%- link _documentation/clients/node/config.md -%}). + + ## Reporting Errors Raven’s `install` method sets up a global handler to automatically capture any uncaught exceptions. You can also report errors manually with `try...catch` and a call to `captureException`: @@ -39,6 +44,7 @@ try { Raven.captureException(e); } ``` + You can also use `wrap` and `context` to have Raven wrap a function and automatically capture any exceptions it throws: diff --git a/src/collections/_documentation/clients/node/integrations/connect.md b/src/collections/_documentation/clients/node/integrations/connect.md index bd697e35f537a..4a95149d91f66 100644 --- a/src/collections/_documentation/clients/node/integrations/connect.md +++ b/src/collections/_documentation/clients/node/integrations/connect.md @@ -3,6 +3,7 @@ title: Connect sidebar_order: 6 --- + ```javascript var connect = require('connect'); var Raven = require('raven'); @@ -36,3 +37,4 @@ connect( onError, ).listen(3000); ``` + diff --git a/src/collections/_documentation/clients/node/integrations/express.md b/src/collections/_documentation/clients/node/integrations/express.md index 998f5d0b0f757..5ec71b023b582 100644 --- a/src/collections/_documentation/clients/node/integrations/express.md +++ b/src/collections/_documentation/clients/node/integrations/express.md @@ -3,6 +3,7 @@ title: Express sidebar_order: 7 --- + ```javascript var app = require('express')(); var Raven = require('raven'); @@ -30,3 +31,4 @@ app.use(function onError(err, req, res, next) { app.listen(3000); ``` + diff --git a/src/collections/_documentation/clients/node/integrations/koa.md b/src/collections/_documentation/clients/node/integrations/koa.md index ae9d73d7b4754..58ef948a74e8b 100644 --- a/src/collections/_documentation/clients/node/integrations/koa.md +++ b/src/collections/_documentation/clients/node/integrations/koa.md @@ -3,6 +3,7 @@ title: Koa sidebar_order: 8 --- + ```javascript var koa = require('koa'); var Raven = require('raven'); @@ -18,3 +19,4 @@ app.on('error', function (err) { app.listen(3000); ``` + diff --git a/src/collections/_documentation/clients/php/index.md b/src/collections/_documentation/clients/php/index.md index 697524c89cae5..84aa5017454b5 100644 --- a/src/collections/_documentation/clients/php/index.md +++ b/src/collections/_documentation/clients/php/index.md @@ -1,10 +1,12 @@ --- title: PHP sidebar_order: 11 +sidebar_relocation: platforms --- The PHP SDK for Sentry supports PHP 5.3 and higher. It’s available as a BSD licensed Open Source library. + ## Installation There are various ways to install the PHP integration for Sentry. The recommended way is to use [Composer](http://getcomposer.org/): @@ -22,7 +24,9 @@ Alternatively you can manually install it: require_once '/path/to/Raven/library/Raven/Autoloader.php'; Raven_Autoloader::register(); ``` + + ## Configuration The most important part is the creation of the raven client. Create it once and reference it from anywhere you want to interface with Sentry: @@ -39,6 +43,7 @@ $error_handler->registerExceptionHandler(); $error_handler->registerErrorHandler(); $error_handler->registerShutdownFunction(); ``` + ## Adding Context diff --git a/src/collections/_documentation/clients/php/integrations/laravel.md b/src/collections/_documentation/clients/php/integrations/laravel.md index 84835aa873414..b2d65083569c0 100644 --- a/src/collections/_documentation/clients/php/integrations/laravel.md +++ b/src/collections/_documentation/clients/php/integrations/laravel.md @@ -5,6 +5,7 @@ sidebar_order: 3 Laravel is supported via a native package, [sentry-laravel](https://github.com/getsentry/sentry-laravel). + ## Laravel 5.x {#laravel-5-x} Install the `sentry/sentry-laravel` package: @@ -205,7 +206,7 @@ return array( // 'release' => trim(exec('git log --pretty="%h" -n1 HEAD')), ); ``` - + ## Testing with Artisan You can test your configuration using the provided `artisan` command: diff --git a/src/collections/_documentation/clients/php/integrations/monolog.md b/src/collections/_documentation/clients/php/integrations/monolog.md index 1e9ba2de42832..38e7fa5475fca 100644 --- a/src/collections/_documentation/clients/php/integrations/monolog.md +++ b/src/collections/_documentation/clients/php/integrations/monolog.md @@ -3,6 +3,7 @@ title: Monolog sidebar_order: 4 --- + ## Capturing Errors Monolog supports Sentry out of the box, so you’ll just need to configure a handler: @@ -50,3 +51,4 @@ $client = new Raven_Client('___PUBLIC_DSN___'); $handler = new \Raven_Breadcrumbs_MonologHandler($client); $monolog->pushHandler($handler); ``` + diff --git a/src/collections/_documentation/clients/php/integrations/symfony2.md b/src/collections/_documentation/clients/php/integrations/symfony2.md index 7a244a611b85a..277d67bd6b5b8 100644 --- a/src/collections/_documentation/clients/php/integrations/symfony2.md +++ b/src/collections/_documentation/clients/php/integrations/symfony2.md @@ -5,6 +5,7 @@ sidebar_order: 5 Symfony is supported via the [sentry-symfony](https://github.com/getsentry/sentry-symfony) package as a native bundle. + ## Symfony 2+ Install the `sentry/sentry-symfony` package: @@ -40,3 +41,4 @@ Add your DSN to `app/config/config.yml`: sentry: dsn: "___PUBLIC_DSN___" ``` + diff --git a/src/collections/_documentation/clients/php/usage.md b/src/collections/_documentation/clients/php/usage.md index c421b06e3da43..95fcfca7f8b15 100644 --- a/src/collections/_documentation/clients/php/usage.md +++ b/src/collections/_documentation/clients/php/usage.md @@ -13,6 +13,7 @@ The most important part is the creation of the raven client. Create it once and $sentryClient = new Raven_Client('___PUBLIC_DSN___'); ``` + ## Capturing Errors Sentry includes basic functionality for reporting any uncaught exceptions or PHP errors. This is done via the error handler, and appropriate hooks for each of PHP’s built-in reporting: @@ -31,6 +32,7 @@ Calling `install()` on a Raven_Client instance will automatically register these title="Note" content=__alert_content %} + ## Reporting Exceptions diff --git a/src/collections/_documentation/clients/python/index.md b/src/collections/_documentation/clients/python/index.md index 6b3a8d2c65447..a39f9ae64058a 100644 --- a/src/collections/_documentation/clients/python/index.md +++ b/src/collections/_documentation/clients/python/index.md @@ -5,6 +5,7 @@ sidebar_order: 12 For pairing Sentry up with Python you can use the Raven for Python (raven-python) library. It is the official standalone Python client for Sentry. It can be used with any modern Python interpreter be it CPython 2.x or 3.x, PyPy or Jython. It’s an Open Source project and available under a very liberal BSD license. + ## Installation If you haven’t already, start by downloading Raven. The easiest way is with _pip_: @@ -12,6 +13,7 @@ If you haven’t already, start by downloading Raven. The easiest way is with _p ```bash pip install raven --upgrade ``` + ## Configuring the Client diff --git a/src/collections/_documentation/clients/python/integrations/bottle.md b/src/collections/_documentation/clients/python/integrations/bottle.md index 84df049824811..daacc47e743a2 100644 --- a/src/collections/_documentation/clients/python/integrations/bottle.md +++ b/src/collections/_documentation/clients/python/integrations/bottle.md @@ -13,6 +13,7 @@ If you haven’t already, start by downloading Raven. The easiest way is with _p pip install raven --upgrade ``` + ## Setup The first thing you’ll need to do is to disable catchall in your Bottle app: @@ -65,3 +66,4 @@ Log a generic message with `captureMessage`: ```python request.app.sentry.captureMessage('Hello, world!') ``` + diff --git a/src/collections/_documentation/clients/python/integrations/celery.md b/src/collections/_documentation/clients/python/integrations/celery.md index dd62e7092e01f..12508be004830 100644 --- a/src/collections/_documentation/clients/python/integrations/celery.md +++ b/src/collections/_documentation/clients/python/integrations/celery.md @@ -13,6 +13,7 @@ If you haven’t already, start by downloading Raven. The easiest way is with _p pip install raven --upgrade ``` + ## Setup To capture errors, you need to register a couple of signals to hijack Celery error handling: @@ -61,3 +62,4 @@ class Celery(celery.Celery): app = Celery(__name__) app.config_from_object('django.conf:settings') ``` + diff --git a/src/collections/_documentation/clients/python/integrations/django.md b/src/collections/_documentation/clients/python/integrations/django.md index e2c14d828c3bb..a89548b129b8a 100644 --- a/src/collections/_documentation/clients/python/integrations/django.md +++ b/src/collections/_documentation/clients/python/integrations/django.md @@ -13,6 +13,7 @@ If you haven’t already, start by downloading Raven. The easiest way is with _p pip install raven --upgrade ``` + ## Setup Using the Django integration is as simple as adding `raven.contrib.django.raven_compat` to your installed apps: @@ -58,6 +59,7 @@ from raven.contrib.django.raven_compat.models import client client.captureException() ``` + ## Using with Raven.js {#using-with-raven-js} diff --git a/src/collections/_documentation/clients/python/integrations/flask.md b/src/collections/_documentation/clients/python/integrations/flask.md index 48f1fff60112f..88cc4cfe5ed95 100644 --- a/src/collections/_documentation/clients/python/integrations/flask.md +++ b/src/collections/_documentation/clients/python/integrations/flask.md @@ -3,6 +3,7 @@ title: Flask sidebar_order: 7 --- + ## Installation If you haven’t already, install raven with its explicit Flask dependencies: @@ -21,6 +22,7 @@ sentry = Sentry(app, dsn='___DSN___') ``` If you don’t specify the `dsn` value, we will attempt to read it from your environment under the `SENTRY_DSN` key. + ## Extended Setup diff --git a/src/collections/_documentation/clients/python/integrations/pylons.md b/src/collections/_documentation/clients/python/integrations/pylons.md index 4085c626545cb..1809c321a5745 100644 --- a/src/collections/_documentation/clients/python/integrations/pylons.md +++ b/src/collections/_documentation/clients/python/integrations/pylons.md @@ -13,6 +13,7 @@ If you haven’t already, start by downloading Raven. The easiest way is with _p pip install raven --upgrade ``` + ## WSGI Middleware A Pylons-specific middleware exists to enable easy configuration from settings: @@ -80,3 +81,4 @@ You may want to setup other loggers as well. title="Note" content=__alert_content %} + diff --git a/src/collections/_documentation/clients/python/integrations/pyramid.md b/src/collections/_documentation/clients/python/integrations/pyramid.md index 83f181ba0ec3b..48798f5f032b5 100644 --- a/src/collections/_documentation/clients/python/integrations/pyramid.md +++ b/src/collections/_documentation/clients/python/integrations/pyramid.md @@ -11,6 +11,7 @@ If you haven’t already, start by downloading Raven. The easiest way is with _p pip install raven --upgrade ``` + ## PasteDeploy Filter A filter factory for [PasteDeploy](https://pastedeploy.readthedocs.io/en/latest/) exists to allow easily inserting Raven into a WSGI pipeline: @@ -83,3 +84,4 @@ You may want to setup other loggers as well. See the [Pyramid Logging Documentat %} Instead of defining the DSN in the _.ini_ file you can also use the environment variable `SENTRY_DSN` which overwrites the setting in this file. Because of a syntax check you cannot remove the `args` setting completely, as workaround you can define an empty list of arguments `args = ()`. + diff --git a/src/collections/_documentation/clients/python/integrations/rq.md b/src/collections/_documentation/clients/python/integrations/rq.md index 6599b63e7f21f..cf1588cc6b16c 100644 --- a/src/collections/_documentation/clients/python/integrations/rq.md +++ b/src/collections/_documentation/clients/python/integrations/rq.md @@ -5,6 +5,7 @@ sidebar_order: 12 Starting with RQ version 0.3.1, support for Sentry has been built in. + ## Usage RQ natively supports binding with Sentry by passing your `SENTRY_DSN` through `rqworker`: @@ -27,3 +28,4 @@ register_sentry(client, worker) ``` Please see `rq`‘s documentation for more information: [http://python-rq.org/patterns/sentry/](http://python-rq.org/patterns/sentry/) + diff --git a/src/collections/_documentation/clients/python/integrations/tornado.md b/src/collections/_documentation/clients/python/integrations/tornado.md index 5e0cabf5673db..fc19e1d6136cf 100644 --- a/src/collections/_documentation/clients/python/integrations/tornado.md +++ b/src/collections/_documentation/clients/python/integrations/tornado.md @@ -12,7 +12,7 @@ If you haven’t already, start by downloading Raven. The easiest way is with _p ```bash pip install raven --upgrade ``` - + ## Setup The first thing you’ll need to do is to initialize sentry client under your application @@ -48,6 +48,7 @@ class UncaughtExceptionExampleHandler( ``` You can also send events manually using the shortcuts defined in _SentryMixin_. The shortcuts can be used for both asynchronous and synchronous usage. + ### Asynchronous diff --git a/src/collections/_documentation/clients/python/usage.md b/src/collections/_documentation/clients/python/usage.md index 167e87a4a61ff..285f6baa594c4 100644 --- a/src/collections/_documentation/clients/python/usage.md +++ b/src/collections/_documentation/clients/python/usage.md @@ -4,6 +4,7 @@ title: 'Basic Usage' This gives a basic overview of how to use the raven client with Python directly. + ## Capture an Error The most basic use for raven is to record one specific error that occurs: @@ -26,6 +27,7 @@ To report an arbitrary event you can use the [`capture()`]({%- link _documentati ```python client.captureMessage('Something went fundamentally wrong') ``` + ## Adding Context diff --git a/src/collections/_documentation/clients/react-native/codepush.md b/src/collections/_documentation/clients/react-native/codepush.md index 7c35980fa4265..6ee9391e2e9f6 100644 --- a/src/collections/_documentation/clients/react-native/codepush.md +++ b/src/collections/_documentation/clients/react-native/codepush.md @@ -19,9 +19,9 @@ Put this somewhere in your code where you already use CodePush. This makes sure After updating your CodePush release you have to upload the new assets to Sentry: ```bash -$ appcenter codepush release-react YourApp ios --outputDir build +$ appcenter codepush release-react YourApp --output-dir ./build $ export SENTRY_PROPERTIES=./ios/sentry.properties -$ sentry-cli react-native codepush YourApp ios ./build +$ sentry-cli react-native appcenter YourApp ios ./build/codePush ``` {% capture __alert_content -%} diff --git a/src/collections/_documentation/clients/react-native/index.md b/src/collections/_documentation/clients/react-native/index.md index 093d4abe0b5b9..a22f9d2b19fc1 100644 --- a/src/collections/_documentation/clients/react-native/index.md +++ b/src/collections/_documentation/clients/react-native/index.md @@ -1,10 +1,12 @@ --- title: 'React Native' sidebar_order: 11 +sidebar_relocation: platforms --- This is the documentation for our React-Native SDK. The React-Native SDK uses a native extension for iOS and Android but will fall back to a pure JavaScript version if necessary. + ## Installation Start by adding Sentry and then linking it: @@ -35,6 +37,7 @@ Upon linking the following changes will be performed: To see what is happening during linking you can refer to [_Manual Setup_]({%- link _documentation/clients/react-native/manual-setup.md -%}) which will give you all the details. Note that we only support `react-native >= 0.38` at the moment. + ## Upgrading @@ -53,6 +56,7 @@ When you use Xcode you can hook directly into the build process to upload debug For Android we hook into gradle for the sourcemap build process. When you run `react-native link` the gradle files are automatically updated. When you run `./gradlew assembleRelease` sourcemaps are automatically built and uploaded to Sentry. + ## Client Configuration Note: When you run `react-native link` we will automatically update your _index.ios.js_ / _index.android.js_ with the following changes: @@ -63,6 +67,7 @@ Sentry.config('___PUBLIC_DSN___').install(); ``` You can pass additional configuration options to the _config()_ method if you want to do so. + ## Mixed Stacktraces diff --git a/src/collections/_documentation/clients/ruby/index.md b/src/collections/_documentation/clients/ruby/index.md index 7039fd017aa11..837b91f9fd666 100644 --- a/src/collections/_documentation/clients/ruby/index.md +++ b/src/collections/_documentation/clients/ruby/index.md @@ -1,10 +1,12 @@ --- title: Ruby sidebar_order: 14 +sidebar_relocation: platforms --- Raven for Ruby is a client and integration layer for the Sentry error reporting API. It supports Ruby 1.9.3 and 2.x. JRuby support is provided but experimental. + ## Installation Raven Ruby comes as a gem and is straightforward to install. If you are using Bundler just add this to your `Gemfile`: @@ -45,6 +47,7 @@ rescue ZeroDivisionError => exception Raven.capture_exception(exception) end ``` + ## Additional Context diff --git a/src/collections/_documentation/clients/ruby/integrations/rack.md b/src/collections/_documentation/clients/ruby/integrations/rack.md index 00e4da86d3f48..fc40d690e4e90 100644 --- a/src/collections/_documentation/clients/ruby/integrations/rack.md +++ b/src/collections/_documentation/clients/ruby/integrations/rack.md @@ -3,6 +3,7 @@ title: 'Rack (Sinatra etc.)' sidebar_order: 8 --- + ## Installation Install the SDK via Rubygems by adding it to your `Gemfile`: @@ -24,3 +25,4 @@ end use Raven::Rack ``` + diff --git a/src/collections/_documentation/clients/ruby/integrations/rails.md b/src/collections/_documentation/clients/ruby/integrations/rails.md index 6ca8553b7ebad..8ffa1528dafcc 100644 --- a/src/collections/_documentation/clients/ruby/integrations/rails.md +++ b/src/collections/_documentation/clients/ruby/integrations/rails.md @@ -3,6 +3,7 @@ title: 'Ruby on Rails' sidebar_order: 7 --- + In Rails, all uncaught exceptions will be automatically reported. We support Rails 4 and newer. @@ -55,3 +56,4 @@ end ## Caveats Currently, custom exception applications (_config.exceptions_app_) are not supported. If you are using a custom exception app, you must manually integrate Raven yourself. + diff --git a/src/collections/_documentation/clients/rust/index.md b/src/collections/_documentation/clients/rust/index.md deleted file mode 100644 index b1081b8e0c456..0000000000000 --- a/src/collections/_documentation/clients/rust/index.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Rust -sidebar_order: 15 ---- - -Sentry-Rust is the official Rust SDK for Sentry. It maps the entire Sentry protocol for Rust and provides convenient helpers for sending common types of events to Sentry. - -## Installation - -Sentry-Rust is distributed as a normal crate from crates.io. You can add it to your project as a dependency in your _Cargo.toml_ file: - -``` -[dependencies] -sentry = "0.9.0" -``` - -Additionally you can configure a bunch of features to enable or disable functionality in the crate. By default the most common features are compiled into the crate. For a list of features that are available refer to the [API Documentation](https://docs.rs/sentry). - -## Configuring the Client - -The client is configured by calling `sentry::init` with a value that can be converted into a configuration object. These are the most common values: - -- _an empty tuple_: in that case the client is configured from the `SENTRY_DSN` environment variably only. -- _a string holding a DSN_: if you pass a string then a DSN is parsed and the client is initialized with that DSN. -- _a tuple in the form (dsn, options)_: This is a form where the client is configured with a DSN plus an options object that allows you to configure additional features. -- _just options_: In that case everything (including the DSN) are configured from the passed options. - -This is the most common case for client configuration: - -```rust -extern crate sentry; - -fn main() { - sentry::init("___PUBLIC_DSN___"); - // code using sentry goes here. -} -``` - -To configure releases automatically you can use the `sentry_crate_release!` macro in combination with the tuple config syntax: - -```rust -#[macro_use] extern crate sentry; - -fn main() { - sentry::init(("___PUBLIC_DSN___", sentry::ClientOptions { - release: sentry_crate_release!(), - ..Default::default() - })); - // code using sentry goes here. -} -``` - -## Reporting Errors - -Once Sentry is configured errors and other events can be emitted. Since Rust has different mechanisms by which errors can be issued different functionality is provided for them. By default support for the new [failure](https://docs.rs/failure) error system is provided. - -For instance to report a `failure::Error` this code can be used: - -```rust -use sentry::integrations::failure::capture_error; - -let result = match a_function_that_might_fail() { - Ok(val) => val, - Err(err) => { - capture_error(&err); - return Err(err); - } -}; -``` - -## Catching Panics - -To automatically catch panics the panic integration can be used: - -```rust -use sentry::integrations::panic::register_panic_handler; - -fn main() { - sentry::init(...); - register_panic_handler(); -} -``` - -## Flushing Errors on Shutdown - -Since Sentry Rust uses a thread to offload event sending it’s possible that pending events are not sent on shutdown. There are two ways to prevent this from happening. The first one is to retain the guard returned from `sentry::init` which will flush out in the _Drop_ implementation (it will wait up to 2 seconds for this): - -```rust -fn main() { - let _guard = sentry::init(...); -} -``` - -## More Information - -For more information (in particular about how to set contextual data) refer to the [full API documentation](https://docs.rs/sentry/) which has all that information and more. - -Resources: - -- [API Docs](http://docs.rs/sentry) -- [Crates.io page](http://crates.io/crates/sentry) -- [Bug Tracker](http://github.com/getsentry/sentry-rust/issues) -- [Github Project](http://github.com/getsentry/sentry-rust) diff --git a/src/collections/_documentation/integrations/github.md b/src/collections/_documentation/integrations/github.md index 9ee67979776f1..fbb6c41c0d3d5 100644 --- a/src/collections/_documentation/integrations/github.md +++ b/src/collections/_documentation/integrations/github.md @@ -53,4 +53,4 @@ When Sentry sees this, we’ll automatically annotate the matching issue with a ## GitHub SSO -[Enable Single Sign-on]({%- link _documentation/learn/sso.md -%}) +[Enable Single Sign-on]({%- link _documentation/product/sso.md -%}) diff --git a/src/collections/_documentation/integrations/splunk.md b/src/collections/_documentation/integrations/splunk.md index c9c68a482639e..ee821f430140c 100644 --- a/src/collections/_documentation/integrations/splunk.md +++ b/src/collections/_documentation/integrations/splunk.md @@ -3,7 +3,7 @@ title: Splunk sidebar_order: 8 --- -Connect Splunk to Sentry with the [Data Forwarding]({%- link _documentation/learn/data-forwarding.md -%}) feature. +Connect Splunk to Sentry with the [Data Forwarding]({%- link _documentation/product/data-forwarding.md -%}) feature. {% capture __alert_content -%} See the [Splunk documentation](http://dev.splunk.com/view/event-collector/SP-CAAAE7F) for specific details on your Splunk installation. diff --git a/src/collections/_documentation/internal/index.md b/src/collections/_documentation/internal/index.md index 58e5e668b671c..efa1ba06201f8 100644 --- a/src/collections/_documentation/internal/index.md +++ b/src/collections/_documentation/internal/index.md @@ -9,3 +9,8 @@ This documentation serves as reference points for developing against Sentry. - [Development Environment]({%- link _documentation/internal/environment.md -%}) - [Documentation Guide]({%- link _documentation/internal/docs.md -%}) - [Web API]({%- link _documentation/internal/api.md -%}) + +If you want to develop against the Sentry API itself see: + +- [Client Development]({%- link _documentation/clientdev/index.md -%}) +- [API Reference]({%- link _documentation/api/index.md -%}) diff --git a/src/collections/_documentation/learn/before-breadcrumb-hint/javascript.md b/src/collections/_documentation/learn/before-breadcrumb-hint/javascript.md new file mode 100644 index 0000000000000..b2a7672b8119f --- /dev/null +++ b/src/collections/_documentation/learn/before-breadcrumb-hint/javascript.md @@ -0,0 +1,18 @@ +```javascript +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + dsn: 'https://@sentry.io/', + beforeBreadcrumb(breadcrumb, hint) { + if (breadcrumb.category === 'ui.click') { + const { target } = hint.event; + if (target.ariaLabel) { + breadcrumb.message = target.ariaLabel; + } + } + return breadcrumb; + }, +}); +``` + +For information about which hints are available see [hints in javascript]({% link _documentation/platforms/javascript/index.md %}#hints). diff --git a/src/collections/_documentation/learn/before-breadcrumb-hint/python.md b/src/collections/_documentation/learn/before-breadcrumb-hint/python.md new file mode 100644 index 0000000000000..e96e41486f07b --- /dev/null +++ b/src/collections/_documentation/learn/before-breadcrumb-hint/python.md @@ -0,0 +1,12 @@ +```python +import sentry_sdk + +def before_breadcrumb(crumb, hint): + if 'log_record' in hint: + crumb['data']['thread'] = hint['log_record'].threadName + return crumb + +sentry_sdk.init(before_breadcrumb=before_breadcrumb) +``` + +For information about which hints are available see [hints in python]({% link _documentation/platforms/python/index.md %}#hints). diff --git a/src/collections/_documentation/learn/before-breadcrumb/javascript.md b/src/collections/_documentation/learn/before-breadcrumb/javascript.md new file mode 100644 index 0000000000000..d52f65fc4e474 --- /dev/null +++ b/src/collections/_documentation/learn/before-breadcrumb/javascript.md @@ -0,0 +1,11 @@ + +```javascript +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + dsn: 'https://@sentry.io/', + beforeBreadcrumb(breadcrumb, hint) { + return breadcrumb.category === 'ui.click' ? null : breadcrumb; + }, +}); +``` diff --git a/src/collections/_documentation/learn/before-breadcrumb/python.md b/src/collections/_documentation/learn/before-breadcrumb/python.md new file mode 100644 index 0000000000000..6f78145b8dd85 --- /dev/null +++ b/src/collections/_documentation/learn/before-breadcrumb/python.md @@ -0,0 +1,10 @@ +```python +import sentry_sdk + +def before_breadcrumb(crumb, hint): + if crumb['category'] == 'a.spammy.Logger': + return None + return crumb + +sentry_sdk.init(before_breadcrumb=before_breadcrumb) +``` diff --git a/src/collections/_documentation/learn/before-send-hint/javascript.md b/src/collections/_documentation/learn/before-send-hint/javascript.md new file mode 100644 index 0000000000000..a8b087fc781c3 --- /dev/null +++ b/src/collections/_documentation/learn/before-send-hint/javascript.md @@ -0,0 +1,15 @@ +```javascript +import * as Sentry from '@sentry/browser'; + +init({ + beforeSend(event, hint) { + const { message } = hint.originalException; + if (message && message.match(/database unavailable/i)) { + event.fingerprint = ['database-unavailable']; + } + return event; + } +}); +``` + +For information about which hints are available see [hints in JavaScript]({% link _documentation/platforms/javascript/index.md %}#hints). diff --git a/src/collections/_documentation/learn/before-send-hint/python.md b/src/collections/_documentation/learn/before-send-hint/python.md new file mode 100644 index 0000000000000..5d69cb9b0d5ba --- /dev/null +++ b/src/collections/_documentation/learn/before-send-hint/python.md @@ -0,0 +1,14 @@ +```python +import sentry_sdk + +def before_send(event, hint): + if 'exc_info' in hint: + exc_type, exc_value, tb = hint['exc_info'] + if isinstance(exc_value, DatabaseUnavailable): + event['fingerprint'] = ['database-unavailable'] + return event + +sentry_sdk.init(before_send=before_send) +``` + +For information about which hints are available see [hints in python]({% link _documentation/platforms/python/index.md %}#hints). diff --git a/src/collections/_documentation/learn/before-send/csharp.md b/src/collections/_documentation/learn/before-send/csharp.md new file mode 100644 index 0000000000000..235d0a299a9e4 --- /dev/null +++ b/src/collections/_documentation/learn/before-send/csharp.md @@ -0,0 +1,15 @@ +A `Func` can be used to mutate, discard (return null), or return a completely new event. + +```csharp +using Sentry; + +SentrySdk.Init(o => +{ + o.BeforeSend = sentryEvent => + { + // Modify the event here: + sentryEvent.ServerName = null; // Don't send server names. + return sentryEvent; + }; +}); +``` diff --git a/src/collections/_documentation/learn/before-send/javascript.md b/src/collections/_documentation/learn/before-send/javascript.md new file mode 100644 index 0000000000000..d523ca1a88cf3 --- /dev/null +++ b/src/collections/_documentation/learn/before-send/javascript.md @@ -0,0 +1,12 @@ +```javascript +Sentry.init({ + beforeSend(event) { + // Modify the event here + if (event.user) { + // Don't send user's email address + delete event.user.email; + } + return event; + } +}); +``` diff --git a/src/collections/_documentation/learn/before-send/python.md b/src/collections/_documentation/learn/before-send/python.md new file mode 100644 index 0000000000000..b1d10c8341489 --- /dev/null +++ b/src/collections/_documentation/learn/before-send/python.md @@ -0,0 +1,11 @@ +```python +import sentry_sdk + +def strip_pii(event): + # modify event here + return event + +sentry_sdk.init( + before_send=strip_pii +) +``` diff --git a/src/collections/_documentation/learn/before-send/rust.md b/src/collections/_documentation/learn/before-send/rust.md new file mode 100644 index 0000000000000..4fab9a7fd98a9 --- /dev/null +++ b/src/collections/_documentation/learn/before-send/rust.md @@ -0,0 +1,10 @@ +```rust +sentry::init(sentry::ClientOptions { + before_send: Some(Arc::new(Box::new(|mut event| { + // Modify event here + event.server_name = None; // Don't send server name + Some(event) + }))), + ..Default::default() +}); +``` diff --git a/src/collections/_documentation/learn/breadcrumbs-example/csharp.md b/src/collections/_documentation/learn/breadcrumbs-example/csharp.md new file mode 100644 index 0000000000000..ebef6d9a36d63 --- /dev/null +++ b/src/collections/_documentation/learn/breadcrumbs-example/csharp.md @@ -0,0 +1,8 @@ +```csharp +using Sentry; + +SentrySdk.AddBreadcrumb( + message: "Authenticated user " + user.email, + category: "auth", + level: BreadcrumbLevel.Info); +``` diff --git a/src/collections/_documentation/learn/breadcrumbs-example/javascript.md b/src/collections/_documentation/learn/breadcrumbs-example/javascript.md new file mode 100644 index 0000000000000..febb1afa3bd63 --- /dev/null +++ b/src/collections/_documentation/learn/breadcrumbs-example/javascript.md @@ -0,0 +1,7 @@ +```javascript +Sentry.addBreadcrumb({ + category: 'auth', + message: 'Authenticated user ' + user.email, + level: 'info' +}); +``` diff --git a/src/collections/_documentation/learn/breadcrumbs-example/python.md b/src/collections/_documentation/learn/breadcrumbs-example/python.md new file mode 100644 index 0000000000000..e23a00ff7ecca --- /dev/null +++ b/src/collections/_documentation/learn/breadcrumbs-example/python.md @@ -0,0 +1,9 @@ +```python +from sentry_sdk import add_breadcrumb + +add_breadcrumb( + category='auth', + message='Authenticated user %s' % user.email, + level='info', +) +``` diff --git a/src/collections/_documentation/learn/breadcrumbs-example/rust.md b/src/collections/_documentation/learn/breadcrumbs-example/rust.md new file mode 100644 index 0000000000000..8e530626e83c5 --- /dev/null +++ b/src/collections/_documentation/learn/breadcrumbs-example/rust.md @@ -0,0 +1,10 @@ +```rust +use sentry::{add_breadcrumb, Breadcrumb, Level}; + +add_breadcrumb(Breadcrumb { + category: Some("auth".into()), + message: Some(format!("Authenticated user {}", user.email)), + level: Level::Info, + ..Default::default() +}); +``` diff --git a/src/collections/_documentation/learn/breadcrumbs.md b/src/collections/_documentation/learn/breadcrumbs.md index 54922d34772f7..dd769a6681ed2 100644 --- a/src/collections/_documentation/learn/breadcrumbs.md +++ b/src/collections/_documentation/learn/breadcrumbs.md @@ -1,47 +1,70 @@ --- title: Breadcrumbs -sidebar_order: 2 +sidebar_order: 3 --- -Sentry supports a concept called Breadcrumbs, which is a trail of events which happened prior to an issue. Often times these events are very similar to traditional logs, but also have the ability to record more rich structured data. +Sentry supports a concept called Breadcrumbs, which is a trail of events which +happened prior to an issue. Often times these events are very similar to +traditional logs, but also have the ability to record more rich structured +data. Each crumb in the trail has the following attributes: Message -: A string describing the event. The most common vector, often used as a drop-in for a traditional log message. +: A string describing the event. The most common vector, often used as a + drop-in for a traditional log message. Data -: A mapping (str => str) of metadata around the event. This is often used instead of message, but may also be used in addition. +: A mapping (str => str) of metadata around the event. This is often used + instead of message, but may also be used in addition. All keys here are + rendered out as table in the breadcrumb on display but some crumb types + might special case some keys. Category -: A category to label the event under. This generally is similar to a logger name, and will let you more easily understand the area an event took place, such as `auth`. +: A category to label the event under. This generally is similar to a logger + name, and will let you more easily understand the area an event took place, + such as `auth`. Level -: The level may be any of `error`, `warning`, `info`, or `debug`. +: The level may be any of `fatal`, `error`, `warning`, `info`, or `debug`. + +Type + +: Additionally a semi internal attribute `type` exists which can control the type + of the breadcrumb. By default all breadcrumbs are recoded as `default` which + makes it appear as a log entry. Other types are available which will + influence how they are rendered. The following types currently exist: + + * `default`: The default breadcrumb rendering. + * `http`: Renders the breadcrumb as HTTP request. + * `error`: Renders the breadcrumb as a hard error. + + Note that the type is not exclusively used to customize the rendering. It's + best not to change the type from the default. ## Recording Crumbs -Each SDK will have an API native to its language, but we’ll use our PHP SDK as an example. - -```php -function loginUser($username, $password) -{ - $sentryClient->breadcrumbs->record(array( - 'message' => 'Authenticating ' . $username, - 'category' => 'auth', - 'level' => 'info', - )); - - // validate login - - $sentryClient->breadcrumbs->record(array( - 'message' => 'Successfully logged in ' . $username, - 'category' => 'auth', - 'level' => 'info', - )); -} -``` +Manual breadcrumb recording is also available and easy to use. This way breadcrumbs +can be added whenever something interesting happens. For instance it might make sense +to record a breadcrumb if the user authenticates or another state change happens. + +{% include components/platform_content.html content_dir='breadcrumbs-example' %} + +## Automatic Breadcrumbs + +SDKs will automatically start recording breadcrumbs by enabling integrations. For instance +the browser JavaScript SDK will automatically record all location changes. + +## Breadcrumb Customization + +SDKs following the unified API support customizing breadcrumbs through the `before_breadcrumb` +hook. This hook is passed an already assembled breadcrumb and in some SDKs an optional +hint. The function can modify the breadcrumb or decide to discard it entirely: + +{% include components/platform_content.html content_dir='before-breadcrumb' %} + +For information about what can be done with the hint see [hints]({% link _documentation/learn/hints.md %}). diff --git a/src/collections/_documentation/learn/capture-error/csharp.md b/src/collections/_documentation/learn/capture-error/csharp.md new file mode 100644 index 0000000000000..0202efaa572bf --- /dev/null +++ b/src/collections/_documentation/learn/capture-error/csharp.md @@ -0,0 +1,14 @@ +In C# you can capture any exception object that you caught: + +```csharp +using Sentry; + +try +{ + AFunctionThatMightFail(); +} +catch (Exception err) +{ + SentrySdk.CaptureException(err); +} +``` diff --git a/src/collections/_documentation/learn/capture-error/javascript.md b/src/collections/_documentation/learn/capture-error/javascript.md new file mode 100644 index 0000000000000..0859e1a53feac --- /dev/null +++ b/src/collections/_documentation/learn/capture-error/javascript.md @@ -0,0 +1,11 @@ +In JavaScript you can pass an error object to `captureException()` to get it captured +as event. Note that it's possible to throw strings as errors in which case no traceback +can be recorded. + +```javascript +try { + aFunctionThatMightFail(); +} catch (err) { + Sentry.captureException(err); +} +``` diff --git a/src/collections/_documentation/learn/capture-error/python.md b/src/collections/_documentation/learn/capture-error/python.md new file mode 100644 index 0000000000000..0c7a17b34c4c8 --- /dev/null +++ b/src/collections/_documentation/learn/capture-error/python.md @@ -0,0 +1,12 @@ +In Python you can either capture a caught exception or the one currently held in +`sys.exc_info()` by not passing an argument: + +```python +from sentry_sdk import capture_exception + +try: + a_potentially_failing_function() +except Exception as e: + # Alternatively the argument can be omitted + capture_exception(e) +``` diff --git a/src/collections/_documentation/learn/capture-error/rust.md b/src/collections/_documentation/learn/capture-error/rust.md new file mode 100644 index 0000000000000..58ddd9c89f318 --- /dev/null +++ b/src/collections/_documentation/learn/capture-error/rust.md @@ -0,0 +1,14 @@ +In Rust you can capture errors that implement the `Fail` trait or that are `failure::Error` +objects: + +```rust +use sentry::integrations::failure::capture_error; + +let result = match function_that_might_fail() { + Ok(result) => result, + Err(err) => { + capture_error(&err); + return Err(err); + } +}; +``` diff --git a/src/collections/_documentation/learn/capture-message/csharp.md b/src/collections/_documentation/learn/capture-message/csharp.md new file mode 100644 index 0000000000000..03d0d16f19cb0 --- /dev/null +++ b/src/collections/_documentation/learn/capture-message/csharp.md @@ -0,0 +1,5 @@ +```csharp +using Sentry; + +SentrySdk.CaptureMessage("Something went wrong"); +``` diff --git a/src/collections/_documentation/learn/capture-message/javascript.md b/src/collections/_documentation/learn/capture-message/javascript.md new file mode 100644 index 0000000000000..edb820b96a915 --- /dev/null +++ b/src/collections/_documentation/learn/capture-message/javascript.md @@ -0,0 +1,3 @@ +```javascript +Sentry.captureMessage('Something weng wrong'); +``` diff --git a/src/collections/_documentation/learn/capture-message/python.md b/src/collections/_documentation/learn/capture-message/python.md new file mode 100644 index 0000000000000..c2d6f21cd5b0f --- /dev/null +++ b/src/collections/_documentation/learn/capture-message/python.md @@ -0,0 +1,5 @@ +```python +from sentry_sdk import capture_message + +capture_message('Something went wrong') +``` diff --git a/src/collections/_documentation/learn/capture-message/rust.md b/src/collections/_documentation/learn/capture-message/rust.md new file mode 100644 index 0000000000000..2341b2ecef1fe --- /dev/null +++ b/src/collections/_documentation/learn/capture-message/rust.md @@ -0,0 +1,5 @@ +```rust +use sentry::{capture_message, Level}; + +capture_message("Something went wrong", Level::Info); +``` diff --git a/src/collections/_documentation/learn/capturing.md b/src/collections/_documentation/learn/capturing.md new file mode 100644 index 0000000000000..7c45a475ddb39 --- /dev/null +++ b/src/collections/_documentation/learn/capturing.md @@ -0,0 +1,37 @@ +--- +title: Capturing Events +sidebar_order: 2 +--- + +Out of the box SDKs will attempt to hook themselves into your runtime environment +or framework to automatically report fatal errors. However in many situations +it's useful to manually report errors or messages to Sentry. This is called +"capturing". When an event is captured it's sent to Sentry and will create a new +issue group or be added to an already existing once based on Sentry's grouping +algorithm. Separately to capturing you can also record "breadcrumbs" that lead +up to an event. Breadcrumbs are different in that they will not create an event +in Sentry but will be buffered until the next event is sent. For more information +have a look at [the breadcrumbs documentation]({% link _documentation/learn/breadcrumbs.md %}). + +## Capturing Errors / Exceptions + +The most common form of capturing is to capture errors. What can be captured as an +error will depend on the platform. In general if you have something that looks like +an exception it can be captured. For some SDKs you can also omit the argument to +`capture_exception` and it will attempt to capture the current exception. + +{% include components/platform_content.html content_dir='capture-error' %} + +## Capturing Messages + +Another common operation is to capture a bare message. A message is just some textual +information that should be sent to Sentry. Typically messages are not emitted but +there are situations when this is useful. + +{% include components/platform_content.html content_dir='capture-message' %} + +## Capturing Events + +SDKs generally also provide ways to capture entire custom event objects. This is what +integrations internally use to capture bespoke events with a lot of extra data fed +into. For more information about that consult the API documentation of the SDK. diff --git a/src/collections/_documentation/learn/config-intro/browser.md b/src/collections/_documentation/learn/config-intro/browser.md new file mode 100644 index 0000000000000..b5f44914ef224 --- /dev/null +++ b/src/collections/_documentation/learn/config-intro/browser.md @@ -0,0 +1,8 @@ +Options are passed to the `init()` as object: + +```javascript +Sentry.init({ + maxBreadcrumbs: 50, + debug: true, +}); +``` diff --git a/src/collections/_documentation/learn/config-intro/csharp.md b/src/collections/_documentation/learn/config-intro/csharp.md new file mode 100644 index 0000000000000..46b3a6a703e58 --- /dev/null +++ b/src/collections/_documentation/learn/config-intro/csharp.md @@ -0,0 +1,16 @@ +Options can be set by passing a callback to the `Init()` method which will +pass the option object along for modifications: + +```csharp +using Sentry; + +using (SentrySdk.Init(o => +{ + o.Dsn = "___PUBLIC_DSN___"; + o.MaxBreadcrumbs = 50; + o.Debug = true; +}) +{ + // app code here +} +``` diff --git a/src/collections/_documentation/learn/config-intro/javascript.md b/src/collections/_documentation/learn/config-intro/javascript.md new file mode 100644 index 0000000000000..637e144caac52 --- /dev/null +++ b/src/collections/_documentation/learn/config-intro/javascript.md @@ -0,0 +1,9 @@ +Options are passed to the `init()` as object: + +```javascript +Sentry.init({ + dsn: '___PUBLIC_DSN___', + maxBreadcrumbs: 50, + debug: true, +}) +``` diff --git a/src/collections/_documentation/learn/config-intro/python.md b/src/collections/_documentation/learn/config-intro/python.md new file mode 100644 index 0000000000000..80de866d72587 --- /dev/null +++ b/src/collections/_documentation/learn/config-intro/python.md @@ -0,0 +1,11 @@ +Options are passed to the `init()` function as optional keyword arguments: + +```python +import sentry_sdk + +sentry_sdk.init( + '___PUBLIC_DSN___', + max_breadcrumbs=50, + debug=True, +) +``` diff --git a/src/collections/_documentation/learn/config-intro/rust.md b/src/collections/_documentation/learn/config-intro/rust.md new file mode 100644 index 0000000000000..e4e5a01cb059b --- /dev/null +++ b/src/collections/_documentation/learn/config-intro/rust.md @@ -0,0 +1,11 @@ +Options are passed to the `init()` as tuple where the first argument is the DSN and the second the options: + +```rust +use sentry; + +sentry::init(("___PUBLIC_DSN___", sentry::ClientOptions { + max_breadcrumbs: 50, + debug: true, + ..Default::default() +})); +``` diff --git a/src/collections/_documentation/learn/config-keys/max_breadcrumbs.md b/src/collections/_documentation/learn/config-keys/max_breadcrumbs.md new file mode 100644 index 0000000000000..7dedf6f29a885 --- /dev/null +++ b/src/collections/_documentation/learn/config-keys/max_breadcrumbs.md @@ -0,0 +1,3 @@ +### {% include components/config_key.html key='max-breadcrumbs' %} + +This variable controls the total amount of keys that should be used. diff --git a/src/collections/_documentation/learn/configuration.md b/src/collections/_documentation/learn/configuration.md new file mode 100644 index 0000000000000..66be641b4770e --- /dev/null +++ b/src/collections/_documentation/learn/configuration.md @@ -0,0 +1,208 @@ +--- +title: Configuration +sidebar_order: 1 +--- + +SDKs are configurable in many ways. The options are largely standardized between SDKs but there are +some differences to better acommodate platform peculiarities. Options are set when the SDK is first +initialized. + +{% include components/platform_content.html content_dir='config-intro' %} + +## Common Options + +The list of common options across SDKs. These work more or less the same in all SDKs but some +subtle differences will exist to better support the platform. + +{:.config-key} +### dsn + +The _DSN_ tells the SDK where to send the events to. This option is always required and different SDKs might pick this up from an environment +variable (`SENTRY_DSN`) or in the case if you are using the CDN version or the Browser SDK, it's already configured for you. + +{:.config-key} +### debug + +Turns debug mode on or off. If debug is enabled SDK will attempt to print out useful debugging +information if something goes wrong with sending the event. The default is always `false` and +it's generally not recommended to turn it on in production but doing so will not cause any +safety concerns. + +{:.config-key} +### release + +Sets the release. Some SDKs will try to automatically configure a release out of the box but +if you have the chance it's a better idea to manually set it. That way it's guaranteed to be +in sync with your deploy integrations or sourcemap uploads. + +Release names are just strings but some formats are detected by Sentry and might be rendered +differently. For more information have a look at [the releases documentation]({% link _documentation/learn/releases.md %}). + +{:.config-key} +### environment + +Sets the environment. This string is freeform and not set by default. A release can be associated +with more than one environment to separate them in the UI (think `staging` vs `prod` or similar). + +{:.config-key} +### repos + +For repository integration, the repository identifiers need to be sent along. For more information +have a look at [the releases documentation]({% link _documentation/learn/releases.md %}). + +{:.config-key} +### sample-rate + +Configures the sample rate as a percentage of events to be sent in the range of `0.0` to `1.0`. The +default is `1.0` which means that 100% of events are sent. If set to `0.1` only 10% of events will +be sent. Events are picked randomly. + +{:.config-key} +### max-breadcrumbs + +This variable controls the total amount of breadcrumbs that should be captured. This defaults +to `100`. + +{:.config-key} +### attach-stacktrace + +When enabled stacktraces are automatically attached to all messages logged. Note that stacktraces +are always attached to exceptions but when this is set stacktraces are also sent with messages. This, for instance, means that stacktraces appear next to all log messages. + +It's important to note that grouping in Sentry is different for events with stacktraces and without. +This means that you will get new groups as you enable or disable this flag for certain events. + +This feature is `off` by default. + +{:.config-key} +### send-default-pii + +If this flag is enabled, certain personally identifiable information is added by active +integrations. Without this flag they are never added to the event, to begin with. If possible +it's recommended to turn on this feature and use the server side PII stripping to remove the +values instead. + +{:.config-key} +### server-name + +{% unsupported browser %} +Can be used to supply a "server name". When provided the name of the server is sent along and +persisted in the event. Note that for many integrations the server name actually corresponds to +the device hostname even in situations where the machine is not actually a server. Most SDKs +will attempt to auto-discover this value. +{% endunsupported %} + +{:.config-key} +### blacklist-urls + +{% supported browser %} +A pattern for error URLs which should not be sent to Sentry. By default, all errors will be sent. +{% endsupported %} + +{:.config-key} +### whitelist-urls + +{% supported browser %} +A pattern for error URLs which should exclusively be sent to Sentry. By default, all errors +will be sent. +{% endsupported %} + +{:.config-key} +### request-bodies + +{% supported python %} +This parameter controls if integrations should capture HTTP request bodies. It can be set to one +of the following values: + +* `never`: request bodies are never sent. +* `small`: only small request bodies will be captured where the cutoff for small depends on the SDK (typically 4KB) +* `medium`: medium-sized requests and small requests will be captured. (typically 10KB) +* `always`: the SDK will always capture the request body for as long as sentry can make sense of it +{% endsupported %} + +{:.config-key} +### with-locals + +{% supported python %} +When enabled local variables are sent along with stackframes. This can have a performance +and PII impact. Enabled by default on platforms where this is available. +{% endsupported %} + +## Integration Configuration + +For many platform SDKs integrations can be configured alongside it. On some platforms that +happen as part of the `init()` call, in some others, different patterns apply. + +{:.config-key} +### integrations + +{% unsupported csharp aspnetcore rust %} +In some SDKs the integrations are configured through this parameter on library initialization. +For more information have a look at the specific integration documentation. +{% endunsupported %} + +{:.config-key} +### default-integrations + +{% unsupported csharp aspnetcore rust %} +This can be used to disable integrations that are added by default. When set to `false` no +default integrations are added. +{% endunsupported %} + +## Hooks + +These options can be used to hook the SDK in various ways to customize the reporting of events. + +{:.config-key} +### before-send + +This function is called with an SDK specific event object and can return a modified event object or +nothing to skip reporting the event. This can be used for instance for manual PII stripping before +sending. + +{:.config-key} +### before-breadcrumb + +This function is called with an SDK specific breadcrumb object before the breadcrumb is added to the +scope. When nothing is returned from the function the breadcrumb is dropped. The callback typically +gets a second argument (called a "hint") which contains the original object that the breadcrumb was +created from to further customize what the breadcrumb should look like. + +## Transport Options + +Transports are used to send events to Sentry. This can be customized to some degree to better +support highly specific deployments. + +{:.config-key} +### transport + +This switches out the transport that is used to send events. How this works depends on the SDK. It +can, for instance, be used to capture events for unit-testing or to send it through some more complex +setup that requires proxy authentication. + +{:.config-key} +### http-proxy + +When set a proxy can be configured that should be used for outbound requests. This is also used for +HTTPS requests unless a separate `https-proxy` is configured. Note however that not all SDKs +support a separate HTTPS proxy. SDKs will attempt to default to the system-wide configured proxy +if possible. For instance, on unix systems, the `http_proxy` environment variable will be picked up. + +{:.config-key} +### https-proxy + +{% unsupported csharp aspnetcore %} +Configures a separate proxy for outgoing HTTPS requests. This value might not be supported by all +SDKs. When not supported the `http-proxy` value is also used for HTTPS requests at all times. +{% endunsupported %} + +{:.config-key} +### shutdown-timeout + +{% unsupported browser %} +Controls how many seconds to wait before shutting down. Sentry SDKs send events from a background +queue and this queue is given a certain amount to drain pending events. The default is SDK specific +but typically around 2 seconds. Setting this value too low will most likely cause problems for +sending events from command line applications. Setting it too high will cause the application to +block for a long time for users with network connectivity problems. +{% endunsupported %} diff --git a/src/collections/_documentation/learn/configure-scope/csharp.md b/src/collections/_documentation/learn/configure-scope/csharp.md new file mode 100644 index 0000000000000..8b534eea79439 --- /dev/null +++ b/src/collections/_documentation/learn/configure-scope/csharp.md @@ -0,0 +1,22 @@ +```csharp +using Sentry; + +SentrySdk.ConfigureScope(scope => +{ + scope.SetTag("my-tag", "my value"); + scope.User = new User + { + Id = "42", + Email = "john.doe@example.com" + }; +}); +``` + +Or when an asynchronous call is required: + +```csharp +await SentrySdk.ConfigureScopeAsync(scope => +{ + scope.User = await _context.Users.FindAsync(id); +}); +``` \ No newline at end of file diff --git a/src/collections/_documentation/learn/configure-scope/javascript.md b/src/collections/_documentation/learn/configure-scope/javascript.md new file mode 100644 index 0000000000000..f758d7e81ba7e --- /dev/null +++ b/src/collections/_documentation/learn/configure-scope/javascript.md @@ -0,0 +1,9 @@ +```javascript +Sentry.configureScope((scope) => { + scope.setTag("my-tag", "my value"); + scope.setUser({ + id: 42, + email: "john.doe@example.com" + }); +}); +``` diff --git a/src/collections/_documentation/learn/configure-scope/python.md b/src/collections/_documentation/learn/configure-scope/python.md new file mode 100644 index 0000000000000..c898bd384278b --- /dev/null +++ b/src/collections/_documentation/learn/configure-scope/python.md @@ -0,0 +1,7 @@ +```python +from sentry_sdk import configure_scope + +with configure_scope() as scope: + scope.set_tag("my-tag", "my value") + scope.user = {'id': 42, 'email': 'john.doe@example.com'} +``` diff --git a/src/collections/_documentation/learn/configure-scope/rust.md b/src/collections/_documentation/learn/configure-scope/rust.md new file mode 100644 index 0000000000000..fe0c9d62b37be --- /dev/null +++ b/src/collections/_documentation/learn/configure-scope/rust.md @@ -0,0 +1,12 @@ +```rust +use sentry::{configure_scope, User}; + +configure_scope(|scope| { + scope.set_tag("my-tag", "my value"); + scope.set_user(Some(User { + id: Some(42.to_string()), + email: Some("john.doe@exmaple.com".into()), + ..Default::default() + })); +}); +``` diff --git a/src/collections/_documentation/learn/context.md b/src/collections/_documentation/learn/context.md index 96d8fb9ca34b0..68946d3c75282 100644 --- a/src/collections/_documentation/learn/context.md +++ b/src/collections/_documentation/learn/context.md @@ -1,28 +1,42 @@ --- title: Context sidebar_order: 4 +example_tag_name: page_locale +example_tag_value: de-at +example_user_email: 'john.doe@example.com' +example_extra_key: character_name +example_extra_value: 'Mighty Fighter' --- Sentry supports additional context with events. Often this context is shared amongst any issue captured in its lifecycle, and includes the following components: -**Tags** - -: Key/value pairs which generate breakdowns charts and search filters - **User** : Information about the current actor -**Extra** +**Structured Contexts** + +: Specific structured contexts (OS info, runtime information etc.). This is normally set automatically. + +**Tags** + +: Key/value pairs which generate breakdowns charts and search filters -: Arbitrary unstructured data which is stored with an event sample +**Unstructured Extra** -Context is considered to be request state, and thus should be cleared out at the beginning (or end) of each operation. SDKs like the JavaScript SDK usually won’t need to worry about this as they generally are not long lived. +: Arbitrary unstructured data which is stored with an event sample. + +Context is held on the current scope and thus is cleared out at the end of each operation (request etc.). For more information +[have a look at the scopes and hub documentation](({%- link _documentation/learn/scopes.md -%}). ## Tagging Events Sentry implements a system it calls tags. Tags are various key/value pairs that get assigned to an event, and can later be used as a breakdown or quick access to finding related events. +Most SDKs generally support configuring tags by configuring the scope: + +{% include components/platform_content.html content_dir='set-tag' %} + Several common uses for tags include: - The hostname of the server @@ -37,28 +51,14 @@ Once you’ve starting sending tagged data, you’ll see it show up in a few pla We’ll automatically index all tags for an event, as well as the frequency and the last time a value has been seen. Even more so, we keep track of the number of distinct tags, and can assist in you determining hotspots for various issues. -Most SDKs generally support configuring tags at the global SDK level configuration, as well as on a per event basis. - -For example, in the JavaScript SDK: - -```javascript -Raven.captureMessage('hello world!', {tags: { - locale: 'en-us' -}}); -``` - -Or to bind tags to the request context: - -```javascript -Raven.setTagsContext({ - environment: "production" -}); -``` - ## Capturing the User Sending users to Sentry will unlock a number of features, primarily the ability to drill down into the number of users affecting an issue, as well to get a broader sense about the quality of the application. +Capturing the user is fairly straight forward: + +{% include components/platform_content.html content_dir='set-user' %} + Users consist of a few key pieces of information which are used to construct a unique identity in Sentry. Each of these is optional, but one **must** be present in order for the user to be captured: `id` @@ -79,25 +79,8 @@ Users consist of a few key pieces of information which are used to construct a u Additionally you can provide arbitrary key/value pairs beyond the reserved names and those will be stored with the user. -Capturing the user is fairly straight forward. For example, in the JavaScript SDK: - -```javascript -Raven.setUserContext({ - email: 'foo@example.com' -}); -``` - ## Extra Context -In addition to the structured context that Sentry understands, you can send arbitrary key/value pairs of data which will be stored alongside the event. These are not indexed and are simply used to add additional information about what might be happening. - -Extra context can generally be passed in both the event constructor, as well as the global context state: - -For example, in the JavaScript SDK: +In addition to the structured context that Sentry understands, you can send arbitrary key/value pairs of data which will be stored alongside the event. These are not indexed and are simply used to add additional information about what might be happening: -```javascript -Raven.setExtraContext({ - arbitrary: {key: value}, - foo: "bar" -}); -``` +{% include components/platform_content.html content_dir='set-extra' %} diff --git a/src/collections/_documentation/learn/drain-example/csharp.md b/src/collections/_documentation/learn/drain-example/csharp.md new file mode 100644 index 0000000000000..4adc2e4dc7e3a --- /dev/null +++ b/src/collections/_documentation/learn/drain-example/csharp.md @@ -0,0 +1,11 @@ +The .NET SDK automatically shuts down and waits `ShutdownTimeout` seconds before that happens +when the `Init`'s return value is disposed: + +```csharp +using (SentrySdk.Init(...)) +{ + // App code +} +``` + +In case of an unhandled exception that will crash the app, the SDK automatically disposes itself. \ No newline at end of file diff --git a/src/collections/_documentation/learn/drain-example/javascript.md b/src/collections/_documentation/learn/drain-example/javascript.md new file mode 100644 index 0000000000000..c1fba56d3aeb0 --- /dev/null +++ b/src/collections/_documentation/learn/drain-example/javascript.md @@ -0,0 +1,12 @@ +The client provides a close method that optionally takes the time in milliseconds for how long it +waits and will return a promise that resolves when everything was flushed or the timeout kicked +in. + +```javascript +let client = Sentry.getCurrentHub().getClient(); +if (client) { + client.close(2000).then(function() { + process.exit(); + }); +} +``` diff --git a/src/collections/_documentation/learn/drain-example/python.md b/src/collections/_documentation/learn/drain-example/python.md new file mode 100644 index 0000000000000..fd333fca90ec7 --- /dev/null +++ b/src/collections/_documentation/learn/drain-example/python.md @@ -0,0 +1,10 @@ +The Python SDK automatically drains on shutdown unless the `AtExitIntegration` is removed or the `shutdown_timeout` +config key is set to 0. To manually drain the client provides a `close` method: + +```python +from sentry_sdk import Hub + +client = Hub.current.client +if client is not None: + client.close(timeout=2.0) +``` diff --git a/src/collections/_documentation/learn/drain-example/rust.md b/src/collections/_documentation/learn/drain-example/rust.md new file mode 100644 index 0000000000000..ff781cd8824df --- /dev/null +++ b/src/collections/_documentation/learn/drain-example/rust.md @@ -0,0 +1,12 @@ +When the Rust SDK initializes a guard is returned from the `init` function. The destructor +will automatically wait `shutdown_timeout` seconds. This means you just need to hold on to +the guard and make sure it disposes on shutdown. Alternatively the client can be closed: + +```javascript +use std::time::Duration; +use sentry::Hub; + +if let Some(client) = Hub.current().client() { + client.close(Some(Duration::from_secs(2))); +} +``` diff --git a/src/collections/_documentation/learn/draining.md b/src/collections/_documentation/learn/draining.md new file mode 100644 index 0000000000000..0a78db033eb42 --- /dev/null +++ b/src/collections/_documentation/learn/draining.md @@ -0,0 +1,17 @@ +--- +title: 'Shutdown and Draining' +sidebar_order: 16 +--- + +Most SDKs use a background queue to send out events. Because the queue sends asynchronously in the background +it means that some events might be lost if the application shuts down unexpectedly. To prevent this all SDKs +provide mechanisms to cope with this. + +Typically SDKs provide two ways to shut down: a controlled shutdown where the system will wait up to about two +seconds to flush out events (configurable) and an uncontrolled shutdown (also referred to as "killing" the +client). + +{% include components/platform_content.html content_dir='drain-example' %} + +After shutdown the client cannot be used any more so make sure to only do that right before you shut down +the application. diff --git a/src/collections/_documentation/learn/environments.md b/src/collections/_documentation/learn/environments.md index 87c21360c891b..245cbb56a1ec3 100644 --- a/src/collections/_documentation/learn/environments.md +++ b/src/collections/_documentation/learn/environments.md @@ -1,6 +1,7 @@ --- title: Environments sidebar_order: 5 +example_environment: "staging" --- _Note: The environments feature is only available for early adopters. You can enable early adopter features by navigating to your organization settings._ @@ -35,11 +36,6 @@ If you would like to see Sentry filtered by a certain environment every time you # How to send environment data -Environment data is sent to Sentry by tagging issues via your SDK. You can send environment data to Sentry using the following SDKs: +Environment data is sent to Sentry by tagging issues via your SDK: -- [Javascript]({%- link _documentation/clients/javascript/config.md -%}) -- [Node.js]({%- link _documentation/clients/node/config.md -%}#configuration) -- [Python]({%- link _documentation/clients/python/advanced.md -%}) -- [Ruby]({%- link _documentation/clients/ruby/config.md -%}) -- [php]({%- link _documentation/clients/php/config.md -%}) -- [Java]({%- link _documentation/clients/java/config.md -%}) +{% include components/platform_content.html content_dir='set-environment' %} diff --git a/src/collections/_documentation/learn/getting-started-config/aspnetcore.md b/src/collections/_documentation/learn/getting-started-config/aspnetcore.md new file mode 100644 index 0000000000000..95632ed7ffa8d --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-config/aspnetcore.md @@ -0,0 +1,10 @@ +Add Sentry to `Program.cs` through the `WebHostBuilder`: + +```csharp +public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + // Add this: + .UseSentry("___PUBLIC_DSN___") + .Build(); +``` diff --git a/src/collections/_documentation/learn/getting-started-config/browser.md b/src/collections/_documentation/learn/getting-started-config/browser.md new file mode 100644 index 0000000000000..a70e09123c803 --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-config/browser.md @@ -0,0 +1,2 @@ +When using the CDN for browser, no further configuration is required. +If you want to know more, please visit [What does the CDN version provide?]({% link _documentation/platforms/javascript/browser.md %}#what-does-the-cdn-version-provide). diff --git a/src/collections/_documentation/learn/getting-started-config/browsernpm.md b/src/collections/_documentation/learn/getting-started-config/browsernpm.md new file mode 100644 index 0000000000000..768e67e773529 --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-config/browsernpm.md @@ -0,0 +1,7 @@ +You should `init` the Sentry browser SDK as soon as possible during your application load up: + +```javascript +import * as Sentry from '@sentry/browser'; + +Sentry.init({ dsn: '___PUBLIC_DSN___' }); +``` diff --git a/src/collections/_documentation/learn/getting-started-config/cordova.md b/src/collections/_documentation/learn/getting-started-config/cordova.md new file mode 100644 index 0000000000000..38a4a974c593c --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-config/cordova.md @@ -0,0 +1,8 @@ +You should `init` the SDK in the `deviceReady` function, to make sure the native integrations runs. For more details about Cordova [click here]({%- link _documentation/platforms/javascript/cordova.md -%}) + +```javascript +onDeviceReady: function() { + var Sentry = cordova.require("sentry-cordova.Sentry"); + Sentry.init({ dsn: '___PUBLIC_DSN___' }); +} +``` diff --git a/src/collections/_documentation/learn/getting-started-config/csharp.md b/src/collections/_documentation/learn/getting-started-config/csharp.md new file mode 100644 index 0000000000000..22f3244d66c5b --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-config/csharp.md @@ -0,0 +1,8 @@ +You should initialize the SDK as early as possible, like in the `Main` method in `Program.cs`: + +```csharp +using (SentrySdk.Init("___PUBLIC_DSN___")) +{ + // App code +} +``` diff --git a/src/collections/_documentation/learn/getting-started-config/electron.md b/src/collections/_documentation/learn/getting-started-config/electron.md new file mode 100644 index 0000000000000..0e10d755d39b3 --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-config/electron.md @@ -0,0 +1,8 @@ +You need to call `init` in your `main` and every `renderer` process you spawn. +For more details about Electron [click here]({%- link _documentation/platforms/javascript/electron/index.md -%}) + +```javascript +import * as Sentry from '@sentry/electron'; + +Sentry.init({dsn: '___PUBLIC_DSN___'}); +``` diff --git a/src/collections/_documentation/learn/getting-started-config/node.md b/src/collections/_documentation/learn/getting-started-config/node.md new file mode 100644 index 0000000000000..c2545d7e46d75 --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-config/node.md @@ -0,0 +1,6 @@ +You need to inform the Sentry Node SDK about your DSN: + +```javascript +const Sentry = require('@sentry/node'); +Sentry.init({ dsn: '___PUBLIC_DSN___' }); +``` diff --git a/src/collections/_documentation/learn/getting-started-config/python.md b/src/collections/_documentation/learn/getting-started-config/python.md new file mode 100644 index 0000000000000..d3fa9953b343a --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-config/python.md @@ -0,0 +1,4 @@ +```python +import sentry_sdk +sentry_sdk.init("___PUBLIC_DSN___") +``` diff --git a/src/collections/_documentation/learn/getting-started-config/rust.md b/src/collections/_documentation/learn/getting-started-config/rust.md new file mode 100644 index 0000000000000..5cc70046e42be --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-config/rust.md @@ -0,0 +1,4 @@ +```rust +extern crate sentry; +let _guard = sentry::init("___PUBLIC_DSN___"); +``` diff --git a/src/collections/_documentation/learn/getting-started-install/aspnetcore.md b/src/collections/_documentation/learn/getting-started-install/aspnetcore.md new file mode 100644 index 0000000000000..d42db22bed273 --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-install/aspnetcore.md @@ -0,0 +1,11 @@ +Install the **NuGet** package: + +Package Manager: +```shell +Install-Package Sentry.AspNetCore -Version {% sdk_version sentry.dotnet.aspnetcore %} +``` + +.NET Core CLI: +```shell +dotnet add package Sentry.AspNetCore -v {% sdk_version sentry.dotnet.aspnetcore %} +``` diff --git a/src/collections/_documentation/learn/getting-started-install/browser.md b/src/collections/_documentation/learn/getting-started-install/browser.md new file mode 100644 index 0000000000000..36a4a218dac0d --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-install/browser.md @@ -0,0 +1,13 @@ +The quickest way to get started is to use the CDN hosted version of the JavaScript browser SDK: + +```html + +``` + +{% wizard hide %} +{% include components/alert.html + title="Don't like the CDN?" + content="You can also [NPM install our browser library](?platform=browsernpm)" + level="info" +%} +{% endwizard %} \ No newline at end of file diff --git a/src/collections/_documentation/learn/getting-started-install/browsernpm.md b/src/collections/_documentation/learn/getting-started-install/browsernpm.md new file mode 100644 index 0000000000000..dfca924d24f90 --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-install/browsernpm.md @@ -0,0 +1,17 @@ +If you are using `yarn` you can add our package as a dependency easily: + +```bash +$ yarn add @sentry/browser@{% sdk_version sentry.javascript.browser %} +``` + +Or alternatively you can npm install it: + +```bash +$ npm install @sentry/browser@{% sdk_version sentry.javascript.browser %} +``` + +{% include components/alert.html + title="Want a CDN?" + content="You can also [use our more comfortable CDN version](?platform=browser)" + level="info" +%} diff --git a/src/collections/_documentation/learn/getting-started-install/cordova.md b/src/collections/_documentation/learn/getting-started-install/cordova.md new file mode 100644 index 0000000000000..b7e2b58bbc231 --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-install/cordova.md @@ -0,0 +1,5 @@ +Install our SDK using the cordova command: + +```bash +$ cordova plugin add sentry-cordova@{% sdk_version sentry.javascript.cordova %} +``` diff --git a/src/collections/_documentation/learn/getting-started-install/csharp.md b/src/collections/_documentation/learn/getting-started-install/csharp.md new file mode 100644 index 0000000000000..613a630a78ff9 --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-install/csharp.md @@ -0,0 +1,11 @@ +Install the **NuGet** package: + +Package Manager: +```shell +Install-Package Sentry -Version {% sdk_version sentry.dotnet %} +``` + +.NET Core CLI: +```shell +dotnet add package Sentry -v {% sdk_version sentry.dotnet %} +``` diff --git a/src/collections/_documentation/learn/getting-started-install/electron.md b/src/collections/_documentation/learn/getting-started-install/electron.md new file mode 100644 index 0000000000000..d60d2b75857e2 --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-install/electron.md @@ -0,0 +1,11 @@ +If you are using `yarn` you can add our package as a dependency easily: + +```bash +$ yarn add @sentry/electron@{% sdk_version sentry.javascript.electron %} +``` + +Or alternatively you can npm install it: + +```bash +$ npm install @sentry/electron@{% sdk_version sentry.javascript.electron %} +``` diff --git a/src/collections/_documentation/learn/getting-started-install/node.md b/src/collections/_documentation/learn/getting-started-install/node.md new file mode 100644 index 0000000000000..9cdf057f86b40 --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-install/node.md @@ -0,0 +1,11 @@ +If you are using `yarn` you can add our package as a dependency easily: + +```bash +$ yarn add @sentry/node@{% sdk_version sentry.javascript.node %} +``` + +Or alternatively you can npm install it: + +```bash +$ npm install @sentry/node@{% sdk_version sentry.javascript.node %} +``` diff --git a/src/collections/_documentation/learn/getting-started-install/python.md b/src/collections/_documentation/learn/getting-started-install/python.md new file mode 100644 index 0000000000000..4ab922bee185a --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-install/python.md @@ -0,0 +1,5 @@ +Install our Python SDK using [`pip`](https://pip.pypa.io/en/stable/): + +```bash +$ pip install --upgrade sentry-sdk=={% sdk_version sentry.python %} +``` diff --git a/src/collections/_documentation/learn/getting-started-install/rust.md b/src/collections/_documentation/learn/getting-started-install/rust.md new file mode 100644 index 0000000000000..11afe36d36738 --- /dev/null +++ b/src/collections/_documentation/learn/getting-started-install/rust.md @@ -0,0 +1,6 @@ +To add Sentry to your Rust project you just need to add a new dependency to your `Cargo.toml`: + +```toml +[dependencies] +sentry = "{% sdk_version sentry.rust %}" +``` diff --git a/src/collections/_documentation/learn/hints.md b/src/collections/_documentation/learn/hints.md new file mode 100644 index 0000000000000..ab2cf490dbe02 --- /dev/null +++ b/src/collections/_documentation/learn/hints.md @@ -0,0 +1,29 @@ +--- +title: Hint-based Customization +sidebar_order: 3 +--- + +When an SDK creates an event or breadcrumb for transmission that is typically created from some sort +of source object. For instance an error event is typically created from a log record or exception +instance. For better customization SDKs send these objects to certain callbacks (`before-send`, +`before-breadcrumb` or the event processor system in the SDKs). + +# Before Send + +The `before-send` callback is passed the event and a second argument `hint` which holds one or more +hints. Typically this hint holds the original exception so that additional data can be extracted +or grouping be affected. + +In this example the fingerprint is forced to a common value if an exception of a certain type has +been caught: + +{% include components/platform_content.html content_dir='before-send-hint' %} + +# Before Breadcrumb + +Similar to `before-breadcrumb` hints are also supported here. This is particularly useful when +breadcrumbs should be augmented or changed with some extra data from log records or events. The +following example shows a typical situation where you might want to extract extra information and +how to do it: + +{% include components/platform_content.html content_dir='before-breadcrumb-hint' %} diff --git a/src/collections/_documentation/learn/quickstart.md b/src/collections/_documentation/learn/quickstart.md index b26a19a2512cc..af0c37d0c03b4 100644 --- a/src/collections/_documentation/learn/quickstart.md +++ b/src/collections/_documentation/learn/quickstart.md @@ -11,73 +11,58 @@ Sentry is designed to be very simple to get off the ground, yet powerful to grow Getting started with Sentry is a three step process: 1. [Sign up for an account](https://sentry.io/signup/) -2. [Configure an SDK](#pick-a-client-integration) -3. [About the DSN](#configure-the-dsn) +2. [Install your SDK](#pick-a-client-integration) +2. [Configure it](#configure-the-sdk) -## Configure an SDK {#pick-a-client-integration} +## Install an SDK {#pick-a-client-integration} -Sentry captures data by using an SDK within your application’s runtime. These are platform specific, and allow Sentry to have a deep understanding of both how your application works. In case your environment is very specific, you can also roll your own SDK using our document [_SDK API_]({%- link _documentation/clientdev/index.md -%}). - -Popular integrations are: - -- [_Python_]({%- link _documentation/clients/python/index.md -%}) -- [_JavaScript_]({%- link _documentation/clients/javascript/index.md -%}) -- [_PHP_]({%- link _documentation/clients/php/index.md -%}) -- [_Ruby_]({%- link _documentation/clients/ruby/index.md -%}) -- [_Java_]({%- link _documentation/clients/java/index.md -%}) -- [_Cocoa_]({%- link _documentation/clients/cocoa/index.md -%}) -- [_C#_]({%- link _documentation/clients/csharp/index.md -%}) -- [_Go_]({%- link _documentation/clients/go/index.md -%}) -- [_Elixir_]({%- link _documentation/clients/elixir/index.md -%}) - -For exact configuration for the integration consult the corresponding documentation. For all SDKs however, the basics are the same. - -## About the DSN {#configure-the-dsn} - -After you complete setting up a project in Sentry, you’ll be given a value which we call a _DSN_, or _Data Source Name_. It looks a lot like a standard URL, but it’s actually just a representation of the configuration required by the Sentry SDKs. It consists of a few pieces, including the protocol, public key, the server address, and the project identifier. +Sentry captures data by using an SDK within your application’s runtime. These are platform specific and allow Sentry to have a deep understanding of both how your application works. In case your environment is very specific, you can also roll your own SDK using our document [_SDK API_]({%- link _documentation/clientdev/index.md -%}). {% capture __alert_content -%} -As of Sentry 9, we removed the need to provide the secret key. Older versions of SDKs may still require you to provide the DSN including the secret which is now called DSN (Legacy). Please check the corresponding docs of the SDK you are using if you still need to provide the secret. +Your platform is not listed? There are more SDKs we support: [list of SDKs]({%- link _documentation/platforms/index.md -%}) {%- endcapture -%} {%- include components/alert.html title="Note" content=__alert_content %} -The DSN can be found in Sentry by navigating to [Project Name] -> Project Settings -> Client Keys (DSN). Its template resembles the following: +{% wizard %} +{% include components/platform_content.html content_dir='getting-started-install' %} -``` -'{PROTOCOL}://{PUBLIC_KEY}@{HOST}/{PATH}{PROJECT_ID}' -``` +{% wizard hide %} +## Configure the SDK {#configure-the-sdk} -If you are using the Hosted Sentry and signed into your account, the documentation will refer to your actual DSNs. You can select the correct one which will adjust the examples for easy copy pasting: +After you completed setting up a project in Sentry, you’ll be given a value which we call a _DSN_, or _Data Source Name_. It looks a lot like a standard URL, but it’s actually just a representation of the configuration required by the Sentry SDKs. It consists of a few pieces, including the protocol, public key, the server address, and the project identifier. +{% endwizard %} -``` -'___PUBLIC_DSN___' -``` +{% include components/platform_content.html content_dir='getting-started-config' %} -It is composed of five important pieces: +Most SDKs will now automatically collect data if available, some require some extra configuration as automatic error collecting is not +available due to platform limitations. +{% endwizard %} -- The Protocol used. This can be one of the following: http or https. -- The public key to authenticate the SDK. -- The destination Sentry server. -- The project ID which the authenticated user is bound to. - -You’ll have a few options for plugging the DSN into the SDK, depending on what it supports. At the very least, most SDKs will allow you to set it up as the `SENTRY_DSN` environment variable or by passing it into the SDK’s constructor. +{% capture __alert_content -%} +As of Sentry 9, we removed the need to provide the secret key. Older versions of SDKs may still require you to provide the DSN including the secret which is now called DSN (Legacy). Please check the corresponding docs of the SDK you are using if you still need to provide the secret. -For example for the JavaScript SDK it works roughly like this: +The DSN can be found in Sentry by navigating to [Project Name] -> Project Settings -> Client Keys (DSN). Its template resembles the following: -```javascript -import Raven from 'raven-js' -Raven.config('___PUBLIC_DSN___') +``` +'{PROTOCOL}://{PUBLIC_KEY}@{HOST}/{PROJECT_ID}' ``` Note: If you’re using Heroku, and you’ve added Hosted Sentry via the standard addon hooks, most SDKs will automatically pick up the `SENTRY_DSN` environment variable that we’ve already configured for you. +{%- endcapture -%} +{%- include components/alert.html + title="Note" + content=__alert_content +%} ## Next Steps Now that you’ve got basic reporting setup, you’ll want to explore adding additional context to your data. +- [_manual error and event capturing_]({%- link _documentation/learn/capturing.md -%}) +- [_configuration options_]({%- link _documentation/learn/configuration.md -%}) - [_identifying users via context_]({%- link _documentation/learn/context.md -%}) - [_tracing issues with breadcrumbs_]({%- link _documentation/learn/breadcrumbs.md -%}) - [_capturing user feedback on crashes_]({%- link _documentation/learn/user-feedback.md -%}) diff --git a/src/collections/_documentation/learn/releases.md b/src/collections/_documentation/learn/releases.md index 2d6260c3066b9..bc699b9dc85cc 100644 --- a/src/collections/_documentation/learn/releases.md +++ b/src/collections/_documentation/learn/releases.md @@ -1,6 +1,7 @@ --- title: Releases sidebar_order: 3 +release_identifier: "my-project-name@2.3.12" --- A release is a version of your code that is deployed to an environment. When you give Sentry information about your releases, you unlock a number of new features: @@ -22,13 +23,9 @@ Configuring releases fully is a 3-step process: ### Tag Your Errors {#tag-errors} -Include a release ID (a.k.a version) where you configure your client SDK. This is commonly a git SHA or a custom version number (check language-specific docs for exact syntax): +Include a release ID (a.k.a version) where you configure your client SDK. This is commonly a git SHA or a custom version number. Note that releases are global per organization so make sure to prefix them with something project specific if needed: -```javascript -SentryClient.setRelease({ - release: "6d5a6a446805a06154e25e2fa203d67b9e762f5d" -}); -``` +{% include components/platform_content.html content_dir='set-release' %} How you make the version available to your code is up to you. For example, you could use an environment variable that is set during the build process. @@ -149,7 +146,7 @@ res = requests.post( For more information, see the [API reference]({%- link _documentation/api/releases/post-organization-releases.md -%}). -After this step, **suspect commits** and **suggested assignees** will start appearing on the issue page. We determine these by tying together the commits in the release, files touched by those commits, files observed in the stack trace, authors of those files, and [ownership rules]({%- link _documentation/learn/issue-owners.md -%}). +After this step, **suspect commits** and **suggested assignees** will start appearing on the issue page. We determine these by tying together the commits in the release, files touched by those commits, files observed in the stack trace, authors of those files, and [ownership rules]({%- link _documentation/product/issue-owners.md -%}). {% asset suspect-commits-highlighted.png %} diff --git a/src/collections/_documentation/learn/rollups.md b/src/collections/_documentation/learn/rollups.md index 53fdac8cccb9a..b1c58f65ab837 100644 --- a/src/collections/_documentation/learn/rollups.md +++ b/src/collections/_documentation/learn/rollups.md @@ -58,12 +58,6 @@ To work around these the Sentry protocol supports a `fingerprint` attribute. In supported SDKs, this attribute can be passed with the event information, and should be an array of strings: -```javascript -Raven.captureException(ex, {fingerprint: ['my', 'custom', 'fingerprint']}) -``` +{% include components/platform_content.html content_dir='set-fingerprint' %} -Additionally if you simply wish to append information, thus making the grouping slightly less aggressive, you can do that as well: - -```javascript -{% raw %}Raven.captureException(ex, {fingerprint: ['{{ default }}', 'other', 'data']}){% endraw %} -``` +Additionally if you simply wish to append information, thus making the grouping slightly less aggressive, you can do that as well by adding the special string `{% raw %}{{ default }}{% endraw %}` as one of the items. diff --git a/src/collections/_documentation/learn/scopes.md b/src/collections/_documentation/learn/scopes.md new file mode 100644 index 0000000000000..9af11d7af89a7 --- /dev/null +++ b/src/collections/_documentation/learn/scopes.md @@ -0,0 +1,84 @@ +--- +title: Scopes and Hubs +sidebar_order: 4 +--- + +When an event is captured and sent to Sentry, SDKs will merge that event data with extra +information from the current scope. SDKs will typically automatically mange the scopes +for you in the framework integrations and you don't need to think about them. However +you should know what a scope is and how you can use it for your advantage. + +## What's a Scope, what's a Hub + +You can think of the hub as the central point that our SDKs use to route an +event to Sentry. When you call `init()` a hub is created and a client and a +blank scope are created on it. That hub is then associated with the current +thread and will internally hold a stack of scopes. + +The scope will hold useful information that should be sent along with the +event. For instance [contexts]({% link _documentation/learn/context.md %}) or +[breadcrumbs]({% link _documentation/learn/breadcrumbs.md %}) are stored on +the scope. When a scope is pushed it inherits all data from the parent scope +and when it pops all modifications are reverted. + +The default SDK integrations will push and pop scopes intelligently. For +instance web framework integrations will create and destroy scopes around your +routes or controllers. + +## How do the Scope and Hub Work + +As you start using an SDK a scope and hub are automatically created for you out +of the box. The hub you are unlikely to be interacting with directly unless you +are writing an integration or you want to create or destroy scopes. Scopes on the +other hand are more user facing. You can at any point in time call +`configure-scope` to modify data stored on the scope. This is for instance +used to [modify the context]({% link _documentation/learn/context.md %}). + +{% capture __alert_content -%} +If you are very curious about how this thread locality thing works here are the +nitty gritty details. On platforms such as .NET or on Python 3.7 and later we will +use "ambient data" to have either the hub flow with your code or the hub is already +a singleton that internally manages the scope. + +Effectively this means that when you spawn a task in .NET and the execution flow is +not supressed all the context you have bound to the scope in Sentry will flow along. +If however you suppress the flow, you get new scope data. +{% endcapture %} +{%- include components/alert.html + title="Note" + content=__alert_content +%} + +When you call a global function such as `capture_event` internally Sentry +discovers the current hub and asks it to capture an event. Internally the hub will +then merge the event with the topmost scope's data. + +## Configuring the Scope + +The most useful operation when working with scopes is the `configure-scope` function. +It can be used to reconfigure the current scope. This for instance can be used to +add custom tags or to inform sentry about the currently authenticated user. + +{% include components/platform_content.html content_dir='configure-scope' %} + +To learn what useful information can be associated with scopes see +[the context documentation]({% link _documentation/learn/context.md %}). + +## Local Scopes + +We also have support for pushing and configuring a scope in one go. This is +typically called `with-scope` or `push-scope` which is also very helpful +if you only want to send data with one specific event. In the following example we are using +that function to attach a `level` and a `tag` to only one specific error: + +{% include components/platform_content.html content_dir='with-scope' %} + +While this example looks similar to `configure-scope` it very different, in the sense that +`configure-scope` actually changes the current active scope, all successive calls to `configure-scope` +will keep the changes. + +While on the other hand using `with-scope` creates a clone of the current scope +and will stay isolated until the function call is completed. +So you can either set context information in there that you don't want to be somewhere +else or create do not attach any context information at all +by calling `clear` on the scope, while the "global" scope remains unchanged. diff --git a/src/collections/_documentation/learn/security-policy-reporting.md b/src/collections/_documentation/learn/security-policy-reporting.md index b4b3eb4ae5841..49f8c305f50ac 100644 --- a/src/collections/_documentation/learn/security-policy-reporting.md +++ b/src/collections/_documentation/learn/security-policy-reporting.md @@ -14,13 +14,13 @@ The integration process consists of configuring the the appropriate header with To configure CSP reports in Sentry, you’ll need to send a header from your server describing your policy, as well specifying the authenticated Sentry endpoint: ``` -Content-Security-Policy: ...; report-uri https://sentry.io/api//security/?sentry_key= +Content-Security-Policy: ...; report-uri https://sentry.io/api/___PROJECT_ID___/security/?sentry_key=___PUBLIC_KEY___ ``` Alternatively you can setup CSP reports to simply send reports rather than actually enforcing the policy: ``` -Content-Security-Policy-Report-Only: ...; report-uri https://sentry.io/api//security/?sentry_key= +Content-Security-Policy-Report-Only: ...; report-uri https://sentry.io/api/___PROJECT_ID___/security/?sentry_key=___PUBLIC_KEY___ ``` For more information, see the article on [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy). @@ -32,7 +32,7 @@ For more information, see the article on [MDN](https://developer.mozilla.org/en- To configure reports in Sentry, you’ll need to configure the Expect-CT a header from your server: ``` -Expect-CT: ..., report-uri="https://sentry.io/api//security/?sentry_key=" +Expect-CT: ..., report-uri="https://sentry.io/api/___PROJECT_ID___/security/?sentry_key=___PUBLIC_KEY___" ``` For more information, see the article on [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Expect-CT). @@ -44,7 +44,7 @@ For more information, see the article on [MDN](https://developer.mozilla.org/en- To configure HPKP reports in Sentry, you’ll need to send a header from your server describing your policy, as well specifying the authenticated Sentry endpoint: ``` -Public-Key-Pins: ...; report-uri="https://sentry.io/api//security/?sentry_key=" +Public-Key-Pins: ...; report-uri="https://sentry.io/api/___PROJECT_ID___/security/?sentry_key=___PUBLIC_KEY___" ``` For more information, see the article on [MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Public_Key_Pinning). diff --git a/src/collections/_documentation/learn/sensitive-data.md b/src/collections/_documentation/learn/sensitive-data.md index 50cba21f88f48..01e9118f0cb07 100644 --- a/src/collections/_documentation/learn/sensitive-data.md +++ b/src/collections/_documentation/learn/sensitive-data.md @@ -41,3 +41,13 @@ If you’ve accidentally sent sensitive data to the server it’s likely you’r - If you send it as a tagged value, removing the event is not enough. You can visit Project Settings and under Tags you’ll find a way to permanently remove any related data for a given tag. - If you need to wipe just a single event, you’ll find the ability to bulk delete all sampled events under a rollup by visiting the rollup details page and selecting “Delete”. - If you send sparse events to a project (potentially all of them), your only option is to remove the project and re-create it. Keep in mind this will revoke API credentials, so you likely want to do this in the reverse order. + +## Custom Event Processing in the SDK + +In the SDKs you can also set a function `before-send` which is invoked before events are sent which can be used to modify the events and remove bad data: + +{% include components/platform_content.html content_dir='before-send' %} + +## Custom Event Processing using Relay + +In addition you have the option to put a proxy between your applications and Sentry that can strip sensitive data from your events. Head over to [_Relay_]({%- link _documentation/relay/index.md -%}). diff --git a/src/collections/_documentation/learn/set-environment/browser.md b/src/collections/_documentation/learn/set-environment/browser.md new file mode 100644 index 0000000000000..5716d172d8324 --- /dev/null +++ b/src/collections/_documentation/learn/set-environment/browser.md @@ -0,0 +1,9 @@ +Options are passed to the `init()` as object: + +```javascript +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + environment: '{{ page.example_environment }}', +}) +``` diff --git a/src/collections/_documentation/learn/set-environment/cordova.md b/src/collections/_documentation/learn/set-environment/cordova.md new file mode 100644 index 0000000000000..d01c94807fdba --- /dev/null +++ b/src/collections/_documentation/learn/set-environment/cordova.md @@ -0,0 +1,8 @@ +```javascript +onDeviceReady: function() { + var Sentry = cordova.require("sentry-cordova.Sentry"); + Sentry.init({ + environment: '{{ page.example_environment }}', + }); +} +``` diff --git a/src/collections/_documentation/learn/set-environment/csharp.md b/src/collections/_documentation/learn/set-environment/csharp.md new file mode 100644 index 0000000000000..ed280f25eb80a --- /dev/null +++ b/src/collections/_documentation/learn/set-environment/csharp.md @@ -0,0 +1,5 @@ +```csharp +using Sentry; + +SentrySdk.Init(o => o.Environment = "{{ page.example_environment }}"); +``` diff --git a/src/collections/_documentation/learn/set-environment/electron.md b/src/collections/_documentation/learn/set-environment/electron.md new file mode 100644 index 0000000000000..36e798899cd70 --- /dev/null +++ b/src/collections/_documentation/learn/set-environment/electron.md @@ -0,0 +1,7 @@ +```javascript +import * as Sentry from '@sentry/electron'; + +Sentry.init({ + environment: '{{ page.example_environment }}', +}) +``` diff --git a/src/collections/_documentation/learn/set-environment/node.md b/src/collections/_documentation/learn/set-environment/node.md new file mode 100644 index 0000000000000..a22d40e799a76 --- /dev/null +++ b/src/collections/_documentation/learn/set-environment/node.md @@ -0,0 +1,7 @@ +```javascript +const Sentry = require('@sentry/node'); + +Sentry.init({ + environment: '{{ page.example_environment }}', +}) +``` diff --git a/src/collections/_documentation/learn/set-environment/python.md b/src/collections/_documentation/learn/set-environment/python.md new file mode 100644 index 0000000000000..605f73aa8cf10 --- /dev/null +++ b/src/collections/_documentation/learn/set-environment/python.md @@ -0,0 +1,5 @@ +```python +import sentry_sdk + +sentry_sdk.init(environment="{{ page.example_environment }}") +``` diff --git a/src/collections/_documentation/learn/set-environment/rust.md b/src/collections/_documentation/learn/set-environment/rust.md new file mode 100644 index 0000000000000..3aae4f67fd0b3 --- /dev/null +++ b/src/collections/_documentation/learn/set-environment/rust.md @@ -0,0 +1,6 @@ +```rust +sentry::init(sentry::ClientOptions { + environment: Some("{{ page.example_environment }}".into()), + ..Default::default() +}); +``` diff --git a/src/collections/_documentation/learn/set-extra/csharp.md b/src/collections/_documentation/learn/set-extra/csharp.md new file mode 100644 index 0000000000000..99b60d0af9a63 --- /dev/null +++ b/src/collections/_documentation/learn/set-extra/csharp.md @@ -0,0 +1,8 @@ +```csharp +using Sentry; + +SentrySdk.ConfigureScope(scope => +{ + scope.SetExtra("{{ page.example_extra_key }}", "{{ page.example_extra_value }}"); +}); +``` diff --git a/src/collections/_documentation/learn/set-extra/javascript.md b/src/collections/_documentation/learn/set-extra/javascript.md new file mode 100644 index 0000000000000..52340a4526fc3 --- /dev/null +++ b/src/collections/_documentation/learn/set-extra/javascript.md @@ -0,0 +1,5 @@ +```javascript +Sentry.configureScope((scope) => { + scope.setExtra("{{ page.example_extra_key }}": "{{ page.example_extra_value }}"); +}); +``` diff --git a/src/collections/_documentation/learn/set-extra/python.md b/src/collections/_documentation/learn/set-extra/python.md new file mode 100644 index 0000000000000..09fd84a10843b --- /dev/null +++ b/src/collections/_documentation/learn/set-extra/python.md @@ -0,0 +1,6 @@ +```python +from sentry_sdk import configure_scope + +with configure_scope() as scope: + scope.set_extra("{{ page.example_extra_key }}", "{{ page.example_extra_value }}") +``` diff --git a/src/collections/_documentation/learn/set-extra/rust.md b/src/collections/_documentation/learn/set-extra/rust.md new file mode 100644 index 0000000000000..2c5531e76e9d7 --- /dev/null +++ b/src/collections/_documentation/learn/set-extra/rust.md @@ -0,0 +1,5 @@ +```rust +sentry::configure_scope(|scope| { + scope.set_extra("{{ page.example_extra_key }}", "{{ page.example_extra_value }}".to_owned().into()); +}); +``` diff --git a/src/collections/_documentation/learn/set-fingerprint/csharp.md b/src/collections/_documentation/learn/set-fingerprint/csharp.md new file mode 100644 index 0000000000000..4a238780fd321 --- /dev/null +++ b/src/collections/_documentation/learn/set-fingerprint/csharp.md @@ -0,0 +1,8 @@ +```csharp +using Sentry; + +SentrySdk.ConfigureScope(scope => +{ + scope.SetFingerprint(new[] { "my-view-function" }); +}); +``` diff --git a/src/collections/_documentation/learn/set-fingerprint/javascript.md b/src/collections/_documentation/learn/set-fingerprint/javascript.md new file mode 100644 index 0000000000000..fd538a4cbdded --- /dev/null +++ b/src/collections/_documentation/learn/set-fingerprint/javascript.md @@ -0,0 +1,5 @@ +```javascript +Sentry.configureScope((scope) => { + scope.setFingerprint(['my-view-function']); +}); +``` \ No newline at end of file diff --git a/src/collections/_documentation/learn/set-fingerprint/python.md b/src/collections/_documentation/learn/set-fingerprint/python.md new file mode 100644 index 0000000000000..08bd2541d1faa --- /dev/null +++ b/src/collections/_documentation/learn/set-fingerprint/python.md @@ -0,0 +1,6 @@ +```python +from sentry_sdk import configure_scope + +with configure_scope() as scope: + scope.fingerprint = ['my-view-function'] +``` diff --git a/src/collections/_documentation/learn/set-fingerprint/rust.md b/src/collections/_documentation/learn/set-fingerprint/rust.md new file mode 100644 index 0000000000000..0e90846dd82aa --- /dev/null +++ b/src/collections/_documentation/learn/set-fingerprint/rust.md @@ -0,0 +1,5 @@ +```rust +sentry::configure_scope(|scope| { + scope.set_fingerprint(Some(&["my-view-function"])); +}); +``` diff --git a/src/collections/_documentation/learn/set-release/csharp.md b/src/collections/_documentation/learn/set-release/csharp.md new file mode 100644 index 0000000000000..bf3751d3573f6 --- /dev/null +++ b/src/collections/_documentation/learn/set-release/csharp.md @@ -0,0 +1,5 @@ +```csharp +using Sentry; + +SentrySdk.Init(o => o.Release = "{{ page.release_identifier }}"); +``` diff --git a/src/collections/_documentation/learn/set-release/javascript.md b/src/collections/_documentation/learn/set-release/javascript.md new file mode 100644 index 0000000000000..d48cec527ff5c --- /dev/null +++ b/src/collections/_documentation/learn/set-release/javascript.md @@ -0,0 +1,5 @@ +```javascript +Sentry.init({ + release: "{{ page.release_identifier }}" +}) +``` diff --git a/src/collections/_documentation/learn/set-release/python.md b/src/collections/_documentation/learn/set-release/python.md new file mode 100644 index 0000000000000..902836838184f --- /dev/null +++ b/src/collections/_documentation/learn/set-release/python.md @@ -0,0 +1,5 @@ +```python +import sentry_sdk + +sentry_sdk.init(release="{{ page.release_identifier }}") +``` diff --git a/src/collections/_documentation/learn/set-release/rust.md b/src/collections/_documentation/learn/set-release/rust.md new file mode 100644 index 0000000000000..39a303ee24fe4 --- /dev/null +++ b/src/collections/_documentation/learn/set-release/rust.md @@ -0,0 +1,7 @@ +```rust +use sentry; + +sentry::init(sentry::ClientOptions { + release: "{{ page.release_identifier }}" +}); +``` diff --git a/src/collections/_documentation/learn/set-tag/csharp.md b/src/collections/_documentation/learn/set-tag/csharp.md new file mode 100644 index 0000000000000..658b3e0baa6e2 --- /dev/null +++ b/src/collections/_documentation/learn/set-tag/csharp.md @@ -0,0 +1,8 @@ +```csharp +using Sentry; + +SentrySdk.ConfigureScope(scope => +{ + scope.SetTag("{{ page.example_tag_name }}", "{{ page.example_tag_value }}"); +}); +``` diff --git a/src/collections/_documentation/learn/set-tag/javascript.md b/src/collections/_documentation/learn/set-tag/javascript.md new file mode 100644 index 0000000000000..b2f26d82a94e3 --- /dev/null +++ b/src/collections/_documentation/learn/set-tag/javascript.md @@ -0,0 +1,5 @@ +```javascript +Sentry.configureScope((scope) => { + scope.setTag("{{ page.example_tag_name }}", "{{ page.example_tag_value }}"); +}); +``` \ No newline at end of file diff --git a/src/collections/_documentation/learn/set-tag/python.md b/src/collections/_documentation/learn/set-tag/python.md new file mode 100644 index 0000000000000..85cbfa833f778 --- /dev/null +++ b/src/collections/_documentation/learn/set-tag/python.md @@ -0,0 +1,6 @@ +```python +from sentry_sdk import configure_scope + +with configure_scope() as scope: + scope.set_tag("{{ page.example_tag_name }}", "{{ page.example_tag_value }}") +``` diff --git a/src/collections/_documentation/learn/set-tag/rust.md b/src/collections/_documentation/learn/set-tag/rust.md new file mode 100644 index 0000000000000..a082389b62d86 --- /dev/null +++ b/src/collections/_documentation/learn/set-tag/rust.md @@ -0,0 +1,5 @@ +```rust +sentry::configure_scope(|scope| { + scope.set_tag("{{ page.example_tag_name }}", "{{ page.example_tag_value }}"); +}); +``` diff --git a/src/collections/_documentation/learn/set-user/csharp.md b/src/collections/_documentation/learn/set-user/csharp.md new file mode 100644 index 0000000000000..c4ad60bcc4546 --- /dev/null +++ b/src/collections/_documentation/learn/set-user/csharp.md @@ -0,0 +1,11 @@ +```csharp +using Sentry; + +SentrySdk.ConfigureScope(scope => +{ + scope.User = new User + { + Email = "john.doe@example.com" + }; +}); +``` diff --git a/src/collections/_documentation/learn/set-user/javascript.md b/src/collections/_documentation/learn/set-user/javascript.md new file mode 100644 index 0000000000000..505118b70b00d --- /dev/null +++ b/src/collections/_documentation/learn/set-user/javascript.md @@ -0,0 +1,5 @@ +```javascript +Sentry.configureScope((scope) => { + scope.setUser({"email": "{{ page.example_user_email }}"}); +}); +``` diff --git a/src/collections/_documentation/learn/set-user/python.md b/src/collections/_documentation/learn/set-user/python.md new file mode 100644 index 0000000000000..99d996f8644fc --- /dev/null +++ b/src/collections/_documentation/learn/set-user/python.md @@ -0,0 +1,6 @@ +```python +from sentry_sdk import configure_scope + +with configure_scope() as scope: + scope.set_user({"email": "{{ page.example_user_email }}"}) +``` diff --git a/src/collections/_documentation/learn/set-user/rust.md b/src/collections/_documentation/learn/set-user/rust.md new file mode 100644 index 0000000000000..25aa660163e3c --- /dev/null +++ b/src/collections/_documentation/learn/set-user/rust.md @@ -0,0 +1,8 @@ +```rust +sentry::configure_scope(|scope| { + scope.set_user(Some(sentry::User { + email: "{{ page.example_user_email }}".to_owned() + ..Default::default() + })); +}); +``` diff --git a/src/collections/_documentation/learn/user-feedback-example/aspnetcore.md b/src/collections/_documentation/learn/user-feedback-example/aspnetcore.md new file mode 100644 index 0000000000000..1f2dde5cc2d0e --- /dev/null +++ b/src/collections/_documentation/learn/user-feedback-example/aspnetcore.md @@ -0,0 +1,18 @@ +With ASP.NET Core MVC, the `Error.cshtml` razor page: + +{% raw %} +```html +@using Sentry + + + +@if (SentrySdk.LastEventId != Guid.Empty) +{ + +} +``` +{% endraw %} diff --git a/src/collections/_documentation/learn/user-feedback-example/browser.md b/src/collections/_documentation/learn/user-feedback-example/browser.md new file mode 100644 index 0000000000000..734cd2a8cf744 --- /dev/null +++ b/src/collections/_documentation/learn/user-feedback-example/browser.md @@ -0,0 +1,12 @@ +```html + + + +``` \ No newline at end of file diff --git a/src/collections/_documentation/learn/user-feedback-example/django.md b/src/collections/_documentation/learn/user-feedback-example/django.md new file mode 100644 index 0000000000000..2b7d269f74f85 --- /dev/null +++ b/src/collections/_documentation/learn/user-feedback-example/django.md @@ -0,0 +1,27 @@ +Custom 500 handler: + +```python +from sentry_sdk import last_event_id +from django.shortcuts import render + +def handler500(request, *args, **argv): + return render(request, "500.html", { + 'sentry_event_id': last_event_id(), + }, status=500) +``` + +And the template that brings up the dialog + +{% raw %} +```html + + +{% if sentry_event_id %} + +{% endif %} +``` +{% endraw %} diff --git a/src/collections/_documentation/learn/user-feedback-example/flask.md b/src/collections/_documentation/learn/user-feedback-example/flask.md new file mode 100644 index 0000000000000..94cd3abc39e07 --- /dev/null +++ b/src/collections/_documentation/learn/user-feedback-example/flask.md @@ -0,0 +1,28 @@ +Custom 500 handler: + +```python +from flask import render_template +from sentry_sdk import last_event_id + +@app.errorhandler(500) +def server_error_handler(error): + return render_template("500.html", sentry_event_id=last_event_id()), 500 +``` + +And the template that brings up the dialog: + +{% raw %} +```html + + +{% if sentry_event_id %} + +{% endif %} +``` +{% endraw %} diff --git a/src/collections/_documentation/learn/user-feedback.md b/src/collections/_documentation/learn/user-feedback.md index 609120221018b..cab7d55021108 100644 --- a/src/collections/_documentation/learn/user-feedback.md +++ b/src/collections/_documentation/learn/user-feedback.md @@ -15,64 +15,9 @@ When feedback is collected, Sentry will pair it up with the original event givin ## Collecting Feedback -The integration process consists of running our JavaScript SDK (2.1 or newer), authenticating with your public DSN, and passing in the client-side generated Event ID. +The integration process consists of running our JavaScript SDK (2.1 or newer), authenticating with your public DSN, and passing in the client-side generated Event ID: -For example, in Django this looks like the following: - -```html -{% raw %} - - -{% if request.sentry.id %} - -{% endif %}{% endraw %} -``` - -Often this will vary depending on how you handle errors – specifically routing and rendering errors. If you’ve got a more custom setup, you’ll simply need to pull out the event ID and pass it into the widget: - -```python -class IndexController(Controller): - def get(self, request): - try: - 1 / 0 - except Exception: - event_id = Raven.captureException() - return render('500.html', {'sentry_event_id': event_id}) -``` - -Then simply check for the ID in the template, and open the feedback dialog: - -```html -{% raw %} - -{% if sentry_event_id %} - -{% endif %}{% endraw %} -``` - -Some integrations and frameworks will make this even easier: - -- [Browser JavaScript]({%- link _documentation/clients/javascript/usage.md -%}#javascript-user-feedback) -- [Django]({%- link _documentation/clients/python/integrations/django.md -%}#python-django-user-feedback) -- [Flask]({%- link _documentation/clients/python/integrations/flask.md -%}#python-flask-user-feedback) -- [PHP]({%- link _documentation/clients/php/usage.md -%}#php-user-feedback) -- [Cocoa]({%- link _documentation/clients/cocoa/advanced.md -%}#cocoa-user-feedback) - -Take a look at your SDK’s documentation for more information. +{% include components/platform_content.html content_dir='user-feedback-example' %} ## Customizing the Widget @@ -82,6 +27,8 @@ An override for Sentry’s automatic language detection (e.g. `lang=de`) | Param | Default | | --- | --- | +| `eventId` | Manually set the id of the event. | +| `dsn` | Manually set dsn to report to. | | `lang` | _[automatic]_ – **override for Sentry’s language code** | | `title` | It looks like we’re having issues. | | `subtitle` | Our team has been notified. | diff --git a/src/collections/_documentation/learn/with-scope/javascript.md b/src/collections/_documentation/learn/with-scope/javascript.md new file mode 100644 index 0000000000000..7cb66d835ec15 --- /dev/null +++ b/src/collections/_documentation/learn/with-scope/javascript.md @@ -0,0 +1,7 @@ +```javascript +Sentry.withScope(scope => { + scope.setTag("my-tag", "my value"); + scope.setLevel('warning'); + Sentry.captureException(new Error('my error')); +}); +``` diff --git a/src/collections/_documentation/learn/with-scope/python.md b/src/collections/_documentation/learn/with-scope/python.md new file mode 100644 index 0000000000000..dd11f21c814e4 --- /dev/null +++ b/src/collections/_documentation/learn/with-scope/python.md @@ -0,0 +1,8 @@ +```python +from sentry_sdk import push_scope, capture_exception + +with push_scope() as scope: + scope.set_tag("my-tag", "my value") + scope.level = 'warning' + capture_exception(Exception("my error")) +``` diff --git a/src/collections/_documentation/learn/with-scope/rust.md b/src/collections/_documentation/learn/with-scope/rust.md new file mode 100644 index 0000000000000..89d395cde9e6d --- /dev/null +++ b/src/collections/_documentation/learn/with-scope/rust.md @@ -0,0 +1,15 @@ +```rust +use sentry::{Level, with_scope}; +use sentry::integrations::failure::capture_error; +use failure::err_msg; + +with_scope(|scope| { + scope.set_tag("my-tag", "my value"); + scope.set_level(Some(Level::Warning)); +}, || { + capture_error(err_msg("my error")) +}); +``` + +*Note that in Rust two callbacks are invoked. One for configuring the scope, and a second +which is executed in the context of the scope.* diff --git a/src/collections/_documentation/platforms/dotnet/aspnetcore.md b/src/collections/_documentation/platforms/dotnet/aspnetcore.md new file mode 100644 index 0000000000000..c9da1af37a99a --- /dev/null +++ b/src/collections/_documentation/platforms/dotnet/aspnetcore.md @@ -0,0 +1,190 @@ +--- +title: Sentry.AspNetCore +sidebar_order: 2 +--- + +Sentry has an integration with _ASP.NET Core_ through the [Sentry.AspNetCore NuGet package](https://www.nuget.org/packages/Sentry.AspNetCore). + +## Installation + +Using package manager: + +```powershell +Install-Package Sentry.AspNetCore -Version {% sdk_version sentry.dotnet.aspnetcore %} +``` + +Or using the .NET Core CLI: + +```sh +dotnet add Sentry.AspNetCore -v {% sdk_version sentry.dotnet.aspnetcore %} +``` + +This package extends [Sentry.Extensions.Logging]({%- link _documentation/platforms/dotnet/microsoft-extensions-logging.md -%}). This means that besides the ASP.NET Core related features, through this package you'll also get access to all the framework's logging integration and also the features available in the main [Sentry]({%- link _documentation/platforms/dotnet/index.md -%}) SDK. + +## Overview of the features + +* Easy ASP.NET Core integration, single line: `UseSentry` +* Captures unhandled exceptions in the middleware pipeline +* Captures exceptions handled by the framework `UseExceptionHandler` and Error page display +* Captures process-wide unhandled exceptions (AppDomain) +* Captures `LogError` or `LogCritical` +* Any event sent will include relevant application log messages +* RequestId as tag +* URL as tag +* Environment is automatically set (IHostingEnvironment) +* Release automatically set (`AssemblyInformationalVersionAttribute`, `AssemblyVersion` or environment variable) +* Request payload can be captured if opt-in +* Support for EventProcessors registered with DI +* Support for ExceptionProcessors registered with DI +* Supports configuration system (bind to `SentryAspNetCoreOptions`) +* Server OS info sent +* Server Runtime info sent +* Request headers sent +* HTTP Proxy configuration +* Request body compressed +* Event flooding protection (429 retry-after and internal bound queue) +* Assembly Strong named +* Tested on Windows, Linux and macOS +* Tested on .NET Core, .NET Framework and Mono + +### Configuration + +The simplest way to configure the `Sentry.AspNetCore` package is not by calling `SentrySdk.Init` directly but rather using the extension method `UseSentry` to the `WebHostBuilder` in combination with the framework's configuration system. +The configuration values bind to `SentryAspNetCoreOptions` which extends `SentryLoggingOptions` from the `Sentry.Extensions.Logging` and further extends `SentryOptions` from the `Sentry` package. + +This means all options for the inner packages are available to be configured through the configuration system. + +When using `WebHost.CreateDefaultBuilder`, the framework automatically loads `appsettings.json` and environment variables, binding to `SentryAspNetCoreOptions`. + +For example: + +```json + "Sentry": { + "Dsn": "___PUBLIC_DSN___", + "IncludeRequestPayload": true, + "SendDefaultPii": true, + "MinimumBreadcrumbLevel": "Debug", + "MinimumEventLevel": "Warning", + "AttachStackTrace": true, + "Debug": true, + "DiagnosticsLevel": "Error" + }, +``` + +> An example of some of the options that can be configured via `appsettings.json`. + +It's also possible to bind properties to the SDK via environment variables, like: + +Windows +```sh +set Sentry__Debug=true +``` + +Linux or macOS +```sh +export Sentry__Debug=true +``` + +ASP.NET Core will automatically read this environment variable and bind it to the SDK configuration object. + +When configuring the SDK via the frameworks configuration system, it's possible to add the SDK by simply calling `UseSentry` without providing any further information: + +```csharp +public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + // Add this: + .UseSentry() + .Build(); +``` + +Some of the settings require actual code. For those, like the `BeforeSend` callback you can simply: + +```csharp +public static IWebHost BuildWebHost(string[] args) => + WebHost.CreateDefaultBuilder(args) + .UseStartup() + .UseSentry(options => + { + options.BeforeSend = @event => + { + // Never report server names + @event.ServerName = null; + return @event; + }; + }) + .Build(); +``` + +> Example modifying all events before they are sent to avoid server names being reported. + +## Dependency Injection + +Much of the behavior of the ASP.NET Core integration with Sentry can be customized by using the frameworks dependency injection system. That is done by registering your own implementation of some of the exposed abstraction. + +### Lifetimes + +The lifetime used will be respected by the SDK. For example, when registering a `Transient` dependency, a new instance of the processor is created for each event sent out to Sentry. This allows the use of non thread-safe event processors. + +### Capturing the affected user + +When opting-in to [SendDefaultPii](#senddefaultpii), the SDK will automatically read the user from the request by inspecting `HttpContext.User`. Default claim values like `NameIdentifier` for the _Id_ will be used. + +If you wish to change the behavior of how to read the user from the request, you can register a new `IUserFactory` into the container: + +```csharp +public void ConfigureServices(IServiceCollection services) +{ + services.AddSingleton(); +} +``` + +### Adding event and exception processors + +Event processors and exception processors can be added via DI: + +```csharp +public void ConfigureServices(IServiceCollection services) +{ + services.AddTransient(); + services.AddScoped(); +} +``` + +## Options and Initialization + +As previously mentioned, this package is a wrapper around [Sentry.Extensions.Logging]({%- link _documentation/platforms/dotnet/microsoft-extensions-logging.md -%}) and [Sentry]({%- link _documentation/platforms/dotnet/index.md -%}). Please refer to the documentation of these packages to get the options that are defined at those levels. + +Below, the options that are specific to `Sentry.AspNetCore` will be described. + +### SendDefaultPii + +Although this setting is part of the [Sentry]({%- link _documentation/platforms/dotnet/index.md -%}) package, in the context of ASP.NET Core, it means reporting the user by reading the frameworks `HttpContext.User`. The strategy to create the `SentryUser` can be customized. Please read [retrieving user info](#capturing-the-affected-user) for more. + +### Environment + +The environment name is automatically populated by reading the frameworks `IHostingEnvironment` value. + +> Note: This option is part of the [Sentry]({%- link _documentation/platforms/dotnet/index.md -%}) package. The value of `IHostingEnvironment` will only be used if **no other method was used**. + +Methods that take precedence over `IHostingEnvironment` are: + +* Programatically: `options.Environment` +* Environment variable _SENTRY_ENVIRONMENT_ +* Configuration system like `appsettings.json` + + + +### IncludeRequestPayload + +Opt-in to send the request body to Sentry. By enabling this flag, all requests will have the `EnableRewind` method invoked. This is done so that the request data can be read at a later point in case an error happens while processing the request. + +### IncludeActivityData + +Opt-in to capture values from [System.Diagnostic.Activity](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md) if one exists. + +### Samples + +* A [simple example](https://github.com/getsentry/sentry-dotnet/tree/master/samples/Sentry.Samples.AspNetCore.Basic) without MVC. +* An [example](https://github.com/getsentry/sentry-dotnet/tree/master/samples/Sentry.Samples.AspNetCore.Mvc) using MVC and most of the SDK features. +* For [more samples](https://github.com/getsentry/sentry-dotnet-samples) of the .NET SDKs \ No newline at end of file diff --git a/src/collections/_documentation/platforms/dotnet/entityframework.md b/src/collections/_documentation/platforms/dotnet/entityframework.md new file mode 100644 index 0000000000000..3989c67534581 --- /dev/null +++ b/src/collections/_documentation/platforms/dotnet/entityframework.md @@ -0,0 +1,83 @@ +--- +title: EntityFramework +sidebar_order: 8 +--- + +Sentry has an integration with `EntityFramework` through the of the [Sentry.EntityFramework NuGet package](https://www.nuget.org/packages/Sentry.EntityFramework). + +> Looking for `EntityFramework Core`? That integration is achieved through the [Sentry.Extensions.Logging]({%- link _documentation/platforms/dotnet/microsoft-extensions-logging.md -%}) package. + + +## Installation + +Using package manager: + +```powershell +Install-Package Sentry.EntityFramework -Version {% sdk_version sentry.dotnet.ef %} +``` + +Or using the .NET Core CLI: + +```sh +dotnet add Sentry.EntityFramework -v {% sdk_version sentry.dotnet.ef %} +``` + +This package extends `Sentry` main SDK. That means that besides the EF features, through this package you'll also get access to all API and features available in the main `Sentry` SDK. + +## Features + +* Queries as breadcrumbs +* Validation errors + +All queries executed are added as breadcrumbs and are sent with any event which happens on the same `Scope`. Besides that, validation errors are also included as `Extra`. + + +## Configuration + +There are 2 steps to adding Entity Framework 6 support to your project: + +* Call `SentryDatabaseLogging.UseBreadcrumbs()` to either your application's startup method, or into a static constructor inside your Entity Framework object. Make sure you only call this method once! This will add the interceptor to Entity Framework to log database queries. +* When initializing the SDK, call the extension method `AddEntityFramework()` on `SentryOptions`. This will register all error processors to extract extra data, such as validation errors, from the exceptions thrown by Entity Framework. + +### Example configuration + +For example, configuring an ASP.NET app with _global.asax_: + +```csharp +public class MvcApplication : System.Web.HttpApplication +{ + private IDisposable _sentrySdk; + + protected void Application_Start() + { + // We add the query logging here so multiple DbContexts in the same project are supported + SentryDatabaseLogging.UseBreadcrumbs(); + _sentrySdk = SentrySdk.Init(o => + { + // We store the DSN inside Web.config + o.Dsn = new Dsn(ConfigurationManager.AppSettings["SentryDsn"]); + // Add the EntityFramework integration + o.AddEntityFramework(); + }); + } + + // Global error catcher + protected void Application_Error() + { + var exception = Server.GetLastError(); + SentrySdk.CaptureException(exception); + } + + public override void Dispose() + { + _sentrySdk.Dispose(); + base.Dispose(); + } +} +``` + +### Sample + +Check out a complete working [sample](https://github.com/getsentry/sentry-dotnet-ef/tree/master/samples/Sentry.Samples.AspNet.Mvc) to see it in action. + +![Sample breadcrumbs in Sentry](https://github.com/getsentry/sentry-dotnet-ef/blob/master/.assets/ef.PNG?raw=true) diff --git a/src/collections/_documentation/platforms/dotnet/index.md b/src/collections/_documentation/platforms/dotnet/index.md new file mode 100644 index 0000000000000..757597f7bcf25 --- /dev/null +++ b/src/collections/_documentation/platforms/dotnet/index.md @@ -0,0 +1,59 @@ +--- +title: .NET +sidebar_order: 10 +--- + +{% include learn-sdk.md platform="csharp" %} + +This section will describe features, configurations and general functionality which are specific to the .NET SDK. + +# Compatibility + +The main [Sentry NuGet package](https://www.nuget.org/packages/Sentry) targets .NET Standard 2.0. That means, according to the [compatibility table](https://docs.microsoft.com/en-us/dotnet/standard/net-standard), it is compatible with the following versions or newer: + +* .NET Framework 4.6.1 (4.7.2 advised) +* .NET Core 2.0 +* Mono 5.4 +* Xamarin.Android 8.0 +* Xamarin.Mac 3.8 +* Xamarin.iOS 10.14 +* Universal Windows Platform 10.0.16299 + +Of those, we run our unit/integration tests against: + +* .NET Framework 4.7.2 on Windows +* Mono 5.12 macOS and Linux +* .NET Core 2.0 Windows, macOS and Linux +* .NET Core 2.1 Windows, macOS and Linux + +## Automatically discovering release version + +The SDK attempts to locate the release to add that to the events sent to Sentry. + +> [Default values like 1.0 or 1.0.0.0 are ignored](https://github.com/getsentry/sentry-dotnet/blob/dbb5a3af054d0ca6f801de37fb7db3632ca2c65a/src/Sentry/Internal/ApplicationVersionLocator.cs#L14-L21). + +The SDK will firstly look at the [entry assembly's](https://msdn.microsoft.com/en-us/library/system.reflection.assembly.getentryassembly(v=vs.110).aspx) `AssemblyInformationalVersionAttribute`, which accepts a string as +value and is often used to set a GIT commit hash. + +If that returns null, it'll look at the default `AssemblyVersionAttribute` which accepts the numeric version number. When creating a project with Visual Studio, that values is set to *1.0.0.0*. +Since that usually means that the version is either not being set, or is set via a different method. The **automatic version detection will disregard** this value and no *Release* will be reported automatically. + +## Unit testing + +We often don't want to couple our code with static class like `SentrySdk`. Especially to allow our code to be testable. +If that's your case, you can use 2 abstractions: + +* `ISentryClient` +* `IHub` + +The `ISentryClient` exposes the `CaptureEvent` method and it's implementation `SentryClient` is responsible to queueing the event to be sent to Sentry. It also abstracts away the internal transport. + +The `IHub` on the other hand, holds a client and the current scope. In fact, it extends `ISentryClient` and is able to dispatch calls to the right client depending on the current scope. + +In order to allow different events to hold different contextual data, you need to know in which scope you are in. +That's the job of the [`Hub`](https://github.com/getsentry/sentry-dotnet/blob/master/src/Sentry/Internal/Hub.cs). It holds the scope management as well as a client. + +If all you are doing is sending events, without modification/access to the current scope, then you depend on `ISentryClient`. If on the other hand you would like to have access to the current scope by configuring it or binding a different client to it, you depend on `IHub`. + +An example using `IHub` for testability is [SentryLogger](https://github.com/getsentry/sentry-dotnet/blob/master/src/Sentry.Extensions.Logging/SentryLogger.cs) and its unit tests [SentryLoggerTests](https://github.com/getsentry/sentry-dotnet/blob/master/test/Sentry.Extensions.Logging.Tests/SentryLoggerTests.cs). +`SentryLogger` depends on `IHub` because it does modify the scope (through `AddBreadcrumb`). In case it only sent events, it should instead depend on `ISentryClient` diff --git a/src/collections/_documentation/platforms/dotnet/log4net.md b/src/collections/_documentation/platforms/dotnet/log4net.md new file mode 100644 index 0000000000000..a4204ef518d07 --- /dev/null +++ b/src/collections/_documentation/platforms/dotnet/log4net.md @@ -0,0 +1,57 @@ +--- +title: log4net +sidebar_order: 10 +--- + +Sentry has an integration with log4net through the [Sentry.Log4Net NuGet package](https://www.nuget.org/packages/Sentry.Log4Net). + +Without any code change, this package is able to initialize the Sentry SDK and capture events while including additional properties like `Exception` data and more. + + +## Installation + +Using package manager: + +```powershell +Install-Package Sentry.Log4Net -Version {% sdk_version sentry.dotnet.log4net %} +``` + +Or using the .NET Core CLI: + +```sh +dotnet add Sentry.Log4Net -v {% sdk_version sentry.dotnet.log4net %} +``` + +This package extends `Sentry` main SDK. That means besides the log4net `Appender`, through this package you'll also get access to all API and features available in the main `Sentry` SDK. + +## Configuration + +Once the log4net integration package is installed in your project, you can modify your configuration file to add the appender. +This can be done, for example, via the `app.config` for console and desktop apps or `web.config` in case of ASP.NET. + +```xml + + + + + + +``` + +#### SendIdentity + +In the example above, the `SendIdentity` flag was switched on. The SDK then will take the log4net `Identity` value and report to Sentry as the user's id. + +#### Dsn + +Also in the example above, you can find the [DSN](https://docs.sentry.io/quickstart/#configure-the-dsn) being set. That will instruct the `SentryAppender` to initialize the SDK. + +> NOTE: +This is only one of the ways to initialize the SDK. If you wish to configure the SDK programatically, you could **leave the DSN out** from the appender configuration section. The SDK needs to be initialized only **once** and since other integrations (like ASP.NET) are also able to initialize the SDK, you only need to pass the DSN to one of these integrations. + + +### Sample + +For a [sample app.config](https://github.com/getsentry/sentry-dotnet/blob/master/samples/Sentry.Samples.Log4Net/app.config) or a complete working [sample](https://github.com/getsentry/sentry-dotnet/tree/master/samples/Sentry.Samples.Log4Net) to see it in action. + +![Sample event in Sentry](https://github.com/getsentry/sentry-dotnet/blob/master/samples/Sentry.Samples.Log4Net/.assets/log4net-sample.gif?raw=true) diff --git a/src/collections/_documentation/platforms/dotnet/microsoft-extensions-logging.md b/src/collections/_documentation/platforms/dotnet/microsoft-extensions-logging.md new file mode 100644 index 0000000000000..798f54c20fd41 --- /dev/null +++ b/src/collections/_documentation/platforms/dotnet/microsoft-extensions-logging.md @@ -0,0 +1,151 @@ +--- +title: Microsoft.Extensions.Logging +sidebar_order: 12 +--- + +Sentry has an integration with `Microsoft.Extensions.Logging` through the [Sentry.Extensions.Logging NuGet package](https://www.nuget.org/packages/Sentry.Extensions.Logging). + +## Installation + +Using package manager: + +```powershell +Install-Package Sentry.Extensions.Logging -Version {% sdk_version sentry.dotnet.extensions.logging %} +``` + +Or using the .NET Core CLI: + +```sh +dotnet add Sentry.Extensions.Logging -v {% sdk_version sentry.dotnet.extensions.logging %} +``` + +This package extends `Sentry` main SDK. That means that besides the logging related features, through this package you'll also get access to all API and features available in the main `Sentry` SDK. + +> NOTE: Messages logged from assemblies with the name starting with `Sentry` will not generate events. + +## Features + +* Store log messages as breadcrumbs +* Send events to sentry + +Two separate settings define the minimum log level to keep the log entry as a `Breadcrumb` and to send an `Event` to Sentry. The events include any stored breadcrumb on that `Scope`. + +By default, any message with log level `Information` or higher will be kept as a `Breadcrumb`. + +The default value to report a log entry as an event to Sentry is `Error`. + +This means that out of the box, any `LogError` call will create an `Event` which will include all log messages of level `Information`, `Warning` and also `Error` and `Critical`. + + +## Configuration + +There are two ways to add this integration into your project. In both cases it means calling an extension method. The places where it's available are: + +* `ILoggingBuilder` +* `ILoggerFactory` + +The `ILoggingBuilder` extension is useful when using a `WebHostBuilder` or a `HostBuilder`, also known as _Generic host_. This extension method is used by the ASP.NET Core integration under the hood to automatically. + +The extension to `ILoggerFactory` is a convenient way when only the `LoggerFactory` is being used, without any framework integration. + +In both cases the method call is: + +**AddSentry()** + +### Example configuration + +#### Through `ILoggingBuilder` + +```csharp +public static Task Main() + => new HostBuilder() + .ConfigureHostConfiguration(c => + { + c.SetBasePath(Directory.GetCurrentDirectory()); + c.AddJsonFile("appsettings.json", optional: false); + }) + .ConfigureLogging((c, l) => + { + l.AddConfiguration(c.Configuration); + // Adding Sentry integration to Microsoft.Extensions.Logging + l.AddSentry(); + }) + .Build(); +``` + +In this example, a _generic host_ is being built and the MEL integration with Sentry added through `ConfigureLogging`. The example also demonstrates how to bind the `appsettings.json` configuration to make the values available to the Sentry integration. + +With this approach, options like `Dsn`, `SendDefaultPii`, `MinimumBreadcrumbLevel`, to name a few, can be set in `appsettings.json`. + +Example using `appsettings.json`: + +```json +{ + "Logging": { + "LogLevel": { + "Default": "Debug" + } + }, + "Sentry": { + "Dsn": "___PUBLIC_KEY___", + "MinimumBreadcrumbLevel": "Warning", + "MinimumEventLevel": "Critical", + "MaxBreadcrumbs": 50 + } +} +``` + +Above we set the application wide minimum log level to `Debug`. Sentry specific settings are set under the `Sentry` property. Options are documented below. + +#### Through `ILoggerFactory` + +```csharp +using (var loggerFactory = new LoggerFactory() + .AddConsole(LogLevel.Trace) + .AddSentry(o => o.Dsn = "___PUBLIC_KEY___")) +{ + var logger = loggerFactory.CreateLogger(); +} +``` + +This approach doesn't include any of the framework's configuration system. Since the DSN is being provided via parameter, the SDK will be initialized. +More settings can be passed via the callback configuring the `SentryOptions`. + +## Options and Initialization + +In cases where `AddSentry` is called without arguments, it's worth noting that an overload exists where `SentryOptions` can be configured just like if `SentrySdk.Init` had been called. + +> NOTE: +The SDK only needs to be initialized only once. If the `DSN` is made available to this integration, by default it **will** initialize the SDK. If you do not wish to initialize the SDK via this configuration, set the `InitializeSdk` flag to **false**. Not providing a DSN or leaving it as an _empty string_ will disable the SDK. + +For example: + +```csharp +using (var loggerFactory = new LoggerFactory() + .AddSentry(o => o.InitializeSdk = false)) +{ } +``` + +### Options + +#### MinimumBreadcrumbLevel + +A `LogLevel` which indicates the minimum level a log message has to be to be included as a breadcrumb. By default this value is `Information`. + +#### MinimumEventLevel + +A `LogLevel` which indicates the minimum level a log message has to be to be sent to Sentry as an event. By default this value is `Error`. + +#### InitializeSdk + +Whether or not this integration should initialize the SDK. If you intend to call `SentrySdk.Init` yourself you should set this flag to `true`. + +#### Filters + +A list of filters which are invoked before processing any log message. This allows you to inspect the details of the log entry before they become a `Breadcrumb` or an `Event` with full access to the `Microsoft.Extensions.Logging` data. + + +### Samples + +* A [simple example](https://github.com/getsentry/sentry-dotnet/tree/master/samples/Sentry.Samples.ME.Logging) using simply the `LoggerFactory`. +* An [example](https://github.com/getsentry/sentry-dotnet/tree/master/samples/Sentry.Samples.GenericHost) using the _generic host_. diff --git a/src/collections/_documentation/platforms/index.md b/src/collections/_documentation/platforms/index.md new file mode 100644 index 0000000000000..76e2e32a3fd48 --- /dev/null +++ b/src/collections/_documentation/platforms/index.md @@ -0,0 +1,10 @@ +--- +title: Platforms +sidebar_order: 2 +--- + +To report to Sentry you’ll need to use a language-specific SDK. The Sentry team builds and maintains these for most popular languages, but there’s also a large ecosystem supported by the community. + +{% include platform_icon_links.html %} + +Some platforms have been phased out or have been replaced with new SDKs. For those legacy integrations head over to the [legacy clients]({% link _documentation/clients/index.md %}) page. Your favorite language still cannot be found? Then we encourage you to start a discussion about supporting it on our [community forum](https://forum.sentry.io). diff --git a/src/collections/_documentation/platforms/javascript/angular.md b/src/collections/_documentation/platforms/javascript/angular.md new file mode 100644 index 0000000000000..a8649f82791b0 --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/angular.md @@ -0,0 +1,41 @@ +--- +title: Angular +sidebar_order: 35 +--- + + +This document uses Angular to refer to Angular 2+. On its own, `@sentry/browser` will report any uncaught exceptions triggered from your application. + +Additionally, `@sentry/browser` can be configured to catch any Angular-specific (2.x) exceptions reported through the [@angular/core/ErrorHandler](https://angular.io/api/core/ErrorHandler) component. + +```typescript +import { BrowserModule } from "@angular/platform-browser"; +import { NgModule, ErrorHandler, Injectable } from "@angular/core"; + +import { AppComponent } from "./app.component"; + +import * as Sentry from "@sentry/browser"; + +Sentry.init({ + dsn: "___PUBLIC_DSN___" +}); + +@Injectable() +class SentryErrorHandler implements ErrorHandler { + constructor() {} + handleError(error) { + Sentry.captureException(error.originalError || error); + throw error; + } +} + +@NgModule({ + declarations: [AppComponent], + imports: [BrowserModule], + providers: [{ provide: ErrorHandler, useClass: SentryErrorHandler }], + bootstrap: [AppComponent] +}) + +export class AppModule {} +``` + \ No newline at end of file diff --git a/src/collections/_documentation/platforms/javascript/browser.md b/src/collections/_documentation/platforms/javascript/browser.md new file mode 100644 index 0000000000000..1603cee8ed273 --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/browser.md @@ -0,0 +1,53 @@ +--- +title: Browser +sidebar_order: 20 +--- + +We recommend using our bundled CDN version for the browser as explained [here]({% link _documentation/learn/quickstart.md %}?platform=browser#pick-a-client-integration). + +### What does the CDN version provide? + +The script you add to your website is a small wrapper around our SDK, we call it _Loader_. +The _Loader_ does a few things: + +- You will always have the newest recommend stable version of our SDK. +- It captures all _global errors_ and _unhandled promise_ rejections. +- It lazy injects our SDK into your website. +- After the SDK is loaded everything will be sent to Sentry. + +By default, the _Loader_ contains all information needed for our SDK to function, like the `DSN`. In case you want to set additional [options]({% link _documentation/learn/configuration.md %}) you have to set them like this: + + +```javascript +Sentry.onLoad(() => { + Sentry.init({ + release: '1.0.0', + environment: 'prod' + }); +}); +``` + +`onLoad` is a function the only the _Loader_ provides, it will be called once the SDK has been injected into the website. With the _Loader_ `init()` works a bit different, instead of just setting the options, we merge the options internally, only for convenience so you don't have to set the `DSN` again since the _Loader_ already contains it. + +As explained before, the _Loader_ lazy loads and injects our SDK into your website but you can also tell the loader to fetch it immediately instead of only fetching it when you need it. Setting `data-lazy` to `no` will tell the _Loader_ to inject the SDK as soon as possible: + +```html + +``` + +The _Loader_ also provides a function called `forceLoad()` which does the same, so you can do the following: + +```html +{% raw %}{% if sentry_event_id %} + +{% endif %}{% endraw %} +``` \ No newline at end of file diff --git a/src/collections/_documentation/platforms/javascript/connect.md b/src/collections/_documentation/platforms/javascript/connect.md new file mode 100644 index 0000000000000..c74e502a24142 --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/connect.md @@ -0,0 +1,43 @@ +--- +title: Connect +sidebar_order: 1012 +--- + + + +Our Connect integration only requires _@sentry/node_ to be installed then you can use it like this: + +```javascript +var connect = require('connect'); +const Sentry = require('@sentry/node') ; + +// Must configure Sentry before doing anything else with it +Sentry.init({ dsn:'___PUBLIC_DSN___' }); + +function mainHandler(req, res) { + throw new Error('Broke!'); +} + +function onError(err, req, res, next) { + // The error id is attached to `res.sentry` to be returned + // and optionally displayed to the user for support. + res.statusCode = 500; + res.end(res.sentry + '\n'); +} + +connect( + // The request handler be the first item + Sentry.Handlers.requestHandler(), + + connect.bodyParser(), + connect.cookieParser(), + mainHandler, + + // The error handler must be before any other error middleware + Sentry.Handlers.errorHandler(), + + // Optional fallthrough error handler + onError, +).listen(3000); +``` + diff --git a/src/collections/_documentation/clients/cordova/index.md b/src/collections/_documentation/platforms/javascript/cordova.md similarity index 53% rename from src/collections/_documentation/clients/cordova/index.md rename to src/collections/_documentation/platforms/javascript/cordova.md index 365a10631081e..62639926b62e2 100644 --- a/src/collections/_documentation/clients/cordova/index.md +++ b/src/collections/_documentation/platforms/javascript/cordova.md @@ -1,70 +1,22 @@ --- title: Cordova -sidebar_order: 2 +sidebar_order: 200 --- This is the documentation for our Cordova SDK. The SDK uses a native extension for iOS and Android but will fall back to a pure JavaScript version (@sentry/browser) if needed. -## Installation - -Start by adding Sentry and then linking it: - -```bash -$ cordova plugin add sentry-cordova -``` - +When you [install]({%- link _documentation/learn/quickstart.md -%}?platform=cordova) `sentry-cordova` [Sentry Wizard](https://github.com/getsentry/sentry-wizard) will help you to configure your project. We also add a build step to your Xcode project to upload debug symbols we need to symbolicate iOS crashes. ## Configuration You have to whitelist `sentry.io` in your `config.xml` like: -> - -Keep in mind if you use an on-premise installation, adjust this domain accordingly. - -This example shows the bare minimum for a plain Cordova project. Add this to you _index.js_: - -```javascript -onDeviceReady: function() { - ... - var Sentry = cordova.require("sentry-cordova.Sentry"); - Sentry.init({ dsn: '___PUBLIC_DSN___' }); - ... -} +```xml + ``` -This will setup the Client for native and JavaScript crashes. If you minify or bundle your code we need your sourcemap files in order to symbolicate JavaScript errors, please see: [JavaScript sourcemaps]({%- link _documentation/clients/javascript/sourcemaps.md -%}) for more details. - -## Usage - -- capturing messages and error: - - ```javascript - Sentry.captureMessage('message'); - try { - myFailingFunction(); - } catch (e) { - Sentry.captureException(e); - } - ``` - -Note that we will track unhandled errors and promises by default. - -- adding breadcrumbs: - - ```javascript - Sentry.addBreadcrumb({ message: 'message' }); - ``` -- context handling: - - ```javascript - Sentry.configureScope(scope => { - scope.setUser({ id: '123', email: 'test@sentry.io', username: 'sentry' }); - scope.setTag('cordova', 'true'); - scope.setExtra('myData', ['1', 2, '3']); - }); - ``` +Keep in mind if you use an on-premise installation, adjust this domain accordingly. ## iOS Specifics @@ -82,28 +34,28 @@ If the wizard ran successfully, it should have done setup all the necessary step If you want to run the debug symbol upload during building your app. You can add this as a run script phase in Xcode. Also make sure to set the `DEBUG_INFORMATION_FORMAT` in your project settings to `DWARF and dSYM file`. -> ```bash -> export SENTRY_PROPERTIES=sentry.properties -> function getProperty { -> PROP_KEY=$1 -> PROP_VALUE=`cat $SENTRY_PROPERTIES | grep "$PROP_KEY" | cut -d'=' -f2` -> echo $PROP_VALUE -> } -> if [ ! -f $SENTRY_PROPERTIES ]; then -> echo "warning: SENTRY: sentry.properties file not found! Skipping symbol upload." -> exit 0 -> fi -> echo "# Reading property from $SENTRY_PROPERTIES" -> SENTRY_CLI=$(getProperty "cli.executable") -> SENTRY_COMMAND="../../$SENTRY_CLI upload-dsym" -> $SENTRY_COMMAND -> ``` - -The next script makes sure that all unnes architectures are strip from you binary when submitting the build to iTunes Connect. +```bash +export SENTRY_PROPERTIES=sentry.properties +function getProperty { + PROP_KEY=$1 + PROP_VALUE=`cat $SENTRY_PROPERTIES | grep "$PROP_KEY" | cut -d'=' -f2` + echo $PROP_VALUE +} +if [ ! -f $SENTRY_PROPERTIES ]; then + echo "warning: SENTRY: sentry.properties file not found! Skipping symbol upload." + exit 0 +fi +echo "# Reading property from $SENTRY_PROPERTIES" +SENTRY_CLI=$(getProperty "cli.executable") +SENTRY_COMMAND="../../$SENTRY_CLI upload-dsym" +$SENTRY_COMMAND +``` -{% capture __alert_content -%} -If you are getting an error while submitting your build to iTunes Connect, this script is probably missing. Also readding the plugin helped some people. +The next script makes sure that all unused architectures are striped from your binary when submitting the build to iTunes Connect. + +If you are getting an error while submitting your build to iTunes Connect, this script is probably missing. Also re-adding the plugin helped some people. +{% raw %} ```bash # SENTRY_FRAMEWORK_PATCH APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}" @@ -129,12 +81,8 @@ do mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH" done ``` -{%- endcapture -%} +{% endraw %} {%- include components/alert.html title="Note" content=__alert_content %} - -## Deep Dive - -- [Using Sentry with Ionic]({%- link _documentation/clients/cordova/ionic.md -%}) diff --git a/src/collections/_documentation/clients/electron/index.md b/src/collections/_documentation/platforms/javascript/electron/index.md similarity index 53% rename from src/collections/_documentation/clients/electron/index.md rename to src/collections/_documentation/platforms/javascript/electron/index.md index e3d290cb7bf30..e43aa0e312352 100644 --- a/src/collections/_documentation/clients/electron/index.md +++ b/src/collections/_documentation/platforms/javascript/electron/index.md @@ -1,6 +1,6 @@ --- title: Electron -sidebar_order: 3 +sidebar_order: 2000 --- `@sentry/electron` is the official Sentry SDK for Electron applications. It can capture JavaScript exceptions in the main process and renderers, as well as collect native crash reports (Minidumps). @@ -15,30 +15,24 @@ This SDK is still in beta and undergoing active development. It is part of an ea %}{% capture __alert_content -%} Support for Electron is currently limited to [sentry.io](https://sentry.io). The latest on-premise version of Sentry (_8.22.0_) does not provide server-side support for native crashes and their debug information files. Full support for Electron will made available to all on-premise customers with the next release. -To use the Electron SDK for reporting JavaScript errors at your own discretion, disable native crash handling and use the private DSN: +To use the Electron SDK for reporting JavaScript errors at your own discretion, disable native crash handling and use the DSN: -```javascript -const { init } = require('@sentry/electron'); -init({ - dsn: '___DSN___', - enableNative: false, -}); -``` {%- endcapture -%} {%- include components/alert.html title="Sentry On-Premise" content=__alert_content %} -## Installation - -The Electron SDK is distributed via _npm_: - -```sh -$ npm install --save @sentry/electron -$ yarn add @sentry/electron +```javascript +const { init } = require('@sentry/electron'); +init({ + dsn: '___PUBLIC_DSN___', + enableNative: false, +}); ``` +## Wizard + Our Sentry Wizard can help with the setup process. Make sure you have installed the `@sentry/wizard` npm package globally, then run: ```sh @@ -50,36 +44,65 @@ This will guide you through the installation and configuration process and sugge ## Configuring the Client -Initialize the client and configure it to use your [Sentry DSN]({%- link _documentation/learn/quickstart.md -%}#configure-the-dsn): +After [configuring the SDK]({%- link _documentation/learn/quickstart.md -%}?platform=electron#configure-the-sdk) the [Electron CrashReporter](https://electronjs.org/docs/api/crash-reporter) for native app crashes and captures any uncaught JavaScript exceptions using the JavaScript SDKs under the hood. Be sure to call this function as early as possible in the main process and all renderer processes to also catch errors during startup. + +## Browser integration + +We recommend to put the initialization in a separate JavaScript module, to keep configuration options consistent. This also allows to use it as preload script when creating new `BrowserWindow` instances: ```javascript -const { init } = require('@sentry/electron'); -init({ - dsn: '___PUBLIC_DSN___', - // more options... +mainWindow = new BrowserWindow({ + width: 800, + height: 600, + webPreferences: { + preload: path.join(__dirname, 'sentry.js') + } }); ``` -This configures the [Electron CrashReporter](https://electronjs.org/docs/api/crash-reporter) for native app crashes and captures any uncaught JavaScript exceptions using the JavaScript SDKs under the hood. Be sure to call this function as early as possible in the main process and all renderer processes to also catch errors during startup. +After this, the SDK is ready to capture any uncaught exception and native crashes that occur in those processes. + +## Node Integration + +The SDK requires some NodeJS APIs to operate properly. When creating windows without Node integration, the SDK must be loaded in a preload script, as described above. Doing so also ensures that the SDK is loaded as early as possible. -For more information on all configuration options, as well as the correct setup in [Sandbox mode](https://electronjs.org/docs/api/sandbox-option) or with disabled Node integration, see [_Configuration_]({%- link _documentation/clients/electron/config.md -%}). +```javascript +mainWindow = new BrowserWindow({ + width: 800, + height: 600, + webPreferences: { + nodeIntegration: false, + preload: path.join(__dirname, 'sentry.js') + } +}); +``` + +## Sandbox Mode -## Manually Reporting Errors +[Sandbox mode](https://electronjs.org/docs/api/sandbox-option) fully isolates the renderer processes from the operating system using OS-specific methods. Since most node APIs require system access, they are not available in sandbox mode, most notably `require()`. See the linked documentation for a detailed description of sandbox restrictions. -By default, the Electron SDK makes a best effort to capture any uncaught exception and send crash reports from the Electron processes to Sentry. +The Electron SDK can still be used from within a preload script. However, it needs to be bundled into a single file using bundlers like Webpack or Rollup due to the missing `require()` function. Please refer to the respective documentation your chosen tool for all possible configuration options. -To report errors manually, wrap potentially problematic code with a `try...catch` block and call _captureException_: +The SDK is written in a way that prevents bundlers from processing any code that is only meant to be executed in the main process. The only remaining external dependency is `electron`, which must be explicitly excluded from inlining. For Webpack, this would be: ```javascript -const { captureException } = require('@sentry/electron'); -try { - myEvilOperation(); -} catch (e) { - captureException(e); -} +module.exports = { + externals: { + electron: 'commonjs electron', + }, + // ... +}; ``` -The SDK will automatically add useful information, such as the app name and version or collect breadcrumbs for certain events. But there are more ways to report errors and add custom metadata. For a complete guide on this see [_JavaScript Usage_]({%- link _documentation/clients/electron/javascript.md -%}). +Or for Rollup: + +```javascript +export default { + external: ['electron'], + plugins: [commonjs()], + // ... +}; +``` ## Uploading Debug Information @@ -89,7 +112,7 @@ To get symbolicated stack traces for native crashes, you have to upload debug sy $ node sentry-symbols.js ``` -If your app uses a custom Electron fork, contains modules with native extensions or spawns subprocesses, you have to upload those symbols manually using Sentry CLI. For more information, see [_Native Usage_]({%- link _documentation/clients/electron/native.md -%}). +If your app uses a custom Electron fork, contains modules with native extensions or spawns subprocesses, you have to upload those symbols manually using Sentry CLI. For more information, see [_Native Usage_]({%- link _documentation/platforms/javascript/electron/native.md -%}). {% capture __alert_content -%} It is currently not possible to send events from native code (such as a C++ extension). However, crashes will still be reported to Sentry if they happen in a process where the SDK has been configured. Also, crash reports from sub processes will not be reported automatically on all platforms. This feature will be added in a future SDK update. @@ -101,13 +124,10 @@ It is currently not possible to send events from native code (such as a C++ exte ## Dealing with Minified Source Code -The Electron SDK supports [Source Maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). If you upload source maps in addition to your minified files that data becomes available in Sentry. For more information see [_Source Maps_]({%- link _documentation/clients/electron/sourcemaps.md -%}). +The Electron SDK supports [Source Maps](http://www.html5rocks.com/en/tutorials/developertools/sourcemaps/). If you upload source maps in addition to your minified files that data becomes available in Sentry. For more information see [_Source Maps_]({%- link _documentation/platforms/javascript/electron/sourcemaps.md -%}). ## Deep Dive For more detailed information about how to get most out of the Electron SDK, there is additional documentation available that covers all the rest: -- [Configuration]({%- link _documentation/clients/electron/config.md -%}) -- [JavaScript Usage]({%- link _documentation/clients/electron/javascript.md -%}) -- [Native Usage]({%- link _documentation/clients/electron/native.md -%}) -- [Source Maps]({%- link _documentation/clients/electron/sourcemaps.md -%}) +- [Native Usage]({%- link _documentation/platforms/javascript/electron/native.md -%}) diff --git a/src/collections/_documentation/clients/electron/native.md b/src/collections/_documentation/platforms/javascript/electron/native.md similarity index 99% rename from src/collections/_documentation/clients/electron/native.md rename to src/collections/_documentation/platforms/javascript/electron/native.md index 7ccf952a58d85..e38c03de9c30f 100644 --- a/src/collections/_documentation/clients/electron/native.md +++ b/src/collections/_documentation/platforms/javascript/electron/native.md @@ -1,6 +1,5 @@ --- title: 'Native Usage' -sidebar_order: 2 --- Sentry can process Minidumps created when the Electron process or one of its renderers crashes. To do so, the SDK needs to upload those files once the application restarts (or immediately for renderer crashes). All event meta data including user information and breadcrumbs are included in these uploads. diff --git a/src/collections/_documentation/platforms/javascript/electron/sourcemaps.md b/src/collections/_documentation/platforms/javascript/electron/sourcemaps.md new file mode 100644 index 0000000000000..56c26c17ecf77 --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/electron/sourcemaps.md @@ -0,0 +1,12 @@ +--- +title: 'Source Maps' +sidebar_order: 3 +--- + +To find out why Sentry needs your source maps and how to provide them visit: [Source Maps]({%- link _documentation/platforms/javascript/sourcemaps.md -%}) + +## Native Application + +To allow Sentry to match source code references to uploaded source maps or source files, make sure your tool outputs files relative to your project root folder and prefixes them either with `/` or with `~/`. Some tools do this automatically (e.g. Webpack), or have a configuration option (e.g. TypeScript). For others, please see the section on rewriting source maps before uploading. + +The SDK will rewrite stack traces before sending them to Sentry. If your application generates manual stack traces for some reason, make sure stack frames always contain relative paths from the project root starting with `~/` or `app:///`. diff --git a/src/collections/_documentation/platforms/javascript/ember.md b/src/collections/_documentation/platforms/javascript/ember.md new file mode 100644 index 0000000000000..3ede8778c660e --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/ember.md @@ -0,0 +1,30 @@ +--- +title: Ember +sidebar_order: 50 +--- + +To use Sentry with your Ember application, you will need to use `@sentry/browser` (Sentry’s browser JavaScript SDK). +On its own, `@sentry/browser` will report any uncaught exceptions triggered from your application. +Also, you need to install `ember-cli-cjs-transform` with `ember install ember-cli-cjs-transform`. + +Add this to your `ember-cli-build.js` file: + +```javascript +app.import('node_modules/@sentry/browser/dist/index.js', { + using: [ + { transformation: 'cjs', as: '@sentry/browser' } + ] +}); +``` + +Then add this to your `app.js`: + +```javascript +import * as Sentry from '@sentry/browser' + +Sentry.init({ + dsn: '___PUBLIC_DSN___', + integrations: [new Sentry.Integrations.Ember()] +}); +``` + \ No newline at end of file diff --git a/src/collections/_documentation/platforms/javascript/express.md b/src/collections/_documentation/platforms/javascript/express.md new file mode 100644 index 0000000000000..9a82373760cca --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/express.md @@ -0,0 +1,36 @@ +--- +title: Express +sidebar_order: 1010 +--- + + +Our Express integration only requires _@sentry/node_ to be installed then you can use it like this: + +```javascript +const express = require('express'); +const app = express(); +const Sentry = require('@sentry/node') ; + +Sentry.init({ dsn:'___PUBLIC_DSN___' }); + +// The request handler must be the first middleware on the app +app.use(Sentry.Handlers.requestHandler()); + +app.get('/', function mainHandler(req, res) { + throw new Error('Broke!'); +}); + +// The error handler must be before any other error middleware +app.use(Sentry.Handlers.errorHandler()); + +// Optional fallthrough error handler +app.use(function onError(err, req, res, next) { + // The error id is attached to `res.sentry` to be returned + // and optionally displayed to the user for support. + res.statusCode = 500; + res.end(res.sentry + '\n'); +}); + +app.listen(3000); +``` + \ No newline at end of file diff --git a/src/collections/_documentation/platforms/javascript/index.md b/src/collections/_documentation/platforms/javascript/index.md new file mode 100644 index 0000000000000..58b6fcef81216 --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/index.md @@ -0,0 +1,110 @@ +--- +title: JavaScript +sidebar_order: 10 +--- + +{% include learn-sdk.md platform="javascript" %} + +All our JavaScript related SDKs provide the same API still there are some differences between them +which this section of the docs explains. + +## Integrations + +All of our SDKs provide _Integrations_ which can be seen of some kind of plugins. All JavaScript SDKs provide default _Integrations_ please check details of a specific SDK to see which _Integrations_ they provides. + +One thing is the same across all our JavaScript SDKs and that's how you add or remove _Integrations_, e.g.: for `@sentry/browser`. + +### Adding an Integration + +```javascript +import * as Sentry from '@sentry/browser'; + +// All integration that come with an SDK can be found in +// Sentry.Integrations +// Custom integration must conform this interface: https://bit.ly/2xdcbAR + +Sentry.init({ + dsn: '___PUBLIC_DSN___', + integrations: [new MyAwesomeIntegration()], +}) +``` + +### Removing an Integration + +In this example we will remove the by default enabled integration for adding breadcrumbs to the event: + +```javascript +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + dsn: '___PUBLIC_DSN___', + integrations: (integrations) => { // integrations will be all default integrations + return integrations.filter(integration => integration.name !== 'Breadcrumbs'); + } +}) +``` + +### Alternative way of setting an Integration + +```javascript +import * as Sentry from '@sentry/browser'; + +Sentry.init({ + dsn: '___PUBLIC_DSN___', + integrations: (integrations) => { // integrations will be all default integrations + integrations.push(new MyCustomIntegration()) + return integrations + } +}) +``` + +## Hints + +Event and Breadcrumb `hints` are objects containing various information used to put together an event or a breadcrumb. For events, those are things like `event_id`, `originalException`, `syntheticException` (used internally to generate cleaner stacktrace), and any other arbitrary `data` that user attaches. For breadcrumbs it's all implementation dependent. For XHR requests, hint contains xhr object itself, for user interactions it contains DOM element and event name etc. + +They are available in two places. `beforeSend`/`beforeBreadcrumb` and `eventProcessors`. Those are two ways we'll allow users to modify what we put together. + +These common hints currently exist for events: + +`originalException` + +: The original exception that caused the event to be created. This is useful for changing how events + are grouped or to extract additional information. + +`syntheticException` + +: When a string or a non error object is raised, Sentry creates a synthetic exception so you can get a + basic stacktrace. This exception is stored here for further data extraction. + +And these exist for breadcrumbs: + +`event` + +: For breadcrumbs created from browser events the event is often supplied to the breadcrumb as hint. This + for instance can be used to extract data from the target DOM element into a breadcrumb. + +`level` / `input` + +: For breadcrumbs created from console log interceptions this holds the original console log level and the + original input data to the log function. + +`response` / `input` + +: For breadcrumbs created from HTTP requests this holds the response object + (from the fetch api) and the input parameters to the fetch function. + +`request` / `response` / `event` + +: For breadcrumbs created from HTTP requests this holds the request and response object + (from the node HTTP API) as well as the node event (`response` or `error`). + +`xhr` + +: For breadcrumnbs created from HTTP requests done via the legacy `XMLHttpRequest` API this holds + the original xhr object. + +## EventProcessors + +With `eventProcessors` you are able to hook into the process of enriching the event with additional data. +You can add you own `eventProcessor` on the current scope. The difference to `beforeSend` is that +`eventProcessors` run on the scope level where `beforeSend` runs globally not matter in which scope you are. diff --git a/src/collections/_documentation/clients/cordova/ionic.md b/src/collections/_documentation/platforms/javascript/ionic.md similarity index 98% rename from src/collections/_documentation/clients/cordova/ionic.md rename to src/collections/_documentation/platforms/javascript/ionic.md index e43aa715bbcac..035ff998d0543 100644 --- a/src/collections/_documentation/clients/cordova/ionic.md +++ b/src/collections/_documentation/platforms/javascript/ionic.md @@ -1,5 +1,6 @@ --- -title: 'Using Sentry with Ionic' +title: Ionic +sidebar_order: 201 --- To use Sentry with [Ionic](https://ionicframework.com/) you have to add _sentry-cordova_ as a depenendcy to you package.json. diff --git a/src/collections/_documentation/platforms/javascript/koa.md b/src/collections/_documentation/platforms/javascript/koa.md new file mode 100644 index 0000000000000..530fa2d820c9a --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/koa.md @@ -0,0 +1,23 @@ +--- +title: Koa +sidebar_order: 1011 +--- + + + +Our Koa integration only requires _@sentry/node_ to be installed then you can use it like this: + +```javascript +const koa = require('koa'); +const app = koa(); +const Sentry = require('@sentry/node') ; + +Sentry.init({ dsn:'___PUBLIC_DSN___' }); + +app.on('error', function (err) { + Sentry.captureException(err); +}); + +app.listen(3000); +``` + \ No newline at end of file diff --git a/src/collections/_documentation/platforms/javascript/node.md b/src/collections/_documentation/platforms/javascript/node.md new file mode 100644 index 0000000000000..08f16f71c9ac5 --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/node.md @@ -0,0 +1,22 @@ +--- +title: Node +sidebar_order: 1000 +--- + +{% include learn-sdk.md platform="node" %} + +### Running on serverless architecture + +If you are running our SDK in a serverless architecture like AWS Lambda, Google Cloud Functions you might want to wait until all errors are sent. +Here is an example, specific to node to wait for 2000ms for the request buffer to drain. + +```javascript +import { getCurrentHub } from '@sentry/node'; + +getCurrentHub().getClient().close(2000).then(result => { + if (!result) { + console.log('We reached the timeout for emptying the request buffer, still exiting now!'); + } + global.process.exit(1); +}) +``` \ No newline at end of file diff --git a/src/collections/_documentation/platforms/javascript/react.md b/src/collections/_documentation/platforms/javascript/react.md new file mode 100644 index 0000000000000..17febf47b1f6c --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/react.md @@ -0,0 +1,44 @@ +--- +title: React +sidebar_order: 30 +--- + +To use Sentry with your React application, you will need to use `@sentry/browser` (Sentry’s browser JavaScript SDK). +On its own, `@sentry/browser` will report any uncaught exceptions triggered from your application. + +If you’re using React 16 or above, Error Boundaries are an important tool for defining the behavior of your application in the face of errors. Be sure to send errors they catch to Sentry using `Sentry.captureException`, and optionally this is also a great opportunity to surface User Feedback + +```jsx +import * as Sentry from '@sentry/browser'; +// Sentry.init has to be called in the somewhere before + +class ExampleBoundary extends Component { + constructor(props) { + super(props); + this.state = { error: null }; + } + + componentDidCatch(error, errorInfo) { + this.setState({ error }); + Sentry.configureScope(scope => { + Object.keys(errorInfo).forEach(key => { + scope.setExtra(key, errorInfo[key]); + }); + }); + Sentry.captureException(error); + } + + render() { + if (this.state.error) { + //render fallback UI + return ( + Sentry.showReportDialog()}>Report feedback + ); + } else { + //when there's not an error, render children untouched + return this.props.children; + } + } +} +``` + \ No newline at end of file diff --git a/src/collections/_documentation/platforms/javascript/sourcemaps.md b/src/collections/_documentation/platforms/javascript/sourcemaps.md new file mode 100644 index 0000000000000..1bf10ad80e0e6 --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/sourcemaps.md @@ -0,0 +1,338 @@ +--- +title: 'Source Maps' +sidebar_order: 60 +--- + +Sentry supports un-minifying JavaScript via [Source Maps](http://blog.sentry.io/2015/10/29/debuggable-javascript-with-source-maps.html). This lets you view source code context obtained from stack traces in their original untransformed form, which is particularly useful for debugging minified code (e.g. UglifyJS), or transpiled code from a higher-level language (e.g. TypeScript, ES6). + +## Specify the release + +If you are uploading source map artifacts yourself, you must specify the release in your SDK see: [Releases]({%- link _documentation/learn/releases.md -%}). Sentry will use the release name to associate digested event data with the files you’ve uploaded via the [releases API]({%- link _documentation/api/releases/index.md -%}), [sentry-cli]({%- link _documentation/learn/cli/index.md -%}) or [sentry-webpack-plugin](https://github.com/getsentry/sentry-webpack-plugin). This step is optional if you are hosting source maps on the remote server. + +## Generating a Source Map + +Most modern JavaScript transpilers support source maps. Below are instructions for some common tools. + +### UglifyJS + +UglifyJS is a popular tool for minifying your source code for production. It can dramatically reduce the size of your files by eliminating whitespace, rewriting variable names, removing dead code branches, and more. + +If you are using UglifyJS to minify your source code, the following command will additionally generate a source map that maps the minified code back to the original source: + +```bash +uglifyjs app.js \ + -o app.min.js.map \ + --source-map url=app.min.js.map,includeSources +``` + +### Webpack + +Webpack is a powerful build tool that resolves and bundles your JavaScript modules into files fit for running in the browser. It also supports various _loaders_ to transpile higher-level languages, reference stylesheets, or include static assets. + +We have created a convenient [webpack plugin](https://github.com/getsentry/sentry-webpack-plugin) that configures source maps and uploads them to Sentry during the build. This is the recommended way for uploading sources to Sentry. First, install the plugin via: + +```sh +$ npm install --save-dev @sentry/webpack-plugin +$ yarn add --dev @sentry/webpack-plugin +``` + +To allow the plugin to upload source maps automatically, create a `.sentryclirc` or configure environment variables as described in the [CLI configuration docs]({%- link _documentation/learn/cli/configuration.md -%}). Then, add the plugin to your `webpack.config.js`: + +```javascript +const SentryWebpackPlugin = require('@sentry/webpack-plugin'); + +module.exports = { + // other configuration + plugins: [ + new SentryWebpackPlugin({ + include: '.', + ignoreFile: '.sentrycliignore', + ignore: ['node_modules', 'webpack.config.js'], + configFile: 'sentry.properties' + }) + ] +}; +``` + +Alternatively, if you prefer to upload source maps manually, Webpack just needs to be configured to output source maps: + +```javascript +module.exports = { + output: { + path: path.join(__dirname, 'dist'), + filename: "[name].js", + sourceMapFilename: "[name].js.map" + } + // other configuration +}; +``` + +{% capture __alert_content -%} +In case you use [SourceMapDevToolPlugin](https://webpack.js.org/plugins/source-map-dev-tool-plugin) for more fine grained control of source map generation, leave `noSources` turned off, so Sentry can display proper source code context in event stack traces. +{%- endcapture -%} +{%- include components/alert.html + title="Note" + content=__alert_content +%} + +### SystemJS + +SystemJS is the default module loader for Angular 2 projects. The [SystemJS build tool](https://github.com/systemjs/builder) can be used to bundle, transpile, and minify source code for use in production environments, and can be configured to output source maps. + +```javascript +builder.bundle('src/app.js', 'dist/app.min.js', { + minify: true, + sourceMaps: true, + sourceMapContents: true +}); +``` + +{% capture __alert_content -%} +All of the example configurations above inline your original, un-transformed source files into the generated source map file. Sentry requires both source map(s) **and** your original source files in order to perform reverse transformations. If you choose NOT to inline your source files, you must make those source files available to Sentry in _addition_ to your source maps (see below). +{%- endcapture -%} +{%- include components/alert.html + title="Inline Sources" + content=__alert_content +%} + +### TypeScript + +The TypeScript compiler can output source maps. Configure the `sourceRoot` property to `/` to strip the build path prefix from generated source code references. This allows Sentry to match source files relative to your source root folder: + +```json +{ + "compilerOptions": { + "sourceMap": true, + "inlineSources": true, + "sourceRoot": "/" + } +} +``` + +## Making Source Maps Available to Sentry + +Source maps can be either: + +1. Served publicly over HTTP alongside your source files. +2. Uploaded directly to Sentry (**recommended**). + +### Hosting Source Map Files + +By default, Sentry will look for source map directives in your compiled JavaScript files, which are located on the last line and have the following format: + +```javascript +//# sourceMappingURL= +``` + +When Sentry encounters such a directive, it will resolve the source map URL relative the source file in which it is found, and attempt an HTTP request to fetch it. + +So for example if you have a minified JavaScript file located at `http://example.org/js/app.min.js`. And in that file, on the last line, the following directive is found: + +```javascript +//# sourceMappingURL=app.js.map +``` + +Sentry will attempt to fetch `app.js.map` from [http://example.org/js/app.js.map](http://example.org/js/app.js.map). + +Alternatively, during source map generation you can specify a fully qualified URL where your source maps are located: + +```javascript +//# sourceMappingURL=http://example.org/js/app.js.map +``` + +While making source maps available to Sentry from your servers is the easiest integration, it is not always advisable: + +- Sentry may not always be able to reach your servers. +- If you do not specify versions in your asset URLs, there may be a version mismatch +- The additional latency may mean that source mappings are not available for all errors. + +For these reasons, it is recommended to upload source maps to Sentry beforehand (see below). + +{% capture __alert_content -%} +While the recommended solution is to upload your source artifacts to Sentry, sometimes it’s necessary to allow communication from Sentry’s internal IPs. For more information on Sentry’s public IPs, [IP Ranges]({%- link ip-ranges.md -%}#ip-ranges). +{%- endcapture -%} +{%- include components/alert.html + title="Working Behind a Firewall" + content=__alert_content +%}{% capture __alert_content -%} +If you want to keep your source maps secret and choose not to upload your source maps directly to Sentry, you can enable the “Security Token” option in your project settings. This will cause outbound requests from Sentry’s servers to URLs originating from your “Allowed Domains” to have the HTTP header “X-Sentry-Token: {token}” appended, where {token} is a secure value you define. You can then configure your web server to allow access to your source maps when this header/token pair is present. You can alternatively override the default header name (X-Sentry-Token) and use HTTP Basic Authentication, e.g. by passing “Authorization: Basic {encoded_password}”. +{%- endcapture -%} +{%- include components/alert.html + title="Secure Access to Source Maps" + content=__alert_content +%} + +### Uploading Source Maps to Sentry + +Except for webpack, the recommended way to upload source maps is using [Sentry CLI]({%- link _documentation/learn/cli/index.md -%}). If you have used _Sentry Wizard_ to set up your project, it has already created all necessary configuration to upload source maps. Otherwise, follow the [CLI configuration docs]({%- link _documentation/learn/cli/configuration.md -%}) to set up your project. + +Sentry uses **Releases** to match the correct source maps to your events. To create a new release, run the following command (e.g. during publishing): + +```sh +$ sentry-cli releases new +``` + +Note the release name must be **unique within your organization** and match the `release` option in your SDK initialization code. Then, use the `upload-sourcemaps` command to scan a folder for source maps, process them and upload them to Sentry: + +```sh +$ sentry-cli releases files upload-sourcemaps /path/to/files +``` + +This command will upload all files ending in _.js_ and _.map_ to the specified release. If you wish to change these extensions – e.g. to upload typescript sources – use the `--ext` option: + +```sh +$ sentry-cli releases files upload-sourcemaps --ext ts,map /path/to/files +``` + +{% capture __alert_content -%} +Unfortunately, it can be quite challenging to ensure that source maps are actually valid and uploaded correctly. To ensure that everything is working as intended, you can add the `--validate` flag when uploading source maps. It attempts to parse the source maps and verify source references locally. Note that this flag might produce false positives if you have references to external source maps. +{%- endcapture -%} +{%- include components/alert.html + title="Validating source maps with Sentry CLI" + content=__alert_content +%} + +Until now, the release is in a draft state (“_unreleased_”). Once all source maps have been uploaded and your app has been published successfully, finalize the release with the following command: + +```sh +$ sentry-cli releases finalize +``` + +For convenience, you can alternatively pass the `--finalize` flag to the `new` command which will immediately finalize the release. + +Note: You dont _have_ to upload the source files (ref’d by source maps), but without them the grouping algorithm will not be as strong, and the UI will not show any contextual source. + +Additional information can be found in the [Releases API documentation]({%- link _documentation/api/releases/index.md -%}). + +{% capture __alert_content -%} +It’s not uncommon for a web application to be accessible at multiple origins. For example: + +- Website is operable over both `https` and `http` +- Geolocated web addresses: e.g. `https://us.example.com`, `https://eu.example.com` +- Multiple static CDNs: e.g. `https://static1.example.com`, `https://static2.example.com` +- Customer-specific domains/subdomains + +In this situation, **identical** JavaScript and source map files may be located at two or more distinct origins. If you are dealing with such a deployment, you have two choices for naming your uploaded artifacts: + +1. Upload the same artifact multiple times with each possible URL where it appears, for example: + + > - [https://static1.example.com/js/app.js](https://static1.example.com/js/app.js) + > - [https://static2.example.com/js/app.js](https://static2.example.com/js/app.js) +2. Alternatively, you can omit the protocol + host and use a special tilde (~) prefixed path like so: + + > ~/js/app.js + +The ~ prefix tells Sentry that for a given URL, **any** combination of protocol and hostname whose path is `/js/app.js` should use this artifact. **ONLY** use this method if your source/source map files are identical at all possible protocol/hostname combinations. Note that Sentry will prioritize full URLs over tilde prefixed paths if found. +{%- endcapture -%} +{%- include components/alert.html + title="Assets Accessible at Multiple Origins" + content=__alert_content +%} + +{% capture __alert_content -%} +Unfortunately it can be quite challenging to ensure that source maps are actually valid themselves and uploaded correctly. To ensure that everything is working as intended you can use the _–validate_ flag when uploading source maps which will attempt to locally parse the source map and look up the references. Note that there are known cases where the validate flag will indicate failures when the setup is correct (if you have references to external source maps then the validation tool will indicate a failure). + +Here are some things you can check in addition to the validation step: + +- Make sure that the URL prefix is correct for your files. This is easy to get wrong. +- Make sure you upload the matching source maps for your minimized files. +- Make sure that your minified files you have on your servers actually have references to your files. +{%- endcapture -%} +{%- include components/alert.html + title="Validating source maps with Sentry CLI" + content=__alert_content +%} + +## Troubleshooting + +Source maps can sometimes be tricky to get going. If you’re having trouble, try the following tips. + +### Verify your source maps are built correctly + +We maintain an online validation tool that can be used to test your source (and source maps) against: [sourcemaps.io](http://sourcemaps.io). + +Alternatively, if you are using Sentry CLI to upload source maps to Sentry, you can use the _–validate_ command line option to verify your source maps are correct. + +### Verify sourceMappingURL is present + +Some CDNs automatically strip comments from static files, including JavaScript files. This can have the effect of stripping your JavaScript file of its `sourceMappingURL` directive, because it is considered a comment. For example, CloudFlare has a feature called [Auto-Minify](https://blog.cloudflare.com/an-all-new-and-improved-autominify/) which will strip `sourceMappingURL` if it is enabled. + +Double-check that your deployed, final JavaScript files have `sourceMappingURL` present. + +### Verify artifact names match sourceMappingURL + +When [uploading source maps to Sentry](#uploading-source-maps-to-sentry), you must name your source map files with the same name found in `sourceMappingURL`. + +For example, if you have the following in a minified application file, `app.min.js`: + +```javascript +//-- end app.min.js +//# sourceMappingURL=https://example.com/dist/js/app.min.js.map +``` + +Sentry will look for a matching artifact named exactly `https://example.com/dist/js/app.min.js.map`. + +Note also that Sentry will resolve relative paths. For example, if you have the following: + +```JavaScript +// -- end app.min.js (located at https://example.com/dist/js/app.min.js) +//# sourceMappingURL=app.min.js.map +``` + +Sentry will resolve `sourceMappingURL` relative to `https://example.com/dist/js/` (the root path from which `app.min.js` was served). You will again need to name your source map with the full URL: `https://example.com/dist/js/app.min.js.map`. + +If you serve the same assets from multiple origins, you can also alternatively use our tilde (~) path prefix to ignore matching against protocol + hostname. In which case, `~/dist/js/app.min.js.map`, will also work. See: [Assets Accessible at Multiple Origins](#assets-multiple-origins). + +### Verify artifacts are uploaded before errors occur + +Sentry expects that source code and source maps in a given release are uploaded to Sentry **before** errors occur in that release. + +If you upload artifacts **after** an error is captured by Sentry, Sentry will not go back and retroactively apply any source annotations to those errors. Only new errors triggered after the artifact was uploaded will be affected. + +### Verify your source maps work locally + +If you find that Sentry is not mapping filename, line, or column mappings correctly, you should verify that your source maps are functioning locally. To do so, you can use Node.js coupled with Mozilla’s [source-map library](https://github.com/mozilla/source-map). + +First, install `source-map` globally as an npm module: + +```bash +npm install -g source-map +``` + +Then, write a script that reads your source map file and tests a mapping. Here’s an example: + +```JavaScript +var fs = require('fs'), + path = require('path'), + sourceMap = require('source-map'); + +// file output by Webpack, Uglify, etc. +var GENERATED_FILE = path.join('.', 'app.min.js.map'); + +// line and column located in your generated file (e.g. source of your error +// from your minified file) +var GENERATED_LINE_AND_COLUMN = {line: 1, column: 1000}; + +var rawSourceMap = fs.readFileSync(GENERATED_FILE).toString(); +var smc = new sourceMap.SourceMapConsumer(rawSourceMap); + +var pos = smc.originalPositionFor(GENERATED_LINE_AND_COLUMN); + +// should see something like: +// { source: 'original.js', line: 57, column: 9, name: 'myfunc' } +console.log(pos); +``` + +If you have the same (incorrect) results locally as you do via Sentry, double-check your source map generation configuration. + +### Verify your source files are not too large + +For an individual artifact, Sentry accepts a max filesize of **40 MB**. + +Often users hit this limit because they are transmitting source files at an interim build stage. For example, after Webpack/Browserify has combined all your source files, but before minification has taken place. If possible, send the original source files. + +### Verify artifacts are not gzipped + +The Sentry API currently only works with source maps and source files that are uploaded as plain text (UTF-8 encoded). If the files are uploaded in a compressed format (e.g. gzip), they will be not be interpreted correctly. + +This sometimes occurs with build scripts and plugins that produce pre-compressed minified files. For example, Webpack’s [compression plugin](https://github.com/webpack/compression-webpack-plugin). You’ll need to disable such plugins and perform the compression _after_ the generated source maps / source files have been uploaded to Sentry. diff --git a/src/collections/_documentation/platforms/javascript/vue.md b/src/collections/_documentation/platforms/javascript/vue.md new file mode 100644 index 0000000000000..ec207db26da6b --- /dev/null +++ b/src/collections/_documentation/platforms/javascript/vue.md @@ -0,0 +1,20 @@ +--- +title: Vue +sidebar_order: 40 +--- + +To use Sentry with your Vue application, you will need to use `@sentry/browser` (Sentry’s browser JavaScript SDK). +On its own, `@sentry/browser` will report any uncaught exceptions triggered from your application. + +Additionally, the Vue _integration_ will capture the name and props state of the active component where the error was thrown. This is reported via Vue’s `config.errorHandler` hook. + +Passing in `Vue` is optional, if you not pass it `window.Vue` has to be present. + +```javascript +import * as Sentry from '@sentry/browser' + +Sentry.init({ + dsn: '___PUBLIC_DSN___', + integrations: [new Sentry.Integrations.Vue({ Vue })] +}) +``` \ No newline at end of file diff --git a/src/collections/_documentation/clients/minidump/breakpad.md b/src/collections/_documentation/platforms/minidump/breakpad.md similarity index 100% rename from src/collections/_documentation/clients/minidump/breakpad.md rename to src/collections/_documentation/platforms/minidump/breakpad.md diff --git a/src/collections/_documentation/clients/minidump/crashpad.md b/src/collections/_documentation/platforms/minidump/crashpad.md similarity index 100% rename from src/collections/_documentation/clients/minidump/crashpad.md rename to src/collections/_documentation/platforms/minidump/crashpad.md diff --git a/src/collections/_documentation/clients/minidump/index.md b/src/collections/_documentation/platforms/minidump/index.md similarity index 90% rename from src/collections/_documentation/clients/minidump/index.md rename to src/collections/_documentation/platforms/minidump/index.md index 46bc30150a159..1a0ecd6b17a35 100644 --- a/src/collections/_documentation/clients/minidump/index.md +++ b/src/collections/_documentation/platforms/minidump/index.md @@ -3,13 +3,14 @@ title: Minidump sidebar_order: 8 --- -Sentry can process Minidump crash reports, a memory dump used on Windows and by open-source libraries like [_Breakpad_]({%- link _documentation/clients/minidump/breakpad.md -%}) or [_Crashpad_]({%- link _documentation/clients/minidump/crashpad.md -%}). You can either choose to generate and upload minidumps yourself or use a higher-level SDK for platforms with built-in support for native crashes: +Sentry can process Minidump crash reports, a memory dump used on Windows and by open-source libraries like [_Breakpad_]({%- link _documentation/platforms/minidump/breakpad.md -%}) or [_Crashpad_]({%- link _documentation/platforms/minidump/crashpad.md -%}). You can either choose to generate and upload minidumps yourself or use a higher-level SDK for platforms with built-in support for native crashes: - [_Cocoa_]({%- link _documentation/clients/cocoa/index.md -%}) -- [_Electron_]({%- link _documentation/clients/electron/index.md -%}) +- [_Electron_]({%- link _documentation/platforms/javascript/electron/index.md -%}) In order to receive symbolicated stack traces, you have to upload debug information to Sentry. For more information, see [Uploading Debug Information](#minidump-dif). + ## Platform and Language Support Minidumps are currently supported for **Windows, macOS and Linux**. There is no limitation as to which programming language can be used. Sentry can also demangle symbols from the following languages; other languages will show the mangled name instead: @@ -18,6 +19,7 @@ Minidumps are currently supported for **Windows, macOS and Linux**. There is no - ObjectiveC and ObjectiveC++ - Swift - Rust + ## What is a Minidump? {#what-is-a-minidump} @@ -39,12 +41,13 @@ Minidumps are memory dumps of the process at the moment it crashes. As such, the In addition to this information, you can add further meta data specific to Sentry, which can help in organizing and analyzing issues. For more information, see [Passing Additional Data](#minidump-additional). + ## Creating and Uploading Minidumps {#minidump-integration} Depending on your operating system and programming language, there are various alternatives to create minidumps and upload them to Sentry. See the following resources for libraries that support generating minidump crash reports: -- [Google Breakpad]({%- link _documentation/clients/minidump/breakpad.md -%}) -- [Google Crashpad]({%- link _documentation/clients/minidump/crashpad.md -%}) +- [Google Breakpad]({%- link _documentation/platforms/minidump/breakpad.md -%}) +- [Google Crashpad]({%- link _documentation/platforms/minidump/crashpad.md -%}) If you have already integrated a library that generates minidumps and would just like to upload them to Sentry, you need to configure the _Minidump Endpoint URL_, which can be found at _Project Settings > Client Keys (DSN)_. This endpoint expects a `POST` request with the minidump in the `upload_file_minidump` field: @@ -55,6 +58,7 @@ $ curl -X POST \ ``` To send additional information, simply add more form fields to this request. For a full description of fields accepted by Sentry, see [Passing Additional Data](#minidump-additional). + ## Passing Additional Data {#minidump-additional} diff --git a/src/collections/_documentation/platforms/python/celery.md b/src/collections/_documentation/platforms/python/celery.md new file mode 100644 index 0000000000000..ef0c8ebc8b5f5 --- /dev/null +++ b/src/collections/_documentation/platforms/python/celery.md @@ -0,0 +1,22 @@ +--- +title: Celery +sidebar_order: 2 +--- + +*Import name: `sentry_sdk.integrations.celery.CeleryIntegration`* + +The celery integration adds support for the [Celery Task Queue System](http://www.celeryproject.org/). + +Just add ``CeleryIntegration()`` to your ``integrations`` list. The integration does not +accept any arguments and will automatically report errors from all celery tasks: + +```python +import sentry_sdk +from sentry_sdk.integrations.celery import CeleryIntegration + +sentry_sdk.init(integrations=[CeleryIntegration()]) +``` + +Additionally the transaction on the event will be set to the task name and +the grouping will be improved for global celery errors such as timeouts. + \ No newline at end of file diff --git a/src/collections/_documentation/platforms/python/default-integrations.md b/src/collections/_documentation/platforms/python/default-integrations.md new file mode 100644 index 0000000000000..a9313e93f1cc2 --- /dev/null +++ b/src/collections/_documentation/platforms/python/default-integrations.md @@ -0,0 +1,48 @@ +--- +title: Default Integrations +sidebar_order: 10 +--- + +System integrations are integrations enabled by default that integrate into the +standard library or the interpreter itself. They are documented so you can see +what they do and that they can be disabled if they cause issues. To disable +system integrations set `default_integrations=False` when calling `init()`. + +## Atexit +*Import name: `sentry_sdk.integrations.atexit.AtExitIntegration`* + +This integrates with the interpreter's `atexit` system to automatically flush +events from the background queue on interpreter shutdown. Typically one does +not need to disable this. Even if the functionality is not wanted it can also +be disabled by setting the `shutdown_timeout` to `0` in the options to +`init()`. + +## Excepthook +*Import name: `sentry_sdk.integrations.excepthook.ExceptHookIntegration`* + +This integration registers with the interpreter's except hook system. Through this +any exception that is unhandled will be reported to Sentry automatically. Exceptions +raised interactive interpreter sessions will not be reported. + +## Deduplication +*Import name: `sentry_sdk.integrations.dedupe.DedupeIntegration`* + +This integration deduplicates certian events. This is enabled by default and should not +be disabled except in rare circumstances. Disabling this integration for instance will +cause duplicate error logging in the Flask framework. + +## Stdlib +*Import name: `sentry_sdk.integrations.stdlib.StdlibIntegration`* + +The stdlib integration instruments certain modules in the standard library to emit +breadcrumbs. This is enabled by default and rarely makes sense to disable. + +In detail it provides: + +* Breadcrumbs for HTTP requests done using `httplib`, which also includes + traffic going through `requests`. + +## Modules +*Import name: `sentry_sdk.integrations.modules.ModulesIntegration`* + +Send a list of installed Python packages along with each event. diff --git a/src/collections/_documentation/platforms/python/django.md b/src/collections/_documentation/platforms/python/django.md new file mode 100644 index 0000000000000..2cd7d1fdd72ae --- /dev/null +++ b/src/collections/_documentation/platforms/python/django.md @@ -0,0 +1,45 @@ +--- +title: Django +sidebar_order: 2 +--- + +*Import name: `sentry_sdk.integrations.django.DjangoIntegration`* + +The Django integration adds support for the [Django Web Framework](https://www.djangoproject.com/) +from Version 1.6 upwards. To configure the SDK initialize it with the Django +integration in your ``settings.py`` file: + +```python +import sentry_sdk +from sentry_sdk.integrations.django import DjangoIntegration + +sentry_sdk.init( + dsn="___PUBLIC_DSN___", + integrations=[DjangoIntegration()] +) +``` + +## Behavior + +This causes the following this to happen: + +* All exceptions are reported. + +* A bit of data is attached to each event: + + * Personally identifiable information (such as user ids, usernames, + cookies, authorization headers, ip addresses) is excluded unless + ``send_default_pii`` is set to ``True``. + + * Request data is attached to all events. + + * If you have ``django.contrib.auth`` installed and configured, user data + (current user id, email address, username) is attached to the event. + +* Logging with any logger will create breadcrumbs when the [Logging]({% link _documentation/platforms/python/logging.md %}) + integration is enabled (done by default). + +## User Feedback + +The user feedback feature can be used with this integration. For more information +see [User Feedback]({% link _documentation/learn/user-feedback.md %}?platform=django). diff --git a/src/collections/_documentation/platforms/python/flask.md b/src/collections/_documentation/platforms/python/flask.md new file mode 100644 index 0000000000000..14576f4330c26 --- /dev/null +++ b/src/collections/_documentation/platforms/python/flask.md @@ -0,0 +1,52 @@ +--- +title: Flask +sidebar_order: 2 +--- + + +*Import name: `sentry_sdk.integrations.flask.FlaskIntegration`* + +The Django integration adds support for the [Flask Web +Framework](http://flask.pocoo.org/). To configure the SDK initialize it with +the integration before or after your app has been initialized: + +```python +import sentry_sdk +from sentry_sdk.integrations.flask import FlaskIntegration + +sentry_sdk.init( + dsn="___PUBLIC_DSN___", + integrations=[FlaskIntegration()] +) + +app = Flask(__name__) +``` + + + +## Behavior + +* The Flask integration will be installed for all of your apps. It hooks into + Flask's signals, not anything on the app object. + +* A bit of data is attached to each event: + + * Personally identifiable information (such as user ids, usernames, + cookies, authorization headers, ip addresses) is excluded unless + ``send_default_pii`` is set to ``true``. + + * Request data is attached to all events. + + * If you have Flask-Login installed and configured, user data is attached to + the event. + +* All exceptions leading to a Internal Server Error are reported. + +* Logging with `app.logger` or really *any* logger will create breadcrumbs when + the [Logging]({% link _documentation/platforms/python/logging.md %}) + integration is enabled (done by default). + +## User Feedback + +The user feedback feature can be used with this integration. For more information +see [User Feedback]({% link _documentation/learn/user-feedback.md %}?platform=flask). diff --git a/src/collections/_documentation/platforms/python/index.md b/src/collections/_documentation/platforms/python/index.md new file mode 100644 index 0000000000000..9f5f62923c150 --- /dev/null +++ b/src/collections/_documentation/platforms/python/index.md @@ -0,0 +1,57 @@ +--- +title: Python +sidebar_order: 3 +--- + +{% include learn-sdk.md platform="python" %} + +The [Sentry Python SDK](https://pypi.org/project/sentry-sdk) provides Sentry +support for Python 2.7 and 3.4 or later. + +This documentation goes over some Python specific things such as integrations to +frameworks. + +## Integrations + +*Integrations* extend the functionality of the SDK for some common frameworks and +libraries. They can be seen as plugins that extend the functionality of the Sentry +SDK. Integrations are configured by a call to `sentry_sdk.init`. Any default +integration not in the list is automatically added unless `default_integrations` is +set to `False`. + +### Framework Integrations + +Framework integrations are opt-in integrations for large frameworks or libraries. Currently +the following are supported: + +* [Celery]({% link _documentation/platforms/python/celery.md %}) +* [Django]({% link _documentation/platforms/python/django.md %}) +* [Flask]({% link _documentation/platforms/python/flask.md %}) +* [Logging]({% link _documentation/platforms/python/logging.md %}) + +### Other Integrations + +In addition to framework integrations there are also a few other integrations: + +* [Default integrations]({% link _documentation/platforms/python/default-integrations.md %}) + +## Hints + +The Python SDK provides some common [hints]({% link _documentation/learn/hints.md %}) for breadcrumbs +and events. These hints are passed as the `hint` parameter to `before_send` and `before_breadcrumb` +(as well as event processors) as a dictionary. More than one hint can be supplied but this is rare. + +`exc_info` + +: If this hint is set then it's an exc info tuple in the form `(exc_type, exc_value, tb)`. This + can be used to extract additional information from the original error object. + +`log_record` + +: This hint is passed to breadcrumbs and contains the log record that crated it. It can be used + to extract additional information from the original `logging` log record that is not extracted by default. + Likewise it can be useful to discard uninteresting breadcrumbs. + +`httplib_request` + +: An `httplib` request object for breadcrumbs created from HTTP requests. diff --git a/src/collections/_documentation/platforms/python/logging.md b/src/collections/_documentation/platforms/python/logging.md new file mode 100644 index 0000000000000..ee4dd7d91e1ee --- /dev/null +++ b/src/collections/_documentation/platforms/python/logging.md @@ -0,0 +1,37 @@ +--- +title: Logging +sidebar_order: 2 +--- +*Import name: `sentry_sdk.integrations.logging.LoggingIntegration`* + +Calling ``sentry_sdk.init()`` already captures any logging message with a level +higher than or equal to ``INFO``. You can change this behavior by explicitly +passing the logging integration like any other: + +```python +import sentry_sdk +from sentry_sdk.integrations.logging import LoggingIntegration + +sentry_logging = LoggingIntegration( + level=logging.DEBUG, + event_level=logging.ERROR +) +sentry_sdk.init( + dsn="___PUBLIC_DSN___", + integrations=[sentry_logging] +) +``` + +The above configuration captures *all* messages, now including ``DEBUG``, as +breadcrumbs. Messages with level ``ERROR`` and above will show up as their own +events as well. + +## Config + +* ``level`` (default ``INFO``): Log records with a level higher than or equal + to ``level`` will be recorded as breadcrumbs. Any log record with a level + lower than this one is completely ignored. + +* ``event_level`` (default ``None``): Log records with a level higher than or + equal to ``event_level`` will additionally be reported as event. A value of + ``None`` means that no log records will be sent as events. diff --git a/src/collections/_documentation/platforms/rust/actix.md b/src/collections/_documentation/platforms/rust/actix.md new file mode 100644 index 0000000000000..8e4afbb9089d4 --- /dev/null +++ b/src/collections/_documentation/platforms/rust/actix.md @@ -0,0 +1,83 @@ +--- +title: actix-web +sidebar_order: 2 +--- + +*Crate: `sentry-actix` (has to be installed separately)* + +The `sentry-actix` *crate* adds a middleware for +[`actix-web`](https://actix.rs/) that captures errors and report them to +`Sentry`. + +To use this middleware just configure Sentry and then add it to your actix web +app as a middleware. Because actix is generally working with non sendable +objects and highly concurrent this middleware creates a new hub per request. +As a result many of the sentry integrations such as breadcrumbs do not work +unless you bind the actix hub. + +## Example + +In your `Cargo.toml`: + +```toml +[dependencies] +sentry = "{% sdk_version sentry.rust %}" +sentry-actix = "{% package_version cargo:sentry-actix %}" +``` + +And your Rust code: + +```rust +extern crate actix_web; +extern crate sentry; +extern crate sentry_actix; + +use std::env; +use std::io; + +use actix_web::{server, App, Error, HttpRequest}; +use sentry_actix::SentryMiddleware; + +fn failing(_req: &HttpRequest) -> Result { + Err(io::Error::new(io::ErrorKind::Other, "An error happens here").into()) +} + +fn main() { + let _guard = sentry::init("___PUBLIC_DSN___"); + env::set_var("RUST_BACKTRACE", "1"); + sentry::integrations::panic::register_panic_handler(); + + server::new(|| { + App::new() + .middleware(SentryMiddleware::new()) + .resource("/", |r| r.f(failing)) + }).bind("127.0.0.1:3001") + .unwrap() + .run(); +} +``` + +## Reusing the Hub + +If you use this integration the `Hub::current()` returned hub is typically the wrong one. +To get the request specific one you need to use the `ActixWebHubExt` trait: + +```rust +use sentry::{Hub, Level}; +use sentry_actix::ActixWebHubExt; + +let hub = Hub::from_request(req); +hub.capture_message("Something is not well", Level::Warning); +``` + +The hub can also be made current: + +```rust +use sentry::{Hub, Level}; +use sentry_actix::ActixWebHubExt; + +let hub = Hub::from_request(req); +Hub::run(hub, || { + sentry::capture_message("Something is not well", Level::Warning); +}); +``` diff --git a/src/collections/_documentation/platforms/rust/env_logger.md b/src/collections/_documentation/platforms/rust/env_logger.md new file mode 100644 index 0000000000000..03007e17a3e04 --- /dev/null +++ b/src/collections/_documentation/platforms/rust/env_logger.md @@ -0,0 +1,27 @@ +--- +title: env-logger +sidebar_order: 2 +--- + +*Feature: `with_env_logger` (enabled by default)* + +Adds support for automatic breadcrumb capturing from logs with `env_logger`. + +## Configuration + +In the most trivial version you call this crate's init function instead of the +one from `env_logger` and pass `None` as logger: + +```rust +sentry::integrations::env_logger::init(None, Default::default()); +``` + +This parses the default `RUST_LOG` environment variable and configures both +`env_logger` and this crate appropriately. If you want to create your own +logger you can forward it accordingly: + +```rust +let mut log_builder = pretty_env_logger::formatted_builder().unwrap(); +log_builder.parse("info,foo=debug"); +sentry::integrations::env_logger::init(Some(log_builder.build()), Default::default()); +``` diff --git a/src/collections/_documentation/platforms/rust/error_chain.md b/src/collections/_documentation/platforms/rust/error_chain.md new file mode 100644 index 0000000000000..de995df635fe5 --- /dev/null +++ b/src/collections/_documentation/platforms/rust/error_chain.md @@ -0,0 +1,33 @@ +-- +title: error-chain +sidebar_order: 2 +-- + +*Feature: `with_error_chain` (disabled by default)* + +Adds support for the error-chain crate. + +Errors created by the `error-chain` crate can be logged with the +`error_chain` integration. + +## Example + +In your `Cargo.toml`: + +``` +[dependencies] +sentry = { version = "{% sdk_version sentry.rust %}", features = ["with_error_chain"] } +``` + +And your Rust code: + +```rust +use sentry::integrations::error_chain::capture_error_chain; +let result = match function_that_might_fail() { + Ok(result) => result, + Err(err) => { + capture_error_chain(&err); + return Err(err); + } +}; +``` diff --git a/src/collections/_documentation/platforms/rust/failure.md b/src/collections/_documentation/platforms/rust/failure.md new file mode 100644 index 0000000000000..9dbcf7f10fc78 --- /dev/null +++ b/src/collections/_documentation/platforms/rust/failure.md @@ -0,0 +1,29 @@ +--- +title: failure +sidebar_order: 2 +--- + +*Feature: `with_failure` (enabled by default)* + +Adds support for the failure crate. + +Failure errors and `Fail` objects can be logged with the failure integration. +This works really well if you use the `failure::Error` type or if you have +`failure::Fail` objects that use the failure context internally to gain a +backtrace. + +## Example + +```rust +use sentry::integrations::failure::capture_error; + +let result = match function_that_might_fail() { + Ok(result) => result, + Err(err) => { + capture_error(&err); + return Err(err); + } +}; +``` + +To capture fails and not errors use `capture_fail`. diff --git a/src/collections/_documentation/platforms/rust/index.md b/src/collections/_documentation/platforms/rust/index.md new file mode 100644 index 0000000000000..57b2af926d9fe --- /dev/null +++ b/src/collections/_documentation/platforms/rust/index.md @@ -0,0 +1,50 @@ +--- +title: Rust +sidebar_order: 15 +--- + +{% include learn-sdk.md platform="rust" %} + +Sentry-Rust is the official Rust SDK for Sentry. It maps the entire Sentry +protocol for Rust and provides convenient helpers for sending common types of +events to Sentry. + +The Rust SDK follows the new unified SDK architecture. To get started have a +look at the [quickstart]({% link _documentation/learn/quickstart.md +%}?platform=rust) docs. + +## Integrations + +*Integrations* extend the functionality of the SDK for some common frameworks +and libraries. + +### Framework integrations + +Sentry-Rust supports the following application frameworks: + +* [actix-web]({% link _documentation/platforms/rust/actix.md %}) + +### Error handling integrations + +Sentry-Rust supports the most commonly used libraries for advanced error management: + +* [failure]({% link _documentation/platforms/rust/failure.md %}) +* [error-chain]({% link _documentation/platforms/rust/error_chain.md %}) + +Additionally you can catch panics using the panic integration: + +* [panic]({% link _documentation/platforms/rust/panic.md %}) + +### Logging integrations + +Logs can be automatically converted into breadcrumbs. + +* [env_logger]({% link _documentation/platforms/rust/env_logger.md %}) +* [log]({% link _documentation/platforms/rust/log.md %}) + +## More Information + +- [API Docs](http://docs.rs/sentry) +- [Crates.io page](http://crates.io/crates/sentry) +- [Bug Tracker](http://github.com/getsentry/sentry-rust/issues) +- [Github Project](http://github.com/getsentry/sentry-rust) diff --git a/src/collections/_documentation/platforms/rust/log.md b/src/collections/_documentation/platforms/rust/log.md new file mode 100644 index 0000000000000..816422d179ebb --- /dev/null +++ b/src/collections/_documentation/platforms/rust/log.md @@ -0,0 +1,34 @@ +--- +title: log +sidebar_order: 2 +--- + +*Feature: `with_log` (enabled by default)* + +Adds support for automatic breadcrumb capturing from logs. + +The `log` crate is supported in two ways. First events can be captured as +breadcrumbs for later, secondly error events can be logged as events to Sentry. +By default anything above `Info` is recorded as breadcrumb and anything above +`Error` is captured as error event. + +## Configuration + +However due to how log systems in Rust work this currently requires you to +slightly change your log setup. This is an example with the pretty env logger +crate: + +```rust +let mut log_builder = pretty_env_logger::formatted_builder().unwrap(); +log_builder.parse("info"); // or env::var("RUST_LOG") +let logger = log_builder.build(); +let options = sentry::integrations::log::LoggerOptions { + global_filter: Some(logger.filter()), + ..Default::default() +}; +sentry::integrations::log::init(Some(Box::new(logger)), options); +``` + +For loggers based on `env_logger` (like `pretty_env_logger`) you can also use +the [`env_logger`](../env_logger/index.html) integration which is much easier +to use. diff --git a/src/collections/_documentation/platforms/rust/panic.md b/src/collections/_documentation/platforms/rust/panic.md new file mode 100644 index 0000000000000..5bea9a80a6452 --- /dev/null +++ b/src/collections/_documentation/platforms/rust/panic.md @@ -0,0 +1,18 @@ +--- +title: Handling panics +sidebar_order: 2 +--- + +*Feature: `with_panic` (enabled by default)* + +A panic handler can be installed that will automatically dispatch all errors to +Sentry that are caused by a panic. + +## Configuration + +```rust +use sentry::integrations::panic::register_panic_handler; +register_panic_handler(); +``` + +Additionally panics are forwarded to the previously registered panic hook. diff --git a/src/collections/_documentation/learn/data-forwarding.md b/src/collections/_documentation/product/data-forwarding.md similarity index 100% rename from src/collections/_documentation/learn/data-forwarding.md rename to src/collections/_documentation/product/data-forwarding.md diff --git a/src/collections/_documentation/learn/issue-owners.md b/src/collections/_documentation/product/issue-owners.md similarity index 100% rename from src/collections/_documentation/learn/issue-owners.md rename to src/collections/_documentation/product/issue-owners.md diff --git a/src/collections/_documentation/learn/membership.md b/src/collections/_documentation/product/membership.md similarity index 100% rename from src/collections/_documentation/learn/membership.md rename to src/collections/_documentation/product/membership.md diff --git a/src/collections/_documentation/learn/notifications.md b/src/collections/_documentation/product/notifications.md similarity index 100% rename from src/collections/_documentation/learn/notifications.md rename to src/collections/_documentation/product/notifications.md diff --git a/src/collections/_documentation/learn/pricing.md b/src/collections/_documentation/product/pricing.md similarity index 95% rename from src/collections/_documentation/learn/pricing.md rename to src/collections/_documentation/product/pricing.md index 3bb931998327e..3a44134095808 100644 --- a/src/collections/_documentation/learn/pricing.md +++ b/src/collections/_documentation/product/pricing.md @@ -1,6 +1,6 @@ --- title: Pricing -sidebar_order: 1 +sidebar_order: 30 permalink: /pricing/ --- @@ -57,7 +57,7 @@ Large and Enterprise plans have the option to configure rate limits for each pro If your projects have a high volume of events, you can control how many errors Sentry receives in a few ways: - Within the SDK you can reduce the data volume you’re sending by sampling. -- Turn on [Inbound Filters]({%- link _documentation/learn/quotas.md -%}#inbound-data-filters) for legacy browsers, browser extensions, localhost, and web crawlers. Any filtered events will not count towards your quota. +- Turn on [Inbound Filters]({%- link _documentation/product/quotas.md -%}#inbound-data-filters) for legacy browsers, browser extensions, localhost, and web crawlers. Any filtered events will not count towards your quota. - For JavaScript projects, use _whitelistUrls_ and _ignoreErrors_ - With the Large and Enterprise plans, you’ll be able to set a per-key rate limit for each DSN key in a project at **[Organization] » [Project] » Project Settings » Client Keys (DSN) » Details**. This rate limit is set as number of events to accept during a specific time window (1 minute, 24 hours, etc). diff --git a/src/collections/_documentation/learn/quotas.md b/src/collections/_documentation/product/quotas.md similarity index 100% rename from src/collections/_documentation/learn/quotas.md rename to src/collections/_documentation/product/quotas.md diff --git a/src/collections/_documentation/learn/search.md b/src/collections/_documentation/product/search.md similarity index 100% rename from src/collections/_documentation/learn/search.md rename to src/collections/_documentation/product/search.md diff --git a/src/collections/_documentation/learn/sso.md b/src/collections/_documentation/product/sso.md similarity index 100% rename from src/collections/_documentation/learn/sso.md rename to src/collections/_documentation/product/sso.md diff --git a/src/collections/_documentation/relay/index.md b/src/collections/_documentation/relay/index.md new file mode 100644 index 0000000000000..130705b134af2 --- /dev/null +++ b/src/collections/_documentation/relay/index.md @@ -0,0 +1,15 @@ +--- +title: 'Relay' +sidebar_order: 6 +--- + +Relay is a proxy application you can set up on-premise in front of Sentry that +allows you to modify or drop events, rate-limit clients or queue events in case +of network failures. It is supposed to combine some of the benefits of on-premise +hosting (control over data) with the benefits of SaaS (less administrational +effort). + +- [Getting Started]({%- link _documentation/relay/quickstart.md -%}) +- [Configuration]({%- link _documentation/relay/options.md -%}) +- [Project Configuration]({%- link _documentation/relay/project-config.md -%}) +- [PII Configuration]({%- link _documentation/relay/pii-config/index.md -%}) diff --git a/src/collections/_documentation/relay/options.md b/src/collections/_documentation/relay/options.md new file mode 100644 index 0000000000000..18a3ae22c579f --- /dev/null +++ b/src/collections/_documentation/relay/options.md @@ -0,0 +1,241 @@ +--- +title: 'Configuration Options' +sidebar_order: 2 +--- + +The base configuration for Relay lives in the file `.semaphore/config.yml`. All keys are `snake_case`. + +## Relay + +General relay settings. + +{:.config-key} +### relay.upstream + +*string, default: `https://ingest.sentry.io`* + +The upstream relay or sentry instance. + +It is not a good idea to set this to a value that will make the relay send errors to itself. + +{:.config-key} +### relay.host + +*string, default: `127.0.0.1`* + +The host the relay should bind to (network interface). Example: `0.0.0.0` + +{:.config-key} +### relay.port + +*integer, default: `3000`* + +The port to bind for the unencrypted relay HTTP server. Example: `3000` + +{:.config-key} +### relay.tls_port + +*integer, optional* + +Optional port to bind for the encrypted relay HTTPS server. Example: `3001` + +This is in addition to the `port` option: If you set up a HTTPS server at +`tls_port`, the HTTP server at `port` still exists. + +{:.config-key} +### relay.tls_identity_path + +*string, optional* + +The filesystem path to the identity (DER-encoded PKCS12) to use for the HTTPS +server. Example: `relay_dev.pfx` + +{:.config-key} +### relay.tls_identity_password + +*string, optional* + +Password for the PKCS12 archive in `tls_identity_path`. + +## HTTP + +Set various network-related settings. + +{:.config-key} +### http.timeout + +*integer, default: `5`* + +Timeout for upstream requests in seconds. + +{:.config-key} +### http.max_retry_interval + +*integer, default: `60`* + +Maximum interval between failed request retries in seconds. + +## Caching + +Fine-tune caching of project state. + +{:.config-key} +### cache.project_expiry + +*integer, default: `300` (5 minutes)* + +The cache timeout for project configurations in seconds. Irrelevant if you use +the "simple proxy mode", where your project config is stored in a local file. + +{:.config-key} +### cache.relay_expiry + +*integer, default: `3600` (1 hour)* + +The cache timeout for downstream relay info (public keys) in seconds. + +{:.config-key} +### cache.event_expiry + +*integer, default: `600` (10 minutes)* + +The cache timeout for events (store) before dropping them. + +{:.config-key} +### cache.miss_expiry + +*integer, default: `60` (1 minute)* + +The cache timeout for non-existing entries. + +{:.config-key} +### cache.batch_interval + +*integer, default: `100` (100 milliseconds)* + +The buffer timeout for batched queries before sending them upstream **in milliseconds**. + +{:.config-key} +### cache.file_interval + +*integer, default: `10` (10 seconds)* + +Interval for watching local cache override files in seconds. + +## Size Limits + +Controls various HTTP-related limits. All values are human-readable strings of a number and a human-readable unit, such as: + +- `1KiB` +- `1MB` +- `1MiB` +- `1MiB` +- `1025B` + +{:.config-key} +### limits.max_event_payload_size + +*string, default: `256KB`* + +The maximum payload size for events. + +{:.config-key} +### limits.max_api_payload_size + +*string, default: `20MB`* + +The maximum payload size for general API requests. + +{:.config-key} +### limits.max_api_file_upload_size + +*string, default: `40MB`* + +The maximum payload size for file uploads and chunks. + +{:.config-key} +### limits.max_api_chunk_upload_size + +*string, default: `100MB`* + +The maximum payload size for chunks + +{:.config-key} +## Logging + +{:.config-key} +### logging.level + +*string, default: `info`* + +The log level for the relay. One of: + +- `off` +- `error` +- `warn` +- `info` +- `debug` +- `trace` + +{:.config-key} +### logging.log_failed_payloads + +*boolean, default: `false`* + +If set to true this emits log messages for failed event payloads. + +{:.config-key} +### logging.format + +*string, default: `auto`* + +Controls the log format. One of: + +- `auto`: Auto detect (pretty for tty, simplified for other) +- `pretty`: With colors +- `simplified`: Simplified log output +- `json`: Dump out JSON lines + +{:.config-key} +### logging.enable_backtraces + +*boolean, default: `true`* + +When set to true, backtraces are forced on. + +{:.config-key} +## Statsd Metrics + +{:.config-key} +### metrics.statsd + +*string, optional* + +If set to a host/port string then metrics will be reported to this statsd +instance. + +{:.config-key} +### metrics.prefix + +*string, default: `sentry.relay`* + +The prefix that should be added to all metrics. + +{:.config-key} +## Internal Error Reporting + +{:.config-key} +### sentry.enabled + +*boolean, default: `false`* + +Whether to report internal errors to a separate DSN. `false` means no internal errors are sent (just logged). + +{:.config-key} +### sentry.dsn + +*string, optional* + +DSN to report internal relay failures to. + +It is not a good idea to set this to a value that will make the relay send errors to itself. Ideally this should just send errors to Sentry directly, not another relay. diff --git a/src/collections/_documentation/relay/pii-config/index.md b/src/collections/_documentation/relay/pii-config/index.md new file mode 100644 index 0000000000000..49bb50cdbed04 --- /dev/null +++ b/src/collections/_documentation/relay/pii-config/index.md @@ -0,0 +1,59 @@ +--- +title: 'PII Configuration' +sidebar_order: 4 +--- + +The following document explores the syntax and semantics of PII configs for Relay. To get started with PII configs, it's recommended to use [_Piinguin_](https://getsentry.github.io/piinguin) and refer back to this document when needed. + +## A basic example + +Say you have an exception message which, unfortunately, contains IP addresses which are not supposed to be there. You'd write: + +```json +{ + "applications": { + "freeform": ["@ip:replace"] + } +} +``` + +It reads as "apply rule `@ip:replace` to all fields of kind `freeform`". + +## PII kinds + +Almost every field in an event has an assigned *PII kind*. The following PII kinds exist: + +- `freeform`: Arbitrary text. That might for example be the `message` field of a log entry, or an exception value/message. +- `ip`: Fields containing IP addresses. +- `id`: A user ID, device ID, device ID or similar. +- `username`: A username. +- `hostname`: A hostname. +- `sensitive`: Passwords, secret tokens. +- `email`: An email address. +- `databag`: Local variables in stacktraces, custom data in `extra`. + +Note that PII kinds always match on _location_, not on _content_. For example, +the `email` PII kind really only matches on JSON keys where emails are +suspected to be. + +## Rules + +PII kinds don't employ any kind of pattern matching. That's where PII _rules_ +come in. The following rules exist by default: + +- `@ip:replace` and `@ip:hash` for pattern-matching IP addresses +- `@imei:replace` and `@imei:hash` for pattern-matching IMEIs +- `@mac:replace`, `@mac:mask` and `@mac:hash` for pattern-matching MAC addresses +- `@email:mask`, `@email:replace` and `@email:hash` for pattern-matching email addresses +- `@creditcard:mask`, `@creditcard:replace` and `@creditcard:hash` for pattern-matching creditcard numbers +- `@userpath:replace` and `@userpath:hash` for pattern-matching local paths (e.g. `C:/Users/foo/`) +- `@password:remove` for pattern matching passwords. In this case we're pattern matching against the field's key, whether it contains `password`, `credentials` or similar strings. + +### Writing your own rules + +Rules generally consist of two parts: + +- *Rule types* describe what to match. See [_PII Rule Types_]({%- link _documentation/relay/pii-config/types.md -%}) for an exhaustive list. +- *Rule redaction methods* describe what to do with the match. See [_PII Rule Redaction Methods_]({%- link _documentation/relay/pii-config/methods.md -%}) for a list. + +Each page comes with examples. Try those examples out by pasting them into the "PII config" column of [_Piinguin_](https://getsentry.github.io/piinguin) and clicking on fields to get suggestions. diff --git a/src/collections/_documentation/relay/pii-config/methods.md b/src/collections/_documentation/relay/pii-config/methods.md new file mode 100644 index 0000000000000..70d1fd7db77c8 --- /dev/null +++ b/src/collections/_documentation/relay/pii-config/methods.md @@ -0,0 +1,97 @@ +--- +title: 'PII Rule Redaction Methods' +sidebar_order: 6 +--- + +{:.config-key} +#### remove + +Remove the entire field. Relay may choose to either set it to `null` or to remove it entirely. + +```json +{ + "rules": { + "remove_ip": { + "type": "ip", + "redaction": { + "method": "remove" + } + } + }, + "applications": { + "freeform": ["remove_ip"] + } +} +``` + +{:.config-key} +#### replace + +Replace the key with a static string. + +```json +{ + "rules": { + "replace_ip": { + "type": "ip", + "redaction": { + "method": "replace", + "text": "[censored]" + } + } + }, + "applications": { + "freeform": ["replace_ip"] + } +} +``` + +{:.config-key} +#### mask + +Replace every character of the matched string with a "masking" char. Compared to `replace` this preserves the length of the original string. + +```javascript +{ + "rules": { + "mask_ip": { + "type": "ip", + "redaction": { + "method": "mask", + "mask_char": "0", // The character used for masking. Optional, default "*" + "chars_to_ignore": ".", // Which characters to ignore. Optional, default empty + "range": [0, -1] // Which range of the string to replace. Optional, defaults to full range. Negative indices count from the matches' end. + } + } + }, + "applications": { + "freeform": ["mask_ip"] + } +} +``` + +{:.config-key} +#### hash + +Replace the string with a hashed version of itself. Equal strings will produce the same hash, so if you, for example, decide to hash the user ID instead of replacing or removing it, you will still have an accurate count of users affected. + +```javascript +{ + "rules": { + "hash_ip": { + "type": "ip", + "redaction": { + "method": "hash", + "algorithm": "HMAC-SHA1", // One of "HMAC-SHA1", "HMAC-SHA256", "HMAC-SHA512" + "key": "myOverriddenKey" // A key to salt the hash with. Defaults to the default key set in "vars" + } + } + }, + "vars": { + "hashKey": "myDefaultKey" // The default key to use + } + "applications": { + "freeform": ["mask_ip"] + } +} +``` diff --git a/src/collections/_documentation/relay/pii-config/types.md b/src/collections/_documentation/relay/pii-config/types.md new file mode 100644 index 0000000000000..9821951af4e36 --- /dev/null +++ b/src/collections/_documentation/relay/pii-config/types.md @@ -0,0 +1,224 @@ +--- +title: 'PII Rule Types' +sidebar_order: 5 +--- + +{:.config-key} +#### pattern + +Custom Perl-style regex (PCRE). + +```json +{ + "rules": { + "hash_device_id": { + "type": "pattern", + "pattern": "d/[a-f0-9]{12}", + "redaction": { + "method": "hash" + } + } + }, + "applications": { + "freeform": ["hash_device_id"] + } +} +``` + +{:.config-key} +#### imei + +Matches an IMEI or IMEISV. + +```json +{ + "rules": { + "hash_imei": { + "type": "imei", + "redaction": { + "method": "hash" + } + } + }, + "applications": { + "freeform": ["hash_imei"] + } +} +``` + +{:.config-key} +#### mac + +Matches a MAC address. + +```json +{ + "rules": { + "hash_mac": { + "type": "mac", + "redaction": { + "method": "hash" + } + } + }, + "applications": { + "freeform": ["hash_mac"] + } +} +``` + +{:.config-key} +#### ip + +Matches any IP address. + +```json +{ + "rules": { + "hash_ip": { + "type": "ip", + "redaction": { + "method": "hash" + } + } + }, + "applications": { + "freeform": ["hash_ip"] + } +} +``` + +{:.config-key} +#### creditcard + +Matches a creditcard number. + +```json +{ + "rules": { + "hash_cc": { + "type": "creditcard", + "redaction": { + "method": "hash" + } + } + }, + "applications": { + "freeform": ["hash_cc"] + } +} +``` + +{:.config-key} +#### userpath + +Matches a local path (e.g. `C:/Users/foo/`). + +```json +{ + "rules": { + "hash_userpath": { + "type": "userpath", + "redaction": { + "method": "hash" + } + } + }, + "applications": { + "freeform": ["hash_userpath"] + } +} +``` + +{:.config-key} +#### anything + +Matches any value. This is basically equivalent to a wildcard regex. + +For example, to remove all data with the PII kind `freeform`: + +```json +{ + "rules": { + "remove_everything": { + "type": "anything", + "redaction": { + "method": "remove" + } + } + }, + "applications": { + "freeform": ["remove_everything"] + } +} +``` + +{:.config-key} +#### multiple + +Combine multiple rules into one. This is a disjunction (OR): The field in question has to match only one of the rules to match the combined rule, not all of them. + +```javascript +{ + "rules": { + "remove_ips_and_macs": { + "type": "multiple", + "rules": [ + "@ip", + "@mac" + ], + "hide_rule": false, // Hide the inner rules when showing which rules have been applied. Defaults to false. + "redaction": { + "method": "remove" + } + } + }, + "applications": { + "freeform": ["remove_ips_and_macs"] + } +} +``` + +{:.config-key} +#### alias + +Alias one rule to the other. This is the same as `multiple` except that you can only wrap one rule. + +```javascript +{ + "rules": { + "remove_ips": { + "type": "multiple", + "rule": "@ip", + "hide_rule": false, // Hide the inner rule when showing which rules have been applied. Defaults to false. + "redaction": { + "method": "remove" + } + } + }, + "applications": { + "freeform": ["remove_ips"] + } +} +``` + +{:.config-key} +#### redactPair + +Apply a regex to the key name. The value matches if the key matches the given regex. This is useful for removing tokens and keys, since those are usually completely random. + +```json +{ + "applications": { + "freeform": [ + "remove_all_passwords" + ] + }, + "rules": { + "remove_all_passwords": { + "keyPattern": "(password|token|credentials)", + "type": "redactPair" + } + } +} +``` diff --git a/src/collections/_documentation/relay/project-config.md b/src/collections/_documentation/relay/project-config.md new file mode 100644 index 0000000000000..cded3477a703b --- /dev/null +++ b/src/collections/_documentation/relay/project-config.md @@ -0,0 +1,46 @@ +--- +title: 'Project Configuration' +sidebar_order: 3 +--- + +A Relay will generally not accept or forward events where it doesn't know the project. See [_Getting Started_]({%- link _documentation/relay/quickstart.md -%}) for a short introduction to project configs. This page enumerates all possible options. + +The configuration for a project with the ID `123` lives in the file `.semaphore/projects/123.json`. You can get the project ID from the path section of a DSN. + +All config keys in a project config are `camelCase`. + +{:.config-key} +## disabled + +*boolean, default: `false`* + +Whether the project is disabled. If set to `true`, the Relay will drop all events sent to this project. + +{:.config-key} +## publicKeys + +*map from string to boolean, default: `{}`* + +A map enumerating known public keys (the public key in a DSN) and whether events using that key should be accepted. Example: + +```json +{ + "publicKeys": { + "___PUBLIC_KEY___": true + } +} +``` + +{:.config-key} +## config.allowedDomains + +*array of origins (strings), default: `[]`* + +Configure origin URLs which Sentry should accept events from. + +This is basically the same as the "Allowed Domains" setting in the Sentry UI. + +{:.config-key} +## config.piiConfig + +See [_PII Configuration_]({%- link _documentation/relay/pii-config/index.md -%}). diff --git a/src/collections/_documentation/relay/quickstart.md b/src/collections/_documentation/relay/quickstart.md new file mode 100644 index 0000000000000..bbff9715d09f5 --- /dev/null +++ b/src/collections/_documentation/relay/quickstart.md @@ -0,0 +1,121 @@ +--- +title: 'Getting started' +sidebar_order: 1 +--- + +The relay server is called "semaphore". Binaries can be downloaded from the +[GitHub releases page](https://github.com/getsentry/semaphore/releases). After +downloading place the binary somewhere on your `PATH` and make it executable. + +The `config init` command is provided to initialize the initial config. The +config will be created the folder it's run from in a hidden `.semaphore` +subdirectory: + + $ semaphore config init + +The wizard will ask a few questions: + +1. default vs custom config. In the default config the relay will connect to + sentry.io for sending and will generally use the defaults. In the custom + config a different upstream can be configured. +2. Relay internal crash reporting can be enabled or disabled. When enabled the + relay will report its own internal errors to sentry.io to help us debug it. +3. Lastly the relay will ask it should run authenticated with credentials or + not. Currently we do not yet support authenticated mode against sentry.io. + +You now have a folder named `.semaphore` in your current working directory. To +launch the server, run: + + semaphore run + +If you moved your config folder somewhere else, you can use the `-c` option: + + semaphore run -c ./my/custom/semaphore_folder/ + +## Setting up a Project + +Right now Relay is only really usable in "simple proxy mode" (without +credentials), and as such calls the same exact endpoints on Sentry that an SDK +would. That also means you have to configure each project individually in +Relay. + +Create a new file in the form `project_id.json`: + +``` +.semaphore/project/___PROJECT_ID___.json +``` + +With the following content: + +```json +{ + "allowedDomains": ["*"], + "trustedRelays": [], + "publicKeys": ["___PUBLIC_KEY___"], + "config": { + "piiConfig": {} + } +} +``` + +The relay has to know all public keys (i.e. the secret part of the DSN) that +will send events to it. DSNs unknown for this project will be rejected. + +## Sending a Test Event + +Launch the server with `semaphore run`, and set up any SDK with the following DSN: + +``` +http://___PUBLIC_KEY___@127.0.0.1:3000/___PROJECT_ID___ +``` + +As you can see we only changed the host and port of the DSN to point to your +Relay setup. You should be able to use the SDK normally at this point. Events +arrive at the Sentry instance that Relay is configured to use in +`.semaphore/config.yml`. + +## PII Stripping + +Now let's get to the entire point of this proxy setup: Stripping sensitive +data. + +The easiest way to go about this is if you already have a raw JSON payload from some SDK. Go to our PII config editor [Piinguin](https://getsentry.github.io/piinguin/), and: + +1. Paste in a raw event +2. Click on data you want eliminated +3. Paste in other payloads and see if they look fine, go to step **2** if necessary. + +After iterating on the config, paste it back into the project config you created earlier: + +``` +.semaphore/project/___PROJECT_ID___.json +``` + + +For example: + +```json +{ + "publicKeys": { + "___PUBLIC_KEY___": true + }, + "config": { + "allowedDomains": ["*"], + "trustedRelays": [], + "piiConfig": { + "rules": { + "device_id": { + "type": "pattern", + "pattern": "d/[a-f0-9]{12}", + "redaction": { + "method": "hash" + } + } + }, + "applications": { + "freeform": ["device_id"] + } + } + } +} +``` diff --git a/src/index.md b/src/index.md index 45b40ad2248df..a24715ea261fb 100644 --- a/src/index.md +++ b/src/index.md @@ -2,6 +2,12 @@ title: 'Sentry Documentation' --- +
      + {% asset on-fire.png %} +
      + +Welcome to the Sentry documentation. Sentry is an Open-source error tracking that helps you monitor and fix crashes in real time. Here we cover everything about the product and the platform integrations and our on-prem offering. + ## Getting Started To get you started, you might find some of these links relevant: @@ -11,12 +17,7 @@ To get you started, you might find some of these links relevant: - Stuck? Feel free to contact [_Support_]({%- link support.md -%}). - Installing the Sentry server yourself? See [_Installation_]({%- link _documentation/server/installation/index.md -%}) -## Platforms - -To report to Sentry you’ll need to use a language-specific SDK. The Sentry team builds and maintains these for most popular languages, but there’s also a large ecosystem supported by the community. If your favorite language isn’t listed below, we encourage you to start a discussion about supporting it on our [community forum](https://forum.sentry.io). - -{% include LEGACY_platform_icon_links.html %} - ## Contributing -Looking to get started contributing to Sentry? Our [_internal documentation_]({%- link _documentation/internal/index.md -%}) has you covered. +Looking to get started contributing to Sentry? Our [_internal documentation_]({%- link _documentation/internal/index.md -%}) has you covered. Also +have a look at our [_Forums_](https://forums.sentry.io/) and our [_Github org_](https://github.com/getsentry).