Introduction

Add observability to your VibORM application with OpenTelemetry tracing and structured logging

Features

• OpenTelemetry Tracing - Automatic span creation for all database operations
• Structured Logging - Callback-based logging with level filtering
• Graceful Degradation - Tracing works without OTel installed (no-op)
• Serverless Compatible - No module-level request context, safe for edge runtimes
• Security Defaults - SQL and parameters hidden unless explicitly enabled
• Request-Scoped Attribution - Concurrent clients keep separate model, operation, and correlation metadata

Quick Example

import { createClient } from "viborm";

// Simple: enable both with defaults
const client = createClient({
  schema,
  driver,
  instrumentation: {
    tracing: true,  // Enable tracing with defaults
    logging: true   // Enable pretty console logging for all levels
  }
});

// Advanced: custom configuration
const clientAdvanced = createClient({
  schema,
  driver,
  instrumentation: {
    tracing: {
      includeSql: true,    // Explicitly include SQL in spans
      includeParams: false // Exclude params for security (default: false)
    },
    logging: {
      query: true,                       // Pretty console output
      error: (event, log) => {           // Custom callback
        errorTracker.capture(event.error);
        log();                           // Also use default logger
      }
    },
    diagnostics: {
      includeSql: false,   // Error metadata is independently private
      includeParams: false
    }
  }
});

Configuration

The instrumentation option accepts three optional configurations:

All three are independent - enable only the outputs each destination needs.

Privacy & Security

By default, VibORM excludes both SQL query text and query parameters:

• includeSql: false (default) - SQL statements are hidden
• includeParams: false (default) - Parameters are hidden to protect sensitive data

Logging, tracing, and error diagnostics have independent disclosure options. Enabling SQL for one output does not enable it for the others.

Thrown VibORMError instances, their meta fields, nested causes, and toJSON() output follow the diagnostics policy. Raw provider messages and undeclared provider fields are redacted. Stable provider codes remain available for retry and incident classification.

Cache keys, including custom keys, are omitted from logs and spans. Cache event/status, model, operation, and correlation ID remain available for diagnosis without deriving another identifier from private key material.

Next Steps