VedaTrace SDK

Universal JavaScript logging SDK for VedaTrace. Type-safe, lightweight, and developer-friendly.

Features

• 🎯 Type-safe - Full TypeScript support with autocomplete
• 🚀 Universal - Works in Node.js, Cloudflare Workers, and browsers
• 📦 Lightweight - ~3KB core, tree-shakeable
• ⚡ Fast - Background batching, non-blocking
• 🔒 Safe - Never breaks your app, graceful failures
• 🎨 Flexible - Console + HTTP transports, child loggers

Installation

npm install vedatrace
# or
yarn add vedatrace
# or
bun add vedatrace

Quick Start

Basic Usage

import { vedatrace } from 'vedatrace'

const logger = vedatrace({
  apiKey: 'your-api-key',
  service: 'my-service'
})

logger.info('Hello world')
logger.error('Something went wrong', { error: err.message })

Development Mode

import { devVedatrace } from 'vedatrace'

// Console-only logging for development
const logger = devVedatrace({ service: 'my-service' })

Configuration

const logger = vedatrace({
  apiKey: 'your-api-key',           // Required for HTTP transport
  service: 'my-service',            // Default service name
  endpoint: 'https://ingest.vedatrace.dev/v1/logs',
  environment: 'production',
  
  // Batching
  batchSize: 100,                   // Flush after N logs
  flushInterval: 5000,              // Flush after N ms
  
  // Retry
  maxRetries: 3,
  retryDelay: 1000,
  
  // Redaction
  redaction: {
    paths: ['password', 'token'],
    mask: '[REDACTED]'
  },
  
  // Callbacks
  onError: (err) => console.error('VedaTrace error:', err),
  onSuccess: () => console.log('Logs sent')
})

Logging

All Log Levels

logger.debug('Debug info', { query: 'SELECT *' })
logger.info('User action', { userId: '123' })
logger.warn('Performance warning', { duration: 500 })
logger.error('Error occurred', { error: err })
logger.fatal('Critical failure', { stack: err.stack })

Service Override

Override the default service for individual logs:

logger.info('Payment processed', { 
  service: 'billing-service',  // Override default
  amount: 99.99 
})

Child Loggers

Create context-aware loggers:

const requestLogger = logger.child({ 
  requestId: 'req_123',
  userId: 'user_456' 
})

requestLogger.info('Processing request') 
// Includes requestId, userId, and default service

Framework Integrations

Express.js

import express from 'express'
import { vedaTraceMiddleware } from 'vedatrace/express'

const app = express()
app.use(vedaTraceMiddleware({ 
  apiKey: process.env.VEDATRACE_API_KEY 
}))

app.get('/', (req, res) => {
  req.vedatrace.info('Home page visited')
  res.json({ ok: true })
})

Next.js (App Router)

import { withVedaTrace } from 'vedatrace/next'

export const GET = withVedaTrace(async (req, { logger }) => {
  logger.info('API called')
  return Response.json({ success: true })
}, { apiKey: '...' })

React

import { VedaTraceProvider, useVedaTrace } from 'vedatrace/react'

function App() {
  return (
    <VedaTraceProvider apiKey="..." service="frontend">
      <MyComponent />
    </VedaTraceProvider>
  )
}

function MyComponent() {
  const logger = useVedaTrace()
  
  useEffect(() => {
    logger.info('Component mounted')
  }, [])
  
  return <div>Hello</div>
}

Cloudflare Workers

import { vedatrace } from 'vedatrace'

export default {
  async fetch(req, env, ctx) {
    const logger = vedatrace({ 
      apiKey: env.VEDATRACE_API_KEY,
      service: 'worker'
    })
    
    logger.info('Request received', { 
      method: req.method,
      url: req.url 
    })
    
    // Ensure logs are sent before response
    ctx.waitUntil(logger.flush())
    
    return new Response('OK')
  }
}

Advanced Usage

Custom Transports

import { VedaTraceHttpTransport, VedaTraceConsoleTransport } from 'vedatrace/transports'

const logger = vedatrace({
  transports: [
    new VedaTraceHttpTransport({ apiKey: '...' }),
    new VedaTraceConsoleTransport({ format: 'pretty' })
  ]
})

Manual Flush

// Flush all pending logs
await logger.flush()

// Use in request handlers
app.post('/webhook', async (req, res) => {
  logger.info('Webhook received')
  await logger.flush() // Ensure sent before responding
  res.json({ ok: true })
})

Graceful Shutdown

The SDK uses background batching that doesn't block your app. For short-lived scripts or when you need explicit cleanup:

const logger = vedatrace({ apiKey: '...' })

logger.info('Processing...')

// For short-lived scripts
await logger.flush()
logger.stop()  // Stop background timer

The SDK timer uses unref() so the process will exit automatically when there's nothing else to do. Call stop() if you need explicit cleanup.

Error Handling

const logger = vedatrace({
  apiKey: '...',
  onError: (err) => {
    // Handle transport errors
    metrics.increment('vedatrace.errors')
  }
})

// SDK never throws - errors are logged to onError
logger.error('Critical error', { stack: err.stack })

Log Schema

Logs sent to VedaTrace follow this schema:

{
  level: 'debug' | 'info' | 'warn' | 'error' | 'fatal'
  message: string
  service?: string
  timestamp?: number  // Auto-generated if not provided
  metadata?: {
    // Any arbitrary metadata
  }
}

API Reference

vedatrace(config)

Creates a new logger instance.

logger.debug(message, metadata?)

Log at debug level.

logger.info(message, metadata?)

Log at info level.

logger.warn(message, metadata?)

Log at warn level.

logger.error(message | Error, metadata?)

Log at error level. Accepts string or Error object.

logger.fatal(message | Error, metadata?)

Log at fatal level. Accepts string or Error object.

logger.child(defaults)

Create a child logger with default metadata.

logger.flush()

Manually flush pending logs. Returns a Promise.

logger.stop()

Stop the background flush timer. Call this for explicit cleanup in long-running processes or before shutdown.

License

MIT