Configuration
=============

To get started, you need to configure Raven.js to use your Sentry DSN:

.. sourcecode:: javascript

    Raven.config('___PUBLIC_DSN___').install()

At this point, Raven is ready to capture any uncaught exception.

Optional settings
-----------------

``Raven.config()`` can optionally be passed an additional argument for extra configuration:

.. sourcecode:: javascript

    Raven.config('___PUBLIC_DSN___', {
        release: '1.3.0'
    }).install()

Those configuration options are documented below:

.. describe:: logger

    The name of the logger used by Sentry. Default: ``javascript``

    .. code-block:: javascript

        {
          logger: 'javascript'
        }

.. describe:: release

    Track the version of your application in Sentry.

    .. code-block:: javascript

        {
          release: '721e41770371db95eee98ca2707686226b993eda'
        }

    Can also be defined with ``Raven.setRelease('721e41770371db95eee98ca2707686226b993eda')``.

.. describe:: environment

    Track the environment name inside Sentry.

    .. code-block:: javascript

        {
          environment: 'production'
        }

.. describe:: serverName

    .. versionadded:: 1.3.0

    Typically this would be the server name, but that doesn’t exist on
    all platforms. Instead you may use something like the device ID, as it
    indicates the host which the client is running on.

    .. code-block:: javascript

        {
          serverName: device.uuid
        }


.. describe:: tags

    Additional `tags <https://docs.sentry.io/hosted/learn/context/#tagging-events>`__ to assign to each event.

    .. code-block:: javascript

        {
          tags: {git_commit: 'c0deb10c4'}
        }

.. _config-whitelist-urls:

.. describe:: whitelistUrls

    The inverse of ``ignoreUrls``. Only report errors from whole urls
    matching a regex pattern or an exact string. ``whitelistUrls`` should
    match the url of your actual JavaScript files. It should match the url
    of your site if and only if you are inlining code inside ``<script>``
    tags. Not setting this value is equivalent to a catch-all and will not
    filter out any values.

    .. code-block:: javascript

        {
          whitelistUrls: [/getsentry\.com/, /cdn\.getsentry\.com/]
        }

.. describe:: ignoreErrors

    Very often, you will come across specific errors that are a result of
    something other than your application, or errors that you're
    completely not interested in. `ignoreErrors` is a list of these
    messages to be filtered out before being sent to Sentry as either
    regular expressions or strings. When using strings, they'll partially
    match the messages, so if you need to achieve an exact match, use
    RegExp patterns instead.

    .. code-block:: javascript

        {
          ignoreErrors: ['fb_xd_fragment', /^Exact Match Message$/]
        }

.. describe:: ignoreUrls

    The inverse of ``whitelistUrls`` and similar to ``ignoreErrors``, but
    will ignore errors from whole urls matching a regex pattern or an
    exact string.

    .. code-block:: javascript

        {
          ignoreUrls: [/graph\.facebook\.com/, 'http://example.com/script2.js']
        }

.. describe:: includePaths

    An array of regex patterns to indicate which urls are a part of your
    app in the stack trace. All other frames will appear collapsed inside
    Sentry to make it easier to discern between frames that happened in
    your code vs other code. It'd be suggested to add the current page
    url, and the host for your CDN.

    .. code-block:: javascript

        {
            includePaths: [/https?:\/\/getsentry\.com/, /https?:\/\/cdn\.getsentry\.com/]
        }

.. describe:: sampleRate

    A sampling rate to apply to events. A value of 0.0 will send no events,
    and a value of 1.0 will send all events (default).

    .. code-block:: javascript

        {
            sampleRate: 0.5 // send 50% of events, drop the other half
        }

.. describe:: dataCallback

    A function that allows mutation of the data payload right before being
    sent to Sentry.

    .. code-block:: javascript

        {
            dataCallback: function(data) {
              // do something to data
              return data;
            }
        }

.. describe:: breadcrumbCallback

    A function that allows filtering or mutating breadcrumb payloads.
    Return false to throw away the breadcrumb.

    .. code-block:: javascript

        {
            breadcrumbCallback: function(crumb) {
              if (crumb.type === 'http') {
                return crumb;
              }

              return false;
            }
        }

.. describe:: shouldSendCallback

    A callback function that allows you to apply your own filters to
    determine if the message should be sent to Sentry.

    .. code-block:: javascript

        {
            shouldSendCallback: function(data) {
              return false;
            }
        }

.. describe:: maxMessageLength

    By default, Raven does not truncate messages. If you need to truncate
    characters for whatever reason, you may set this to limit the length.

.. describe:: maxUrlLength

    By default, Raven will truncate URLs as they appear in breadcrumbs and other meta
    interfaces to 250 characters in order to minimize bytes over the wire. This does *not*
    affect URLs in stack traces.

