sentry-javascript v1.0.3

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/sentry-javascript@1.0.3/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: 'john.doe@example.com'
  })
})

Method

Initialization

Sentry.init(options)

options parameter configuration items

Return value

None

Capture message

Sentry.captureMessage(message, options)

Return value

Promise\<SentrySDKResponse>

Capture exception

Sentry.captureException(err, options)

Return value

Promise\<SentrySDKResponse>

Configure scope

Sentry.configureScope(callback)

Return value

None

Description of the global Scope object

The following methods are provided.

Set user information

setUser(options)

Sentry.configureScope((scope) => {
  // clear user information
  scope.setUser(null)
  // set user information
  scope.setUser({
    id: '666',
    email: 'john.doe@example.com'
  })
})

Set tags

setTag(key, value)

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

Remove tag

removeTag(key)

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

Set extra data

setExtra(key, value)

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

Remove extra data

removeExtra(key)

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

Set log level

setLevel(level)

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.

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.

SDK envelope

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

Error Code Description

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.