@bluewhaleops/agent

Lightweight monitoring collector that runs in your infrastructure and pushes telemetry to BLUEWHALE Ops.

Quick Start

1. Get an API Key

Sign in at bluewhaleops.com and create an API key from Admin > API Keys.

2. Install

npm install @bluewhaleops/agent

3. Create Config

Create bluewhale.config.json:

{
  "api_key": "bw_agent_xxxxxxxxxxxx",
  "endpoint": "https://bluewhaleops.com/api/ingest/batch",
  "agent_id": "prod-us-east-1",
  "venture_id": "my-app",
  "collectors": {
    "health_check": {
      "enabled": true,
      "interval": "5m",
      "targets": [
        { "url": "https://api.example.com/health", "type": "api" },
        { "url": "https://www.example.com", "type": "website" }
      ],
      "timeout_ms": 10000
    },
    "ssl_certificate": {
      "enabled": true,
      "interval": "6h",
      "targets": [
        { "hostname": "api.example.com" },
        { "hostname": "www.example.com" }
      ]
    }
  },
  "transport": {
    "batch_size": 50,
    "flush_interval": "30s",
    "retry_max": 5,
    "retry_backoff": "exponential"
  },
  "logging": {
    "level": "info",
    "format": "json"
  }
}

4. Run

# Daemon mode (long-running)
npx @bluewhaleops/agent start --config ./bluewhale.config.json

# One-shot mode (collect once and exit — good for cron)
npx @bluewhaleops/agent collect --config ./bluewhale.config.json

# Validate config
npx @bluewhaleops/agent validate --config ./bluewhale.config.json

Deployment Options

Docker

# Build
docker build -t @bluewhaleops/agent .

# Run
docker run -d \
  --name @bluewhaleops/agent \
  -e BW_API_KEY=bw_agent_xxxxxxxxxxxx \
  -v ./bluewhale.config.json:/app/bluewhale.config.json:ro \
  @bluewhaleops/agent start --config /app/bluewhale.config.json

Or with Docker Compose:

BW_API_KEY=bw_agent_xxxxxxxxxxxx docker compose up -d

Kubernetes

Deploy as a DaemonSet (runs on every node):

# Create namespace
kubectl create namespace monitoring

# Store your API key
kubectl create secret generic @bluewhaleops/agent-secret \
  --namespace monitoring \
  --from-literal=BW_API_KEY=bw_agent_xxxxxxxxxxxx

# Apply config
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/daemonset.yaml

Or as a CronJob (periodic collection):

kubectl apply -f k8s/cronjob.yaml

Systemd (Bare Metal / VMs)

# /etc/systemd/system/@bluewhaleops/agent.service
[Unit]
Description=BLUEWHALE Monitoring Agent
After=network.target

[Service]
Type=simple
User=bluewhale
ExecStart=/usr/local/bin/node /opt/bluewhale/dist/cli/index.js start --config /etc/bluewhale/config.json
Restart=always
RestartSec=10
Environment=BW_API_KEY=bw_agent_xxxxxxxxxxxx

[Install]
WantedBy=multi-user.target

AWS Lambda / Cron

Use collect mode for serverless:

import { BlueWhaleAgent, loadConfig } from '@bluewhaleops/agent';

export async function handler() {
  const config = loadConfig('./bluewhale.config.json');
  const agent = new BlueWhaleAgent(config);
  const result = await agent.collect();
  return { statusCode: 200, body: JSON.stringify(result) };
}

Programmatic Usage

import { BlueWhaleAgent, loadConfig, createCustomCollector } from '@bluewhaleops/agent';

const config = loadConfig('./bluewhale.config.json');
const agent = new BlueWhaleAgent(config);

// Add a custom collector
const redisCollector = createCustomCollector({
  name: 'redis_health',
  description: 'Check Redis connectivity',
  collect: async () => ({
    health_checks: [{
      venture_id: config.venture_id,
      endpoint: 'redis://redis:6379',
      status_code: 200,
      response_time_ms: 2,
      is_healthy: true,
      checked_at: new Date().toISOString(),
    }],
  }),
});

agent.registerCollector(redisCollector, 60_000); // every 60s

// Event listeners
agent.on('pushed', (data) => console.log('Data sent:', data));
agent.on('error', (data) => console.error('Error:', data));
agent.on('retry', (data) => console.warn('Retrying:', data));

await agent.start();

Collectors

| Collector | What it monitors | Interval | |-----------|-----------------|----------| | health_check | HTTP endpoints (status, response time, headers) | 5m default | | ssl_certificate | TLS cert expiry, version, grade | 6h default | | database | PostgreSQL connectivity & stats | 30m default | | Custom | Anything — write your own collect() function | You decide |

Optional Peer Dependencies

Install only what you need:

# PostgreSQL monitoring
npm install pg

# AWS CloudWatch metrics
npm install @aws-sdk/client-cloudwatch

# Azure Monitor metrics
npm install @azure/monitor-query

# Google Cloud Monitoring
npm install @google-cloud/monitoring

Environment Variables

| Variable | Description | |----------|-------------| | BW_API_KEY | API key (overrides config file) | | DATABASE_URL | PostgreSQL connection string | | BW_ENDPOINT | Ingest endpoint override | | BW_LOG_LEVEL | Log level: debug, info, warn, error |

Environment variables in config values are interpolated: "${DATABASE_URL}" becomes the actual value at runtime.

Resource Footprint

| Metric | Value | |--------|-------| | Memory | 32-64 MB typical | | CPU | < 0.1 core | | Disk | ~2 MB (binary + deps) | | Network | ~1 KB per health check batch |

Architecture

Your Infrastructure                    BLUEWHALE Cloud
┌─────────────────────┐               ┌──────────────────┐
│  @bluewhaleops/agent    │               │  bluewhaleops.com │
│  ┌───────────────┐  │   HTTPS POST  │  ┌────────────┐  │
│  │ Health Check  ├──┼──────────────►│  │ /api/ingest│  │
│  │ SSL Cert      │  │  (batched)    │  │   /batch   │  │
│  │ Database      │  │               │  └─────┬──────┘  │
│  │ Custom        │  │               │        │         │
│  └───────┬───────┘  │               │  ┌─────▼──────┐  │
│          │          │               │  │  Supabase   │  │
│  ┌───────▼───────┐  │               │  │  (storage)  │  │
│  │ Batch Queue   │  │               │  └─────┬──────┘  │
│  │ Retry Queue   │  │               │        │         │
│  └───────────────┘  │               │  ┌─────▼──────┐  │
└─────────────────────┘               │  │ Dashboard   │  │
                                      │  └────────────┘  │
                                      └──────────────────┘

• Push-based: Agent pushes to your BLUEWHALE instance. No inbound ports needed.
• Batched: Collects data, batches it, and flushes on interval or batch size.
• Resilient: Failed pushes are queued to disk and retried with exponential backoff.
• Minimal: Zero runtime dependencies beyond Node.js 18+. Optional peer deps for cloud/DB.

License

MIT