API Visualizer SDK

The official Node.js SDK for API Visualizer.

API Visualizer is an observability and execution tracing platform for Express applications. It provides deep visibility into your API routes, database queries, and external HTTP calls without requiring complex manual instrumentation.

Table of Contents

• Features
• Installation
• Quick Start
• Configuration
• Auto-Instrumentation
  • Mongoose
  • Axios
• Error Tracking
• Security and Privacy
• Architecture
• Troubleshooting
• License

Features

• Zero-Config Request Tracing: Automatically records execution time, headers, parameters, and payloads for all Express routes.
• Database Query Tracing: Deep integration with Mongoose to capture exact MongoDB queries, connection overhead, and execution times.
• Outbound HTTP Tracing: Auto-instrumentation for Axios to monitor external API dependencies and webhooks.
• Error Capture: Middleware to catch unhandled exceptions and attach them directly to the associated request trace.
• Automatic Sanitization: Built-in scrubbing of sensitive data (passwords, tokens, authorization headers) before data ever leaves your server.
• Asynchronous Execution: Traces are processed and transmitted entirely out-of-band to guarantee zero impact on your API response times.

Installation

Install the SDK via npm:

npm install api-visualizer-sdk

Quick Start

Initialize the visualizer and inject it into your Express application. For optimal observability, attach the primary middleware as high as possible in your stack, and the error handler at the very bottom.

const express = require('express');
const { createVisualizer } = require('api-visualizer-sdk');

const app = express();

// 1. Initialize the SDK
const { visualizer, visualizerErrorHandler } = createVisualizer({
  projectKey: 'YOUR_PROJECT_KEY'
});

// 2. Attach the main middleware BEFORE your routes
app.use(visualizer);

// Standard Express setup
app.use(express.json());

// Your application routes
app.get('/api/users', (req, res) => {
  res.json({ status: 'success' });
});

// 3. Attach the error middleware AFTER your routes
app.use(visualizerErrorHandler);

app.listen(3000, () => {
  console.log('Server is running on port 3000');
});

Configuration

The createVisualizer function accepts a configuration object with the following properties:

| Property | Type | Default | Description | |---|---|---|---| | projectKey | String | 'local' | Required. Your unique project identifier. Traces without a valid key will be rejected by the server in production environments. | | serverUrl | String | 'https://api-visualizer-1.onrender.com' | The destination URL where traces are ingested. If you are self-hosting the API Visualizer server, update this to point to your instance. | | enabled | Boolean | NODE_ENV !== 'production' | Toggles trace collection. By default, tracing is disabled in production to prevent unintended overhead, but can be forced true. | | mongoose | Object | undefined | Pass your mongoose instance to enable automatic database query tracing. | | axios | Object | undefined | Pass your axios instance to enable automatic outbound HTTP request tracing. |

Auto-Instrumentation

The SDK can automatically trace operations beyond the standard Express lifecycle by patching popular libraries.

Mongoose

To track database operations (queries, updates, deletions), pass your imported Mongoose instance to the SDK during initialization. The SDK will automatically trace methods like find, findOne, save, updateOne, deleteOne, and aggregate.

const mongoose = require('mongoose');
const { createVisualizer } = require('api-visualizer-sdk');

const { visualizer, visualizerErrorHandler } = createVisualizer({
  projectKey: 'YOUR_PROJECT_KEY',
  mongoose: mongoose // Injects MongoDB tracing
});

Axios

To track external API calls made by your application, pass your Axios instance. The SDK uses interceptors to measure DNS resolution, connection time, and data transfer durations.

const axios = require('axios');
const { createVisualizer } = require('api-visualizer-sdk');

const { visualizer, visualizerErrorHandler } = createVisualizer({
  projectKey: 'YOUR_PROJECT_KEY',
  axios: axios // Injects outbound HTTP tracing
});

Error Tracking

To accurately correlate exceptions with the requests that caused them, you must use the exported visualizerErrorHandler.

This middleware must be the last middleware applied to your Express application, immediately preceding your server initialization.

// ... all routes and other middleware ...

// Must be at the very bottom
app.use(visualizerErrorHandler);

When an error is caught, the SDK attaches the stack trace, error message, and error type to the active trace context before transmitting it to the dashboard.

Security and Privacy

API Visualizer is designed to be secure by default.

Data Sanitization

Before any payload is transmitted to the ingest server, it passes through an internal sanitizer. The following keys (and their values) are aggressively redacted from headers, request bodies, route parameters, and query strings:

• password
• token
• authorization
• secret
• cookie
• key

The values are replaced with [REDACTED] to ensure no sensitive customer data or internal credentials leak into your observability platform.

Payload Truncation

To prevent memory bloat and large network payloads, strings exceeding 1000 characters within request payloads are automatically truncated.

Architecture

Understanding how the SDK operates under the hood can help you optimize your application's observability.

1. Context Propagation: The SDK utilizes Node.js async_hooks (specifically AsyncLocalStorage) to maintain state across asynchronous operations. This allows a database query occurring deep within a service layer to be accurately associated with the incoming HTTP request that triggered it.
2. Out-of-Band Transmission: Traces are batched and emitted to the ingest server asynchronously via the built-in http module. This process does not block the Express response lifecycle.
3. Trace Structure: A trace consists of a Root Span (representing the entire HTTP request lifecycle) and Child Spans (representing internal operations like Mongoose queries or Axios requests).

Troubleshooting

Traces are not appearing in the dashboard

• Check your Environment: The SDK defaults to enabled: false if NODE_ENV === 'production'. Force enabled: true in your configuration to override this.
• Verify Project Key: Ensure the projectKey exactly matches the one provided in your API Visualizer dashboard.
• Check Network Egress: Ensure your deployment environment allows outbound HTTP traffic to the serverUrl (default: https://api-visualizer-1.onrender.com).

"No projectKey provided" Warning

If you omit the projectKey, the SDK operates in a degraded state and assigns the key 'local'. While this may work for local development servers configured to accept unsigned traces, production dashboards will reject the data.

Sub-operations (DB/HTTP) are missing

Ensure you are passing the exact module instances used by your application into the createVisualizer configuration. If you instantiate a separate Axios client, you must pass that specific client to the SDK.

License

MIT License