All Integrations
Languagesbun package

Bun Integration

Instrument Bun applications with one bun add command. HTTP handler tracing, bun:sqlite query spans, bundler build performance metrics, and Bun runtime telemetry — built for Bun's speed-first architecture.

Setup

How It Works

01

Install via bun add

Run bun add @tigerops/bun. The package includes a Bun.serve() middleware wrapper, a bun:sqlite query interceptor, a fetch client patcher, a Bun bundler plugin for build metrics, and an OTLP/HTTP exporter tuned for Bun's native fetch implementation.

02

Initialize at Entry Point

Call TigerOps.init() at the top of your entry file before calling Bun.serve(). The init function configures the OTLP exporter, registers the bun:sqlite interceptor, patches global fetch, and starts the runtime metric collector using Bun.gc and process.memoryUsage.

03

Set Environment Variables

Set TIGEROPS_API_KEY, TIGEROPS_SERVICE_NAME, and TIGEROPS_ENVIRONMENT. TigerOps reads them via Bun.env at init() time. Bun's .env file loading is supported automatically. For containerized deployments, inject the key via Kubernetes secrets or Docker environment flags.

04

Handler Spans, SQLite & Build Metrics

TigerOps immediately captures Bun.serve() route handler spans, bun:sqlite query spans, outbound fetch() traces, V8 heap and GC metrics, Bun bundler build duration per output file, module graph analysis timing, and WebSocket lifecycle events.

Capabilities

What You Get Out of the Box

Bun.serve() Handler Tracing

The TigerOps Bun wrapper instruments every HTTP request handled by Bun.serve(). Each request creates a span with matched route pattern, HTTP method, response status, and handler execution time. Static file serving and error responses are tagged separately.

bun:sqlite Query Spans

All SQLite queries executed via bun:sqlite are auto-instrumented. Each query creates a child span with normalized SQL statement, execution time, and row count. Prepared statement reuse is tracked to identify hot query paths and cache effectiveness.

Bundler Build Performance Metrics

The TigerOps Bun bundler plugin hooks into Bun.build() to capture build duration, entry point count, output file count, total output size, module graph resolution time, and TypeScript transpilation time. Build metrics are sent to TigerOps after each build.

fetch() Client Span Injection

TigerOps patches the global fetch to instrument all outbound HTTP calls. Each request creates a child span with target URL, method, response status, and duration. W3C traceparent headers are injected automatically. The patch is transparent to Bun's native fetch optimizations.

Bun Runtime Memory & GC Metrics

Bun runtime metrics are collected every 30 seconds: heap used, heap total, external memory, array buffer bytes (from process.memoryUsage()), and GC event count and duration from the V8 PerformanceObserver. RSS and peak RSS are also tracked.

Hono & ElysiaJS Framework Spans

First-class middleware for Hono (tigerops.honoMiddleware()) and ElysiaJS (tigerops.elysiaPlugin()) adds route pattern matching to spans and captures framework-specific lifecycle events. Plugin execution order and lifecycle hook timings are measured.

Configuration

Install & Initialize

One bun add and one init() call. Full Bun runtime and HTTP observability.

terminal + index.ts
# Install the TigerOps Bun package
bun add @tigerops/bun

# Set environment variables (or use .env file)
export TIGEROPS_API_KEY="your-api-key"
export TIGEROPS_SERVICE_NAME="my-bun-app"
export TIGEROPS_ENVIRONMENT="production"

// index.ts
import { TigerOps, tigeropsServe } from "@tigerops/bun";
import { Database } from "bun:sqlite";

// Initialize before Bun.serve()
TigerOps.init({
  apiKey: Bun.env.TIGEROPS_API_KEY!,
  serviceName: "my-bun-app",
  environment: Bun.env.NODE_ENV ?? "production",
  sqlite: true,
  bundlerMetrics: true,
});

const db = new Database("orders.db");

// Wrap Bun.serve with TigerOps middleware
Bun.serve(
  tigeropsServe({
    port: 3000,
    async fetch(req) {
      const url = new URL(req.url);

      if (url.pathname.startsWith("/api/orders/")) {
        const id = url.pathname.split("/").pop()!;

        return TigerOps.span("order.fetch", (span) => {
          span.setAttribute("order.id", id);
          // bun:sqlite query is auto-traced
          const order = db.query("SELECT * FROM orders WHERE id = ?").get(id);
          if (!order) return new Response("Not found", { status: 404 });
          return Response.json(order);
        });
      }

      return new Response("OK");
    },
  })
);

// build.ts — bundler performance tracking
import { TigerOps } from "@tigerops/bun";
await TigerOps.traceBuild(async () => {
  await Bun.build({
    entrypoints: ["./src/index.ts"],
    outdir: "./dist",
    minify: true,
  });
});
FAQ

Common Questions

Which Bun versions are supported?

Bun 1.0 and later are fully supported. The package uses Bun-specific APIs (Bun.serve, bun:sqlite, Bun.env, Bun.build) and requires Bun as the runtime. It is not compatible with Node.js. The OTLP exporter uses Bun's native fetch for maximum throughput.

How does TigerOps handle Bun's hot reload during development?

TigerOps detects the development environment (NODE_ENV=development or Bun.env.BUN_ENV=development) and reduces sampling to 100% with a shorter export interval for immediate trace visibility. The SDK re-initializes cleanly after hot reloads without accumulating multiple tracer providers.

Does TigerOps work with Bun workspaces and monorepos?

Yes. In a Bun workspace, install @tigerops/bun once at the workspace root. Each service in the workspace can call TigerOps.init() with its own serviceName. Traces from all services are correlated by trace ID and displayed together in the TigerOps distributed trace view.

Can I use TigerOps to trace Bun shell scripts ($`...`)?

Yes. Wrap Bun shell template literal calls with TigerOps.span() to create spans around shell command execution. The span captures the command name (first argument), exit code, and execution time. Shell output is not captured to avoid accidental secret logging.

How are bundler build metrics useful in production?

Build metrics help track bundle size regressions and transpilation performance over time in CI pipelines. Each build sends a metric event to TigerOps tagged with the git commit SHA. TigerOps can alert when bundle size increases by more than a configurable percentage threshold.

Get Started

Full Bun Observability in One bun add

HTTP handler traces, bun:sqlite spans, bundler build metrics, and Bun runtime telemetry — built to match Bun's performance philosophy.