Monoscope Browser SDK

The Monoscope Browser SDK is a lightweight JavaScript library for adding session replay, performance tracing, and frontend logging to your web applications.

When used together with the Monoscope Server SDKs, you gain end-to-end observability — seamlessly connecting user interactions in the browser to backend services, APIs, and databases.

This means you can:

• Replay user sessions to see exactly what happened.
• Trace requests from the frontend, through your backend, and into your database.
• Capture logs and errors with full context for faster debugging.

With the sdk, you can seamlessly monitor how users interact with your app, measure performance, and gain insights into issues — all in one place.

---

Installation

Install via npm/bun:

npm install @monoscopetech/browser

Or include it directly in your HTML using a <script> tag:

<script src="https://unpkg.com/@monoscopetech/browser@latest/dist/monoscope.min.js"></script>

---

Quick Start

Initialize Monoscope with your project ID and configuration:

import Monoscope from "@monoscopetech/browser";

const monoscope = new Monoscope({
  projectId: "YOUR_PROJECT_ID",
  serviceName: "my-web-app",
  // ...other configuration options
});

---

Configuration

The Monoscope constructor accepts the following options:

Name	Type	Description
projectId	string	Required – Your Monoscope project ID.
serviceName	string	Required – Name of your service or application.
exporterEndpoint	string	Endpoint for exporting traces/logs. Defaults to Monoscope's ingest endpoint.
propagateTraceHeaderCorsUrls	RegExp[]	Array of regex patterns for URLs where trace headers should be propagated.
resourceAttributes	Record<string, any>	Additional resource-level attributes.
instrumentations	any[]	OpenTelemetry instrumentations to enable.
replayEventsBaseUrl	string	Base URL for session replay events. Defaults to Monoscope's ingest endpoint.
user	MonoscopeUser	Default user information for the session.

---

User Object

The MonoscopeUser object can contain:

Name	Type	Description
email	string	User's email address.
fullName	string	User's full name.
name	string	User's preferred name.
id	string	User's unique identifier.
roles	string[]	User's roles.

---

API

setUser(user: MonoscopeUser)

Associates the given user with the current session.

monoscope.setUser({
  id: "user-123",
  email: "user@example.com",
});

---

getSessionId(): string

Retrieves the current session ID — useful for tagging custom spans or events.

const sessionId = monoscope.getSessionId();
console.log(sessionId);

---

License

This SDK is licensed under the MIT License.