@egintegrations/telemetry

Official JavaScript/TypeScript telemetry SDK for EGIntegrations client engines.

Installation

``bash


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:

$3

`bash
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)

$3

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!

$3

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.

$3

For CI/CD or automated setups:

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

$3

| Option | Description | Default |
|--------|-------------|---------|
| --engine | Engine name (required) | - |
| --version | Semantic version (required) | - |
| --type | System type (API, BOT, WA, etc.) | - |
| --platform | Platform (VE, EKS, NPM, etc.) | - |
| --url | Control Center URL | https://control-center.egintegrations.com |
| --token | Auth token (optional) | - |
| --modules | Comma-separated module list | - |
| --output | Config file location | .egi/telemetry.json |
| --framework | 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 |

$3

#### Next.js Project

`bash
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:
`typescript
// 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

`bash
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:
`typescript
// 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:

$3

`typescript
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,
},
});
`

$3

`typescript
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
});
`

$3

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

// Stop health checks
clearInterval(healthCheckTimer);
`

$3

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

API Reference

$3

#### 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
Register your engine with the control center.

##### reportStatus(payload: StatusPayload): Promise
Report engine status. Status can be: 'healthy', 'degraded', 'unhealthy', 'starting', 'stopping'.

##### sendMetrics(payload: MetricsPayload): Promise
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`
Report graceful shutdown to control center.

License

Proprietary - EGIntegrations