catalyx-agent-node

🧠 Node.js SDK for Catalyx.dev — the world's smartest AI performance engineer for your stack.

🌐 What is Catalyx?

Catalyx.dev transforms traditional monitoring into context-aware, AI-powered performance engineering.

It connects deeply to your stack — from APIs to databases — to:

• 🔍 Diagnose latency and performance bottlenecks

• 🧠 Suggest contextual, actionable fixes

• 💬 Enable a natural-language developer agent for questions like:

  “Why is the /checkout API slow?” “How do I fix this query?”

Soon, Catalyx will also offer safe auto-fix PRs powered by LLMs and static analysis.

📦 What is catalyx-agent-node?

catalyx-agent-node is the official Node.js agent SDK for integrating Catalyx telemetry into your apps.

It uses OpenTelemetry under the hood to:

• Auto-instrument APIs and DB calls
• Send anonymized, structured telemetry to the Catalyx Gateway (via OTLP exporter)
• Provide plug-and-play middleware for popular frameworks like Express, Fastify, NestJS

✨ Features

• ⏱️ Request-level latency tracking (via OpenTelemetry)
• 📤 Automatic batch trace export to the Catalyx backend
• 🧩 Plug-and-play middleware for Express (Fastify, NestJS coming soon)
• 🗃️ Optional DB wrappers for pg, mysql, mongodb, etc.
• 🔍 Dynamic instrumentation loader — only instruments libraries you already use
• ⚙️ Configurable service name, environment, and gateway
• 📦 Framework-agnostic + zero vendor lock-in

🧠 OpenTelemetry in catalyx-agent-node

Catalyx wraps the OpenTelemetry Node SDK to make setup zero-config while keeping all the power.

| Concept | Role in Catalyx | | -------------------- | ----------------------------------------------------------------------------------- | | Provider | Uses NodeSDK to initialize TracerProvider & MeterProvider with sane defaults | | Instrumentations | Auto-loaded dynamically for HTTP servers, DB clients, etc. No manual install needed | | Processor | Uses BatchSpanProcessor for efficient trace batching | | Exporter | Uses OTLPTraceExporter (HTTP/gRPC) to send to Catalyx Gateway | | Collector | Catalyx Collector (self-hosted or cloud) receives OTLP data and enriches it |

Flow:

🚀 Example setup (with Express+Postgres)

npm install catalyx-agent-node

import { startCatalyxTelemetry } from 'catalyx-agent-node';
import { catalyxMiddleware } from 'catalyx-agent-node/express';
import { catalyxWrapper } from 'catalyx-agent-node/postgres';
import {express} 'express';
import {pg} from 'pg';

await startCatalyxTelemetry({
    service: process.env.CATALYX_SERVICE_NAME || 'my-api',
    env: process.env.CATALYX_ENV || 'development',
    gatewayUrl: process.env.CATALYX_GATEWAY_URL,
    debug: true,
    database: {
      slowQueryThresholdMs: 50, // Low threshold for easy testing
      enableN1Detection: true,
      n1ThresholdCount: 3, // Detect after 3 similar queries
      postgres: {
        captureExplainPlans: true,
      },
    },
    framework: {
      slowRequestThresholdMs: 200, // Low threshold for easy testing
    },
  });
  
const pool = new pg.Pool();
const db = catalyxWrapper(pool);

const app = express();
const PORT = process.env.PORT || 3000;
app.use(catalyxMiddleware());

🧠 Telemetry Payload (Example)

The agent emits OpenTelemetry traces — Catalyx enriches them before analysis:

{
  "service": "user-service",
  "env": "production",
  "language": "nodejs",
  "framework": "express",
  "route": "/checkout",
  "method": "GET",
  "status_code": 200,
  "latency_ms": 1842,
  "timestamp": "2025-08-06T10:22:13Z",
  "db_queries": [
    {
      "query": "SELECT * FROM orders WHERE user_id = $1",
      "duration_ms": 750,
      "rows_returned": 500
    }
  ]
}

🔧 Configuration Options

| Option | Type | Description | | ------------ | --------- | --------------------------------- | | service | string | Your microservice name | | env | string | Environment (e.g., dev, prod) | | gatewayUrl | string | Catalyx ingestion endpoint (OTLP) | | debug | boolean | Enable verbose logging |

🧰 Supported Adapters

| Framework | Status | Module | | --------- | -------- | ----------------------- | | Express | ✅ Ready | express/middleware.ts | | Fastify | 🛠️ Soon | fastify/plugin.ts | | NestJS | 🛠️ Soon | nestjs/interceptor.ts | | Koa | 🔜 | | | Hapi | 🔜 | |

🗃 Supported DB Instrumentation

| DB Library | Status | Notes | | ---------- | -------- | ------------------------------ | | pg | ✅ Ready | Auto-wrapped using OTel hooks | | Prisma | 🛠️ Soon | Requires custom client tracing | | MongoDB | 🔜 | Planned | | MySQL | 🔜 | Planned |

🧠 Why OpenTelemetry?

Catalyx uses OpenTelemetry as the universal trace collection layer, enabling:

• Unified cross-language telemetry
• Minimal vendor lock-in
• Easy extensibility
• Seamless integration with other tools

🧪 Example Use Case

Your /checkout route is slow. Catalyx sees:

• HTTP latency is 1800ms
• 90% of time spent in a large pg query
• Suggests index optimization on orders.user_id

You ask the Copilot: "Why is checkout slow?"

It replies: "Query X takes 1.2s and returns 5k rows. Indexing this column would reduce that by ~85%."