Explore documentation
  1. Welcome to Errors
    1. JavaScript tag
      1. Install the JavaScript tag
      2. Configure the JavaScript tag
      3. JavaScript tag events
  2. Collecting errors
    1. Integrating using an AI prompt
    2. Sentry SDK
  3. Using the product
    1. Exception grouping
    2. AI prompt
    3. Releases
    4. Uploading source maps
    5. Spike protection
  4. Integrations
    1. Reporting incidents
    2. Slack
    3. Microsoft Teams
    4. Linear
    5. Jira
    6. GitHub
    7. Outgoing webhooks
  5. Errors API
    1. Getting an API token
    2. Applications API
    3. Application groups API

Install the JavaScript tag

This page covers everything you need to add to your application code. All other settings are managed remotely from the Better Stack UI, see Configuration.

Install the snippet

Navigate to your application's Frontend tab and copy the <script> tag. Place it before the closing </head> tag on every page you want to instrument:

Install JavaScript tag
<script>
  !function(b,e,t,r){
    b[t]=b[t]||function(...args){(b[t].q=b[t].q||[]).push(args)};
    b[t].l=+new Date;
    var s=e.createElement('script'); s.async=1; s.crossOrigin='anonymous';
    s.src='https://betterstack.net/b.js?t='+r;
    (e.head||e.getElementsByTagName('head')[0]).appendChild(s);
  }(window,document,'betterstack','$APPLICATION_TOKEN');
  betterstack('init', { environment: 'production' });
</script>


The snippet loads asynchronously and won't block page rendering. You never need to update it, as the remote script (b.js) is always generated with your latest configuration.

Don't run a standalone Sentry SDK on the same page as the JavaScript tag

The JavaScript tag uses Sentry's browser SDK internally. If your site also loads its own Sentry SDK, both run on the same shared global Sentry instance and may interfere with each other, producing corrupted or unreliable data on both sides. Remove previous Sentry SDK instances before installing the JavaScript tag.

Initialize

The betterstack('init', opts) call starts data collection. You can pass the following options:

Option Type Default Description
environment string undefined Environment name (e.g., 'production', 'staging'). Passed to error tracking for filtering.
release string undefined App version or release identifier. Useful for tracking regressions across deployments.
autoPageview boolean true Automatically track page views. Set to false to track navigation manually.
debug boolean false Log internal activity to the browser console. Useful during development.

Example:

Start data collection
betterstack('init', {
  environment: 'production',
  release: '1.4.2',
});

Identify users

Call betterstack('user', ...) to associate the current session with a known user. Once set, all subsequent errors, events, and session replays are linked to that user.

Identify known user
betterstack('user', {
  id: 'user_123',
  email: 'user@example.com',
  username: 'John Doe',
  group_id: 456,
  group_name: 'Acme Inc.',
  plan: 'premium',
});

id, email, and username uniquely identify the user. group_id and group_name associate the user with a group in order to track behavior at the company, team, or project level.

You can add arbitrary custom properties, like plan in the example above, they're stored alongside the user data.

Call this after sign-in. The association persists for the page session. To clear it at sign-out:

Clear user at sign-out
betterstack('user', null);

If Auto-capture identified user events is enabled in the Frontend tab, clicks, form submissions, and other interactions are automatically captured for identified users.

Track custom events

Use betterstack('track', eventName, data) to send custom events with an arbitrary payload:

Track a custom event
betterstack('track', 'cta-button-click', {
  button_id: 'signup_cta',
  page: '/pricing',
  variant: 'blue',
});
  • eventName: a string identifying the event type.
  • data: an object with any key-value pairs you want to record.

Events appear in Live tail and can be queried in dashboards. The full event schema is documented in the Events reference.

Custom events respect sampling. If the current session was sampled out of web event tracking, track calls are silently dropped. Events are also gated by the Auto-capture anonymous user events and Auto-capture identified user events toggles depending on whether a user has been identified.

Distributed tracing

When trace collection is enabled, the tag captures a pageload trace for the initial browser request. If your backend already started a trace for this request, the tag can continue it, so the frontend pageload becomes part of the same end-to-end trace instead of a new, disconnected one.

The tag reads a W3C traceparent that your server emits with the HTML response and adopts it as the parent of the pageload trace. No configuration is needed: continuation happens automatically whenever a valid traceparent is present. Your server only has to expose it in one of two ways.

Traceparent meta tag

Render a traceparent meta tag into the document <head>:

 
<meta name="traceparent" content="00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01">

Most tracing SDKs can produce this value for the current server span.

Server-Timing response header

If your server can set a response header but not render markup, expose the traceparent as a Server-Timing entry named traceparent on the document response:

 
Server-Timing: traceparent;desc="00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01"

The tag reads this from the browser's Performance API. The header must be on the main document (navigation) response and served from the same origin as the page.

When both are present, the meta tag takes precedence. If neither is present, the tag generates a new trace ID for the pageload span.

Custom configuration

Use betterstack('config', ...) to set configuration options before init is called:

Customize configuration
betterstack('config', {
  environment: 'production',
  release: 'abcdef012345',
  sentry: {
    ignoreErrors: ['TestError'],
  },
});
betterstack('init');

config must be called before init. Calling it after has no effect: a warning is logged if debug is enabled.

The sentry key passes options directly to the underlying error tracking SDK, deep-merged with defaults. Common use cases:

  • ignoreErrors: array of error message patterns to suppress.
  • denyUrls / allowUrls: filter errors by script URL.
  • Any other supported option from the Sentry JavaScript SDK.

All other keys are merged with the init configuration.

This can also be managed remotely from the Frontend tab: see Custom configuration.

Verify installation

  1. Open your application in a browser.
  2. Go to the Frontend tab and check the Verify data collection section that shows whether data has been received.
  3. Alternatively, open Live tail to see events arriving in real time.

Next steps

  • Configuration: UI settings, collection toggles, sampling, session replays, sessions, batching, and more.
  • Events reference: schema of all captured events.

Previous article

JavaScript tag

Next article

Configure the JavaScript tag