LogSentinel Next.js SDK

Lightweight, non-blocking observability for Next.js apps

Features

• Non-blocking — Fire-and-forget logging that never slows down your app
• Automatic batching — Efficient log transmission with configurable batch sizes
• Smart retry — Exponential backoff for failed requests
• Fail-safe — Graceful degradation; never crashes your app
• Privacy-first — Automatic redaction of sensitive data
• Sampling — Configurable sampling rate for high-traffic apps
• Zero config — Works out of the box with environment variables
• TypeScript — Full type safety included

Installation

npm install logsentinel-nextjs
# or
yarn add logsentinel-nextjs
# or
pnpm add logsentinel-nextjs

Quick Start

1. Add Environment Variables

Create a .env.local file in your project root:

LOGSENTINEL_API_KEY=your_api_key_here
LOGSENTINEL_BASE_URL=https://sentinel.ipvs.cloud/api/sdk/logs
LOGSENTINEL_SAMPLE_RATE=1.0
LOGSENTINEL_BATCH_SIZE=10
LOGSENTINEL_BATCH_INTERVAL=5000

# Debug Mode - Set to 'true' to see detailed SDK logging
# Shows: connection status, batch creation, send success/failure, full log payloads
# Useful for troubleshooting configuration issues or verifying log capture
LOGSENTINEL_DEBUG=false

# Optional: Route filtering (comma-separated patterns)
# Example: LOGSENTINEL_INCLUDE_ROUTES=/api/users/:path*,/api/payments/:path*
# Example: LOGSENTINEL_EXCLUDE_ROUTES=/api/health,/api/ping
# LOGSENTINEL_INCLUDE_ROUTES=
# LOGSENTINEL_EXCLUDE_ROUTES=

2. App Router (Next.js 13+)

Create or update middleware.ts in your project root:

import { logSentinelMiddleware } from 'logsentinel-nextjs';

export const middleware = logSentinelMiddleware;

// Optional: Configure which routes to monitor
export const config = {
  matcher: [
    '/api/:path*',
    '/dashboard/:path*',
  ],
};

3. Pages Router (Next.js 12)

Wrap your API route handlers:

// pages/api/hello.ts
import { withLogSentinel } from 'logsentinel-nextjs';

async function handler(req, res) {
  res.status(200).json({ message: 'Hello from LogSentinel!' });
}

export default withLogSentinel(handler);

That's it! Your logs are now being captured and sent to LogSentinel for analysis.

Some few Configuration

All configuration is done via environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | LOGSENTINEL_API_KEY | Yes | - | Your LogSentinel API key | | LOGSENTINEL_BASE_URL | Yes | - | LogSentinel server URL | | LOGSENTINEL_SAMPLE_RATE | No | 1.0 | Sample rate (0.0 - 1.0) | | LOGSENTINEL_BATCH_SIZE | No | 10 | Logs per batch | | LOGSENTINEL_BATCH_INTERVAL | No | 5000 | Batch interval (ms) | | LOGSENTINEL_MAX_QUEUE_SIZE | No | 1000 | Max logs in memory | | LOGSENTINEL_TIMEOUT | No | 5000 | Request timeout (ms) |

Example Configuration

# Required
LOGSENTINEL_API_KEY=sk_live_abc123xyz
LOGSENTINEL_BASE_URL=https://sentinel.ipvs.cloud

# Optional: Sample 50% of requests for high-traffic apps
LOGSENTINEL_SAMPLE_RATE=0.5

# Optional: Send logs every 20 requests
LOGSENTINEL_BATCH_SIZE=20

# Optional: Flush logs every 10 seconds
LOGSENTINEL_BATCH_INTERVAL=10000

License

MIT © LogSentinel

Links

• GitHub
• npm

Need Help?

• Email: [email protected]

LogSentinel SDK Test App

Minimal Next.js 15 application for testing the LogSentinel SDK in a real-world scenario.

Features

✅ Hello World - Simple GET request returning JSON
✅ Error Simulator - Tests error logging (generic, timeout, validation)
✅ User Generator - POST request with body (creates random user, no DB)
✅ Calculator - Arithmetic operations with query parameters
✅ Echo Endpoint - Tests body sanitization and size limits

Setup

1. Link the LogSentinel SDK

# From the logsentinel-nextjs directory
cd logsentinel-nextjs
npm install
npm link

# From the test app directory
cd ../logsentinel-test-app
npm link logsentinel-nextjs

2. Install Dependencies

npm install

3. Configure Environment

cp .env.example .env.local

Edit .env.local with your LogSentinel credentials:

LOGSENTINEL_API_KEY=your_api_key_here
LOGSENTINEL_BASE_URL=https://sentinel.ipvs.cloud
LOGSENTINEL_SAMPLE_RATE=1.0
LOGSENTINEL_BATCH_SIZE=5

4. Run the App

npm run dev

Open http://localhost:3000

SDK Integration

All API routes in pages/api/ are wrapped with withLogSentinel():

import { withLogSentinel } from 'logsentinel-nextjs';

async function handler(req, res) {
  // Your API logic here
}

// 🔌 Wrap with SDK to enable automatic logging
export default withLogSentinel(handler);

Testing the SDK

1. Click each collapsible section on the homepage
2. Trigger the actions (buttons)
3. Watch for toast notifications (success/error messages)
4. Check the terminal for SDK log output:

   [LogSentinel] Sending batch: { batchId: '...', logs: [...] }

What Gets Logged

Each API request captures:

• Trace ID - Unique identifier for request tracking
• Timestamp - ISO 8601 format
• Method - GET, POST, etc.
• Path - Request URL path
• Status Code - HTTP response code
• Duration - Response time in milliseconds
• Headers - Sanitized request/response headers
• Body - Sanitized request/response body (with sensitive data redacted)
• Error - Stack traces for failed requests
• Metadata - User agent, IP, query params, etc.

Sensitive Data Redaction

The SDK automatically redacts:

• Headers: authorization, cookie, x-api-key
• Body fields: password, token, apiKey, secret

Architecture

Frontend (App Router)          Backend (Pages Router + SDK)
├── app/page.tsx              ├── pages/api/hello.ts ← withLogSentinel()
├── components/               ├── pages/api/error.ts ← withLogSentinel()
│   ├── CollapsibleSection    ├── pages/api/user.ts  ← withLogSentinel()
│   └── ActionButton          ├── pages/api/calculate.ts
└── lib/api-client.ts         └── pages/api/echo.ts

Troubleshooting

SDK not logging?

1. Check .env.local has valid credentials
2. Verify SDK is linked: npm list logsentinel-nextjs
3. Check console for warnings: [LogSentinel] ...

Batches not sending?

• Default batch size is 5 logs
• Batches send every 5 seconds
• Adjust LOGSENTINEL_BATCH_SIZE and LOGSENTINEL_BATCH_INTERVAL in .env.local

License

MIT