Quickstart

Install one SDK, connect one runtime, validate ingestion, and prepare Obtrace for remediation workflows.

Quickstart

Obtrace is most useful when telemetry, release metadata, and repository context are connected early. This quickstart focuses on the shortest path to a production-ready signal baseline.

Outcome

By the end of this guide, you should have:

  • Every detected stack instrumented (backend, frontend, edge functions).
  • Stable service, env, and version tagging.
  • One runtime environment connected.
  • Enough context for root cause analysis and remediation decisions.

Step 1: Instrument your service

Option A: Obtrace Zero (zero-code)

The fastest path. Obtrace Zero auto-instruments your services without code changes — using eBPF, language agents, or sidecar injection depending on your runtime.

Supports Node.js, Python, Java, .NET, PHP, Ruby, and Go out of the box.

Option B: SDK (manual instrumentation)

For full control over what gets captured, use an SDK directly:

Backend:

Frontend:

Fullstack frameworks:

  • Next.js — server + client in one setup

Platforms & Edge:

Multi-stack projects

Obtrace auto-detects all stacks in your repository. If your project combines multiple runtimes, you get a setup snippet for each stack. Instrument all of them for full end-to-end visibility.

Common combinations:

  • React + Supabase → Browser SDK + Supabase Managed Agent
  • Next.js → single Next.js SDK (covers server + client)
  • Vite + Express → Browser SDK + Node SDK
  • React + Cloudflare Workers → Browser SDK + Cloudflare SDK

Agents

  • Database Agent — collect database metrics from PostgreSQL, MySQL, MongoDB, Redis, and more without code changes

Step 2: Set canonical attributes

Every event, span, and error should include:

  • service
  • env
  • version
  • region when applicable

appId and serviceName must resolve to the connected app in the project. You can configure explicit aliases such as core -> web, but arbitrary names are rejected because incident scope, replay, and remediation bind to the canonical project app.

Example:

const sdk = initNodeSDK({
  apiKey: process.env.OBTRACE_API_KEY!,
  tenantId: process.env.OBTRACE_TENANT_ID,
  projectId: process.env.OBTRACE_PROJECT_ID,
  appId: "checkout-api",
  env: process.env.OBTRACE_ENV,
  serviceName: "checkout-api",
  serviceVersion: process.env.OBTRACE_SERVICE_VERSION,
});
 
sdk.span({
  name: "checkout.authorize",
  attrs: {
    "cloud.region": process.env.AWS_REGION ?? "us-east-1",
  },
});

Step 3: Connect the environment

Start with the runtime where the incident actually happens:

Step 4: Validate ingestion

Expected result:

  • Telemetry is continuous.
  • Tags are stable across deploys.
  • Errors contain enough stack and deploy context for diagnosis.

Step 5: Review how remediation works

Before enabling repository actions, read:

On this page