sentry-javascript

A generic Javascript SDK based on Self-Hosted Sentry.

Install

Using unpkg CDN

Use the latest version file

<script type="text/javascript" src="https://unpkg.com/sentry-javascript/dist/index.js"></script>

Use the specified version file (recommended)

<script type="text/javascript" src="https://unpkg.com/[email protected]/dist/index.js"></script>

Using npm

npm install sentry-javascript --save

Using yarn

yarn add sentry-javascript

Usage

Initialization

ESM

import * as Sentry from 'sentry-javascript'

Sentry.init({
  dsn: '_your_sentry_dsn'
})

CommonJS

const Sentry = require('sentry-javascript')
// const Sentry = require('sentry-javascript/cjs')

Sentry.init({
  dsn: '_your_sentry_dsn'
})

Usage of CDN resource

window.Sentry.init({
  dsn: '_your_sentry_dsn'
})

Capture message

The current operation must be performed after initialization.

Sentry.captureMessage('Something went wrong')

Capture exception

The current operation must be performed after initialization.

try {
  /* something to do */
  aFunctionThatMightFail()
} catch(e) {
  Sentry.captureException(e)
}

Configure scope

The current operation must be performed after initialization.

Sentry.configureScope((scope) => {
  // for instance, add custom tags or inform Sentry about the currently authenticated user
  scope.setTag('my-tag', 'my value')
  scope.setUser({
    id: '666',
    email: '[email protected]'
  })
})

Method

Initialization

Sentry.init(options)

| parameter | description | type | required | default value | |---|---|---|---|---| | options | Sentry Initializes the configuration item object of the log. service | object | ✅ | - |

options parameter configuration items

| parameter | description | type | required | default value | |---|---|---|---|---| | dsn | DSN for the Sentry logging service, the DSN tells the SDK where to send the events (available through the configuration backend).| string | ✅ | - | | enabled | Whether to allow data to be reported. | boolean | ❌ | true | | debug | If debugging is enabled, the SDK will attempt to print out useful debugging information if something goes wrong while sending an event. Although enabling debug mode does not cause any security issues, it is usually not recommended to enable debug mode in production environments. | boolean | ❌ | false | | envelope | Whether to use the envelope interface to report data, see Envelopes and Store Endpoint for details. | boolean | ❌ | true | | environment | Environments that send log data, a version can be associated with multiple environments to separate them in the user interface (e.g. staging vs prod or other similar comparisons). | string | ❌ | production | | release | Version number, suggested format [email protected]. | string | ❌ | - |

Return value

None

Capture message

Sentry.captureMessage(message, options)

| parameter | description | type | required | default value | |---|---|---|---|---| | message | Message to be sent. | string | ✅ | - | | options | When passed in as a string, it can only be used as a log level, the available values are fatal | error | warning | info | debug; when passed in as an object, it is used as an optional parameter configuration item, see configuration item description for details. | string/object | ❌ | - |

Return value

Promise<SentrySDKResponse>

Capture exception

Sentry.captureException(err, options)

| parameter | description | type | required | default value | |---|---|---|---|---| | err | Instance of a standard Error, see MDN for details. | object | ✅ | - | | options | An optional parameter configuration item, see configuration item description for details. | object | ❌ | - |

Return value

Promise<SentrySDKResponse>

Configure scope

Sentry.configureScope(callback)

| parameter | description | type | required | default value | |---|---|---|---|---| | callback | Global scope callback function. | funciton | ✅ | - |

Return value

None

Description of the global Scope object

The following methods are provided.

Set user information

setUser(options)

| parameter | description | type | required | default value | |---|---|---|---|---| | options | User information object, see User Definition for details. | object | ✅ | - |

Sentry.configureScope((scope) => {
  // clear user information
  scope.setUser(null)
  // set user information
  scope.setUser({
    id: '666',
    email: '[email protected]'
  })
})

Set tags

setTag(key, value)

| parameter | description | type | required | default value | |---|---|---|---|---| | key | Tag name. | string | ✅ | - | | value | Tag value. | string | ✅ | - |

Sentry.configureScope((scope) => {
  scope.setTag('my-tag', 'my value')
})

Remove tag

removeTag(key)

| parameter | description | type | required | default value | |---|---|---|---|---| | key | Tag name. | string | ✅ | - |

Sentry.configureScope((scope) => {
  scope.removeTag('my-tag')
})

Set extra data

setExtra(key, value)

| parameter | description | type | required | default value | |---|---|---|---|---| | key | Extra data name. | string | ✅ | - | | value | Extra data value. | any | ✅ | - |

Sentry.configureScope((scope) => {
  scope.setExtra('my-extra', {
    'key1': 'value1',
    'key2': 'value2'
  })
})

Remove extra data

removeExtra(key)

| parameter | description | type | required | default value | |---|---|---|---|---| | key | Extra data name. | string | ✅ | - |

Sentry.configureScope((scope) => {
  scope.removeExtra('my-extra')
})

