A generic Javascript SDK based on Self-Hosted Sentry.
<script type="text/javascript" src="https://unpkg.com/sentry-javascript/dist/index.js"></script>
<script type="text/javascript" src="https://unpkg.com/sentry-javascript@1.0.3/dist/index.js"></script>
npm install sentry-javascript --save
yarn add sentry-javascript
import * as Sentry from 'sentry-javascript'
Sentry.init({
dsn: '_your_sentry_dsn'
})
const Sentry = require('sentry-javascript')
// const Sentry = require('sentry-javascript/cjs')
Sentry.init({
dsn: '_your_sentry_dsn'
})
window.Sentry.init({
dsn: '_your_sentry_dsn'
})
The current operation must be performed after initialization.
Sentry.captureMessage('Something went wrong')
The current operation must be performed after initialization.
try {
/* something to do */
aFunctionThatMightFail()
} catch(e) {
Sentry.captureException(e)
}
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'
})
})
parameter | description | type | required | default value |
---|---|---|---|---|
options | Sentry Initializes the configuration item object of the log. service | object | ✅ | - |
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 my-project-name@1.0.0. | string | ❌ | - |
None
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 | ❌ | - |
Promise<SentrySDKResponse>
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 | ❌ | - |
Promise<SentrySDKResponse>
parameter | description | type | required | default value |
---|---|---|---|---|
callback | Global scope callback function. | funciton | ✅ | - |
None
The following methods are provided.
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: 'john.doe@example.com'
})
})
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')
})
removeTag(key)
parameter | description | type | required | default value |
---|---|---|---|---|
key | Tag name. | string | ✅ | - |
Sentry.configureScope((scope) => {
scope.removeTag('my-tag')
})
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'
})
})
removeExtra(key)
parameter | description | type | required | default value |
---|---|---|---|---|
key | Extra data name. | string | ✅ | - |
Sentry.configureScope((scope) => {
scope.removeExtra('my-extra')
})
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')
})
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"
}
})
})
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()
Sentry.configureScope((scope) => {
// clear the previous scope configuration
scope.clear()
// set new tag
scope.setTag('new-tag', 'new value')
})
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 | ❌ | - |
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 |
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 |
---|---|
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. |
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`
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`
sentry-javascript is MIT licensed.