.. describe:: autoBreadcrumbs

    Enables/disables automatic collection of breadcrumbs. Possible values are:

    * `true` (default)
    * `false` - all breadcrumb collection disabled
    * A dictionary of individual breadcrumb types that can be enabled/disabled:

    .. code-block:: javascript

        autoBreadcrumbs: {
            'xhr': false,      // XMLHttpRequest
            'console': false,  // console logging
            'dom': true,       // DOM interactions, i.e. clicks/typing
            'location': false  // url changes, including pushState/popState
            'sentry': true     // sentry events
        }

.. describe:: maxBreadcrumbs

    By default, Raven captures as many as 100 breadcrumb entries. If you find this too noisy, you can reduce this
    number by setting `maxBreadcrumbs`. Note that this number cannot be set higher than the default of 100.

.. describe:: transport

    Override the default HTTP data transport handler.

    Alternatively, can be specified using ``Raven.setTransport(myTransportFunction)``.

    .. code-block:: javascript

        {
            transport: function (options) {
                // send data
            }
        }

    The provided function receives a single argument, ``options``, with the following properties:

    url
        The target url where the data is sent.

    data
        The outbound exception data.

        For POST requests, this should be JSON-encoded and set as the
        HTTP body (and transferred as Content-type: application/json).

        For GET requests, this should be JSON-encoded and passed over the
        query string with key ``sentry_data``.

    auth
        An object representing authentication data. This should be converted to urlencoded key/value pairs
        and passed as part of the query string, for both GET and POST requests.

        The auth object has the following properties:

        sentry_version
            The API version of the Sentry server.
        sentry_client
            The name and version of the Sentry client of the form ``client/version``.
            In this case, ``raven-js/${Raven.VERSION}``.
        sentry_key
            Your public client key (DSN).

    options
        Include all top-level options described.

    onSuccess
        Callback to be invoked upon a successful request.

    onError
        Callback to be invoked upon a failed request.

.. describe:: headers

    Pass custom headers to server requests for ``fetch`` or ``XMLHttpRequest``.

    .. code-block:: javascript

        {
            headers: {
                'CSRF-TOKEN': '12345'
            }
        }

    Headers value can be in form of a function, to compute value in time of a request:

    .. code-block:: javascript

        {
            headers: {
                'CSRF-TOKEN': function() {
                    // custom logic that will be computed on every request
                    return new Date();
                }
            }
        }

.. describe:: fetchParameters

    ``fetch()`` init parameters (https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters).

    Defaults:

    .. code-block:: javascript

        {
            method: 'POST',
            keepalive: true,
            referrerPolicy: 'origin'
        }


.. describe:: allowDuplicates

    By default, Raven.js attempts to suppress duplicate captured errors and messages that occur back-to-back. Such events are often triggered by rogue code (e.g. from a `setInterval` callback in a browser extension), are not actionable, and eat up your event quota.

    To disable this behavior (for example, when testing), set ``allowDuplicates: true`` during configuration.

.. describe:: allowSecretKey

    By default, Raven.js will throw an error if configured with a Sentry DSN that contains a secret key.
    When using Raven.js with a web application accessed via a browser over the web, you should
    only use your public DSN. But if you are using Raven.js in an environment like React Native or Electron,
    where your application is running "natively" on a device and not accessed at a web address, you may need
    to use your secret DSN string. To do so, set ``allowSecretKey: true`` during configuration.

.. describe:: debug

    If set to `true`, Raven.js outputs some light debugging information onto the console.


.. describe:: instrument

    Enables/disables instrumentation of globals. Possible values are:

    * `true` (default)
    * `false` - all instrumentation disabled
    * A dictionary of individual instrumentation types that can be enabled/disabled:

    .. code-block:: javascript

        instrument: {
            'tryCatch': true, // Instruments timers and event targets
        }

Putting it all together
-----------------------

.. code-block:: html

    <!doctype html>
    <html>
    <head>
        <title>Awesome stuff happening here</title>
    </head>
    <body>
        ...
        <script src="jquery.min.js"></script>
        <script src="https://cdn.ravenjs.com/###RAVEN_VERSION###/raven.min.js"
            crossorigin="anonymous"></script>
        <script>
            Raven.config('___PUBLIC_DSN___', {
                logger: 'my-logger',
                whitelistUrls: [
                    /disqus\.com/,
                    /getsentry\.com/
                ],
                ignoreErrors: [
                    'fb_xd_fragment',
                    /ReferenceError:.*/
                ],
                includePaths: [
                    /https?:\/\/(www\.)?getsentry\.com/
                ]
            }).install();
        </script>
        <script src="myapp.js"></script>
    </body>
    </html>