Set log level

setLevel(level)

| parameter | description | type | required | default value | |---|---|---|---|---| | level | Log level, the available values are fatal | error | warning | info | debug | string | ✅ | - |

Sentry.configureScope((scope) => {
  scope.setLevel('debug')
  Sentry.captureMessage('Something went wrong')
})

Add breadcrumb record

addBreadcrumb | parameter | description | type | required | default value | |---|---|---|---|---| | breadcrumb | breadcrumb record | object | ✅ | - |

Sentry.configureScope((scope) => {
  scope.addBreadcrumb({
    "timestamp": "2023-06-19T06:56:32.306Z",
    "message": "Something happened",
    "category": "log",
    "data": {
      "foo": "bar",
      "blub": "blah"
    }
  })
})

Clear breadcrumb records

clearBreadcrumbs

Sentry.configureScope((scope) => {
  // clear the previous scope breadcrumb records
  scope.clearBreadcrumbs()
  // add breadcrumb record
  scope.addBreadcrumb({
    "timestamp": "2023-06-19T06:56:55.266Z",
    "type": "navigation",
    "data": {
      "from": "/login",
      "to": "/dashboard"
    }
  })
})

Clear the global scope configuration

clear()

Sentry.configureScope((scope) => {
  // clear the previous scope configuration
  scope.clear()
  // set new tag
  scope.setTag('new-tag', 'new value')
})

The options of capture methods

This configuration note is only for Sentry.captureMessage and Sentry.captureException.

| parameter | description | type | required | default value | |---|---|---|---|---| | event_id | Hexadecimal string representing a uuid4 value. The length is exactly 32 characters. Dashes are not allowed. Has to be lowercase. | string | ❌ | - | | message | Message to be sent，see Message Definition for details. If this parameter is configured with a legal value, it will take precedence over the message parameter of the Sentry.captureMessage method. | string/object | ❌ | - | | level | Log level, the available values are fatal | error | warning | info | debug. The default value of the Sentry.captureMessage method is info, and the default value of the Sentry.captureException method is error. | string | ❌ | - | | type | Event type for recording errors, see Type Definition for details. | string | ❌ | event | | exception | Specify the exception or error that occurred in the program, see Exception Definition for details. | object | ❌ | - | | request | The Request interface contains information on a HTTP request related to the event. In client SDKs, this can be an outgoing request, or the request that rendered the current web page, see Request Definition for details. | object | ❌ | - | | user | Current authenticated user information, see User Definition for details. | object | ❌ | {ip_address: '{{auto}}'} | | tags | A map or list of tags for this event. Each tag must be less than 200 characters, see Event Payloads for details. | object | ❌ | - | | extra | An arbitrary mapping of additional metadata to store with the event, see Event Payloads for details. | object | ❌ | - | | breadcrumbs | A list of breadcrumb records to describe the track of events，see Breadcrumbs Definition for details. | array | ❌ | - |

Return value description of capture method

Before reading this return value description, you need to understand the predefined SDK envelope.

This return value description is only for results sent successfully using Sentry.captureMessage and Sentry.captureException.

| key | description | type | |---|---|---| | id | Event identifier. | string |

SDK envelope

The predefined SDK envelope is essentially a data of type object, and the following is a description of its structure.

| key | description | type | default value | |---|---|---|---| | code | Error code. | number | - | | data | Communication data, any meaningful data will be given in this field. | object | null | | message | Tip message | string | - |

Error Code Description

| error code | description | |---|---| | 0 | Success | | 400 | Bad request. Usually it is some call and passed parameter error that causes. | | 413 | Request content too large. For example, if the data sent is too large, the current SDK limits it to a maximum of 20MB. | | 429 | Too many requests. It is usually the service itself that responds because the concurrent load is too high. | | 500 | Network errors. Usually some network connection problems, such as request timeouts. | | 10001 | The current SDK is set to disable sending data. |

How to open the envelope properly to get the data

This is a demo to get the event id.

import * as Sentry from 'sentry-javascript'

const getEventId = async () => {
  const res = await Sentry.captureMessage('Something went wrong')
  let eventId = ''
  if (res.code === 0 && res.data && res.data.id) {
    eventId = res.data.id
  }
  return eventId
}
const eventId = await getEventId()
console.log('current event id is: ' + eventId)
// output `current event id is: xxxxxxxx`

TypeScript Support

The module naturally supports TypeScript, and here is a demo.

import * as Sentry from 'sentry-javascript'
import type { SentrySDKResponse } from 'sentry-javascript'

const getCaptureStatus = async (): Promise<string> => {
  const res: SentrySDKResponse = await Sentry.captureMessage('Something went wrong')
  let status = 'fail'
  if (res.code === 0 && res.data && res.data.id) {
    status = 'success'
  }
  return status
}
const status = await getCaptureStatus()
console.log('current data capture is ' + status)
// output `current data capture is success`

License

sentry-javascript is MIT licensed.