@egintegrations/telemetry

Official JavaScript/TypeScript telemetry SDK for EGIntegrations client engines.

Installation

# npm
npm install @egintegrations/telemetry

# pnpm
pnpm add @egintegrations/telemetry

# yarn
yarn add @egintegrations/telemetry

Quick Setup with CLI

The fastest way to integrate telemetry into your project:

Interactive Setup

npx @egintegrations/telemetry init

The CLI will:

1. Show the EGI ASCII logo and welcome message
2. Detect your framework (Next.js, Express, Fastify, or generic)
3. Prompt for engine configuration:
   • Engine name
   • Version (semantic version like 1.0.0)
   • System type (16 options: API, BOT, WA, RAG, ETL, INT, CMS, MA, DA, AI, DB, OP, FX, SDK, CLI, QA)
   • Platform (25 options: VE, EKS, GKE, NPM, PYPI, etc.)
4. Generate full SKU automatically (e.g., 1.0.0.API.VE.20260113)
5. Create configuration file (.egi/telemetry.json)
6. Create integration code (lib/telemetry.ts for Next.js, telemetry.ts for Express/Fastify)

How It Works

1. Install and configure (30 seconds)
2. Deploy your project (Vercel, Heroku, K8s, anywhere)
3. Engine automatically registers on first startup
4. View in dashboard: https://control-center.egintegrations.com/ui

No manual configuration. No YAML files. Just install, configure, and deploy!

SKU Format

SKUs follow the format: VERSION.TYPE.PLATFORM.DATE

Example: 1.0.0.API.VE.20260113

• VERSION: Semantic version (1.0.0, 2.1.3, etc.)
• TYPE: System type - API, BOT, WA, RAG, ETL, INT, CMS, MA, DA, AI, DB, OP, FX, SDK, CLI, QA
• PLATFORM: Deployment platform - VE (Vercel), EKS, GKE, NPM, PYPI, etc.
• DATE: Auto-generated timestamp (YYYYMMDD)

The CLI will guide you through selecting the appropriate type and platform for your project.

Non-Interactive Setup

For CI/CD or automated setups:

npx @egintegrations/telemetry init \
  --engine my-engine \
  --version 1.0.0 \
  --type API \
  --platform VE \
  --url https://control-center.egintegrations.com

CLI Options

| Option | Description | Default | |--------|-------------|---------| | --engine <name> | Engine name (required) | - | | --version <version> | Semantic version (required) | - | | --type <type> | System type (API, BOT, WA, etc.) | - | | --platform <platform> | Platform (VE, EKS, NPM, etc.) | - | | --url <url> | Control Center URL | https://control-center.egintegrations.com | | --token <token> | Auth token (optional) | - | | --modules <modules> | Comma-separated module list | - | | --output <path> | Config file location | .egi/telemetry.json | | --framework <type> | Force framework type (nextjs, express, fastify, generic) | Auto-detected | | --no-interactive | Skip prompts, fail on missing args | Interactive mode | | --no-codegen | Only generate config file | Code generation enabled |

Framework-Specific Examples

Next.js Project

cd my-nextjs-app
npm install @egintegrations/telemetry
npx @egintegrations/telemetry init
# Select: 1.0.0, API type, VE platform

# Deploy to Vercel
vercel deploy --prod

# Check dashboard - engine appears automatically!
# https://control-center.egintegrations.com/ui

Generated Files:

• .egi/telemetry.json - Configuration with full SKU
• lib/telemetry.ts - Telemetry client singleton (auto-registers on import)

Usage in Next.js:

// The telemetry client is already registered automatically
// Just import and use when you need custom metrics:

import telemetry from '@/lib/telemetry';

export async function GET() {
  await telemetry.sendMetrics({
    metrics: { api_calls: 1 }
  });

  return Response.json({ ok: true });
}

Express Project

cd my-express-app
npm install @egintegrations/telemetry
npx @egintegrations/telemetry init
# Select: 1.0.0, API type, EKS platform

# Deploy however you normally deploy
npm start

Generated Files:

• .egi/telemetry.json - Configuration with full SKU
• telemetry.ts - Telemetry client with health endpoint

Usage in Express:

// telemetry.ts already sets up /.well-known/engine-status endpoint
// and registers on startup. Just import and use:

import express from 'express';
import telemetry from './telemetry';

const app = express();

// Optional: Auto-track requests
app.use(telemetry.middleware());

// Use in routes for custom metrics
app.get('/data', async (req, res) => {
  await telemetry.sendMetrics({ metrics: { requests: 1 } });
  res.json({ ok: true });
});

app.listen(3000);

Manual Setup (Advanced)

If you prefer manual setup instead of using the CLI:

Quick Start

import { TelemetryClient } from '@egintegrations/telemetry';

// Initialize the client
const telemetry = new TelemetryClient({
  engineName: 'my-awesome-engine',
  skuVersion: '1.0.0.API.VE.20260113', // Full SKU format: VERSION.TYPE.PLATFORM.DATE
  controlCenterUrl: 'https://control-center.egintegrations.com',
  authToken: 'optional-auth-token', // Optional
  enabled: true, // Default: true
});

// Register your engine (auto-creates engine in dashboard)
await telemetry.register({
  environment: 'production',
  region: 'us-east-1',
});

// Report status
await telemetry.reportStatus({
  status: 'healthy',
  metadata: {
    activeConnections: 42,
    queueSize: 100,
  },
  metrics: {
    cpu_usage: 45.2,
    memory_mb: 512,
  },
});

// Send custom metrics
await telemetry.sendMetrics({
  metrics: {
    orders_processed: 150,
    revenue_usd: 5420.50,
  },
});

Express/Fastify Integration

import express from 'express';
import { TelemetryClient } from '@egintegrations/telemetry';

const app = express();
const telemetry = new TelemetryClient({
  engineName: 'api-server',
  skuVersion: '1.0.0.API.EKS.20260113', // Full SKU format
  controlCenterUrl: 'https://control-center.egintegrations.com',
});

// Automatic request metrics
app.use(telemetry.middleware());

app.listen(3000, async () => {
  await telemetry.register(); // Auto-registers in dashboard
});

Automatic Health Checks

// Report health every 60 seconds
const healthCheckTimer = telemetry.startHealthCheck(60000);

// Stop health checks
clearInterval(healthCheckTimer);

Graceful Shutdown

process.on('SIGTERM', async () => {
  await telemetry.shutdown();
  process.exit(0);
});

API Reference

TelemetryClient

Constructor Options

• engineName (string, required) - Unique name for your engine
• skuVersion (string, required) - Full SKU (e.g., "1.0.0.API.VE.20260113")
• controlCenterUrl (string, required) - URL of your control center
• authToken (string, optional) - Authentication token if required
• enabled (boolean, optional) - Enable/disable telemetry (default: true)

Methods

register(metadata?: object): Promise<void>

Register your engine with the control center.

reportStatus(payload: StatusPayload): Promise<void>

Report engine status. Status can be: 'healthy', 'degraded', 'unhealthy', 'starting', 'stopping'.

sendMetrics(payload: MetricsPayload): Promise<void>

Send custom metrics to the control center.

startHealthCheck(intervalMs?: number): NodeJS.Timeout

Start automatic health checks (default: every 60 seconds).

middleware(): Function

Express/Fastify middleware for automatic request tracking.

shutdown(): Promise<void>

Report graceful shutdown to control center.

License

Proprietary - EGIntegrations