vident-sdk

TypeScript SDK for Vident - monitoring, tracing, and error tracking.

Installation

npm install vident-sdk

Quick Start

import { Vident } from "vident-sdk"

const vident = new Vident({
  apiKey: "sw_...",
  serviceName: "my-api",
})

// Trace an operation
await vident.trace("process-order", async (span) => {
  span.setAttributes({ orderId: "123" })
  await processOrder()
})

Auto-Instrumentation

The SDK can automatically trace database queries, HTTP requests, and more.

Setup with --import (Recommended)

For reliable auto-instrumentation, load the SDK before any other modules using Node's --import flag:

1. Create instrumentation.ts:

import { Vident, autoInstrumentations } from "vident-sdk"

new Vident({
  apiKey: process.env.VIDENT_API_KEY,
  serviceName: process.env.VIDENT_SERVICE_NAME ?? "my-api",
  instrumentations: autoInstrumentations(),
})

2. Update your start command:

{
  "scripts": {
    "start": "node --import ./dist/instrumentation.js dist/index.js",
    "dev": "tsx --import ./src/instrumentation.ts src/index.ts"
  }
}

This ensures pg, fetch, etc. are patched before any modules use them.

What gets auto-instrumented

autoInstrumentations() detects and instruments:

| Library | Spans Created | |---------|---------------| | pg (PostgreSQL) | pg:SELECT users, pg:INSERT orders | | fetch | GET api.stripe.com, POST internal-api.com | | @prisma/client | prisma:user.findMany, prisma:order.create | | @aws-sdk/* | aws:S3.PutObject, aws:SQS.SendMessage |

Disabling specific instrumentations

autoInstrumentations({
  prisma: false,  // Disable if using Prisma extension instead
  pg: false,      // Disable PostgreSQL
  fetch: false,   // Disable fetch
  awsSdk: false,  // Disable AWS SDK
})

HTTP Framework Middleware

Add server-side tracing for incoming requests:

Hono

import { Vident, createHonoMiddleware } from "vident-sdk"

const vident = new Vident({ apiKey: "sw_...", serviceName: "my-api" })
app.use(createHonoMiddleware(vident))

Express

import { Vident, createExpressMiddleware } from "vident-sdk"

const vident = new Vident({ apiKey: "sw_...", serviceName: "my-api" })
app.use(createExpressMiddleware(vident))

Fastify

import { Vident, createFastifyPlugin } from "vident-sdk"

const vident = new Vident({ apiKey: "sw_...", serviceName: "my-api" })
fastify.register(createFastifyPlugin(vident))

Prisma Extension

For more control over Prisma tracing, use the extension instead of auto-instrumentation:

import { Vident } from "vident-sdk"
import { createPrismaExtension } from "vident-sdk/instrument"

const vident = new Vident({
  apiKey: "sw_...",
  serviceName: "my-api",
  instrumentations: autoInstrumentations({ prisma: false }), // Disable auto
})

const prisma = new PrismaClient().$extends(createPrismaExtension(vident))

Fetch Instrumentation Options

By default, spans are created for all fetch requests but trace headers are not propagated (to avoid breaking third-party SDKs).

To enable distributed tracing with your own services:

import { FetchInstrumentation } from "vident-sdk/instrument"

new Vident({
  apiKey: "sw_...",
  serviceName: "my-api",
  instrumentations: [
    new FetchInstrumentation({
      propagateToUrls: [
        /\.mycompany\.com$/,    // Regex: any subdomain
        "api.internal.com",      // String: URLs containing this
      ],
    }),
  ],
})

Manual Tracing

trace() - Automatic span lifecycle

const result = await vident.trace("process-order", async (span) => {
  span.setAttributes({ orderId: "123" })
  const order = await db.getOrder("123")
  return order
})
// Span automatically ends, errors recorded if thrown

startSpan() - Manual control

const span = vident.startSpan("custom-operation", { kind: "internal" })
try {
  await doWork()
  span.setAttributes({ result: "success" })
} catch (error) {
  span.end({ error })
  throw error
}
span.end()

Metrics

vident.counter("orders.processed", 1)
vident.gauge("queue.depth", 42)
vident.histogram("request.duration", 150, { unit: "ms" })

Events

vident.info("user.signup", "New user registered", { userId: "123" })
vident.warn("rate.limit", "Rate limit approaching", { current: 95 })
vident.errorEvent("payment.failed", "Payment declined", { reason: "insufficient_funds" })

Cron Job Monitoring

// Automatic start/success/fail tracking
await vident.wrap("daily-backup", async () => {
  await runBackup()
})

// Manual pinging
await vident.ping("check-id")
await vident.ping("check-id", { type: "start" })
await vident.ping("check-id", { type: "fail", body: "Error details" })

Configuration

const vident = new Vident({
  apiKey: "sw_...",           // Required
  serviceName: "my-api",      // Required for tracing
  baseUrl: "https://...",     // Optional, custom API endpoint
  timeout: 30000,             // Optional, default 30s
  retries: 2,                 // Optional, default 2
  sampler: traceIdRatioSampler(0.1), // Optional, sample 10% of traces
})

Development Mode

When apiKey is undefined, all methods silently no-op:

const vident = new Vident({ apiKey: process.env.VIDENT_API_KEY })
// Works in dev (no-op) and prod (sends data)

Error Handling

import { VidentError, NotFoundError, UnauthorizedError } from "vident-sdk"

try {
  await vident.projects.get("invalid-id")
} catch (error) {
  if (error instanceof NotFoundError) {
    console.log("Not found")
  } else if (error instanceof UnauthorizedError) {
    console.log("Invalid API key")
  }
}

License

MIT