Quickstart

Create a project, install the SDK and send your first error.

1. Create a project

A project collects the telemetry of one app. Owners and admins create projects under Settings → Projects → New project. A new organization offers to create its first project right away.

Create project opens the project’s settings. Under Connection you find:

• DSN: what the SDK needs, such as https://opf_…@ingest.example.com.
• Endpoint: the OTLP address, for apps that send OpenTelemetry without the SDK.

The DSN can only send data, so it is safe in browser code.

2. Install the SDK

npm install @openperf/sdk

Server runtimes need Node.js 22.15 or later, or Bun.

3. Initialize it

Run init before the rest of your app. Pick your runtime.

Browser

import { init } from "@openperf/sdk/browser";

init({
  dsn: "https://opf_…@ingest.example.com",
  environment: "production",
  release: "1.4.2",
});

For a browser app, list your site under Allowed origins in the project settings, such as https://app.example.com. One origin per line, up to 20. Empty accepts any origin; requests from an unlisted origin get 403.

Node.js

Create instrument.mjs:

import { init } from "@openperf/sdk/node";

init({ serviceName: "checkout" });

Start the app with it:

OPENPERF_DSN="https://opf_…@ingest.example.com" \
  node --import ./instrument.mjs app.mjs

Bun

Create instrument.ts with the same init, imported from @openperf/sdk/bun, and preload it:

OPENPERF_DSN="https://opf_…@ingest.example.com" bun --preload ./instrument.ts app.ts

Without a DSN, init does nothing, so you can leave it in local builds.

4. Send a test error

import { captureException } from "@openperf/sdk/browser";

captureException(new Error("OpenPerf test"));

Import from the entry point you initialized. The error shows up under Errors. Requests your app serves or makes appear under Traces, and logs under Logs.

Next

• SDK: every option, automatic instrumentation and the API.
• Releases and source maps: readable browser stacks and release health.
• Errors: triage what came in.