{"_id":"@bluewhaleops/agent","_rev":"2-6706108aac9ae27cf69e30d1d7a995a2","name":"@bluewhaleops/agent","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.0":{"name":"@bluewhaleops/agent","version":"1.0.0","license":"MIT","_id":"@bluewhaleops/agent@1.0.0","maintainers":[{"name":"serbisuyo","email":"serbisuyo@gmail.com"}],"homepage":"https://github.com/blas-tavarahldg/blue-whale#readme","bugs":{"url":"https://github.com/blas-tavarahldg/blue-whale/issues"},"bin":{"bluewhale-agent":"dist/cli/index.js"},"dist":{"shasum":"7ded68dd3ebad5ed703505370ab02a71e83289f8","tarball":"https://registry.npmjs.org/@bluewhaleops/agent/-/agent-1.0.0.tgz","fileCount":9,"integrity":"sha512-L2IjoxBx6MdF4NQRzRWv7JhC/kd6FIGvKlUIJmhIu4UcWhUf+575Tf14VKjENIOXeSDAG2Iy4hMg216f7i/GKQ==","signatures":[{"sig":"MEUCIQDSx34F+Zf5pmYC1kVtX7mmYR6YWrPloDmkPftz4DIA7AIgA6oEAdjkacTf4uFc3/GVUpn8c+1zkD5LpDVArNQBaPo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":267319},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"e96253aa7e970890c359992cb18984ecd835fb2c","scripts":{"dev":"tsup --watch","build":"tsup","type-check":"tsc --noEmit"},"_npmUser":{"name":"serbisuyo","email":"serbisuyo@gmail.com"},"repository":{"url":"git+https://github.com/blas-tavarahldg/blue-whale.git","type":"git","directory":"packages/agent-sdk"},"_npmVersion":"11.11.0","description":"Blue Whale Agent SDK — lightweight collector for multi-cloud monitoring","directories":{},"_nodeVersion":"25.8.0","dependencies":{"zod":"^3.23.0"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^5.9.3"},"peerDependencies":{"pg":">=8.0.0","@azure/monitor-query":">=1.0.0","@google-cloud/monitoring":">=4.0.0","@aws-sdk/client-cloudwatch":">=3.0.0"},"peerDependenciesMeta":{"pg":{"optional":true},"@azure/monitor-query":{"optional":true},"@google-cloud/monitoring":{"optional":true},"@aws-sdk/client-cloudwatch":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/agent_1.0.0_1775048821650_0.903577597087877","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@bluewhaleops/agent","version":"1.0.1","description":"BLUEWHALE Agent SDK — lightweight collector for multi-cloud monitoring","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"bluewhale-agent":"dist/cli/index.js"},"scripts":{"build":"tsup","dev":"tsup --watch","type-check":"tsc --noEmit"},"engines":{"node":">=18.0.0"},"dependencies":{"zod":"^3.23.0"},"peerDependencies":{"@aws-sdk/client-cloudwatch":">=3.0.0","@azure/monitor-query":">=1.0.0","@google-cloud/monitoring":">=4.0.0","pg":">=8.0.0"},"peerDependenciesMeta":{"@aws-sdk/client-cloudwatch":{"optional":true},"@azure/monitor-query":{"optional":true},"@google-cloud/monitoring":{"optional":true},"pg":{"optional":true}},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/tavara-holdings/blue-whale.git","directory":"packages/agent-sdk"},"devDependencies":{"tsup":"^8.5.1","typescript":"^5.9.3"},"gitHead":"85e50b79a446ee369710fde4113f6915bcc20968","_id":"@bluewhaleops/agent@1.0.1","bugs":{"url":"https://github.com/tavara-holdings/blue-whale/issues"},"homepage":"https://github.com/tavara-holdings/blue-whale#readme","_nodeVersion":"25.8.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-8ymbHjP4bkm7R5QWku0pQJhCEF5sMlk6AhKMggubMYgT3r5LaCjpcRlGsBBevwj2iEvDC1/Ntfg5UUxOFMAWhQ==","shasum":"0b5bb732a826a73b6916ea8bb505619cd5b75499","tarball":"https://registry.npmjs.org/@bluewhaleops/agent/-/agent-1.0.1.tgz","fileCount":9,"unpackedSize":367494,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIE3fY/aN531YJ9GRPxmdl3YxFTFGPHo1DL/sKNjbqXeCAiEAng9d7VQhHb5d32UtMtIlP0mjKMpj+4uLQFY0mBlfd+E="}]},"_npmUser":{"name":"serbisuyo","email":"serbisuyo@gmail.com"},"directories":{},"maintainers":[{"name":"serbisuyo","email":"serbisuyo@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent_1.0.1_1780071973462_0.8574510373091577"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-01T13:07:01.523Z","modified":"2026-05-29T16:26:13.753Z","1.0.0":"2026-04-01T13:07:01.821Z","1.0.1":"2026-05-29T16:26:13.622Z"},"bugs":{"url":"https://github.com/tavara-holdings/blue-whale/issues"},"license":"MIT","homepage":"https://github.com/tavara-holdings/blue-whale#readme","repository":{"type":"git","url":"git+https://github.com/tavara-holdings/blue-whale.git","directory":"packages/agent-sdk"},"description":"BLUEWHALE Agent SDK — lightweight collector for multi-cloud monitoring","maintainers":[{"name":"serbisuyo","email":"serbisuyo@gmail.com"}],"readme":"# @bluewhaleops/agent\n\nLightweight monitoring collector that runs in your infrastructure and pushes telemetry to [BLUEWHALE Ops](https://bluewhaleops.com).\n\n## Quick Start\n\n### 1. Get an API Key\n\nSign in at [bluewhaleops.com](https://bluewhaleops.com) and create an API key from **Admin > API Keys**.\n\n### 2. Install\n\n```bash\nnpm install @bluewhaleops/agent\n```\n\n### 3. Create Config\n\nCreate `bluewhale.config.json`:\n\n```json\n{\n  \"api_key\": \"bw_agent_xxxxxxxxxxxx\",\n  \"endpoint\": \"https://bluewhaleops.com/api/ingest/batch\",\n  \"agent_id\": \"prod-us-east-1\",\n  \"venture_id\": \"my-app\",\n  \"collectors\": {\n    \"health_check\": {\n      \"enabled\": true,\n      \"interval\": \"5m\",\n      \"targets\": [\n        { \"url\": \"https://api.example.com/health\", \"type\": \"api\" },\n        { \"url\": \"https://www.example.com\", \"type\": \"website\" }\n      ],\n      \"timeout_ms\": 10000\n    },\n    \"ssl_certificate\": {\n      \"enabled\": true,\n      \"interval\": \"6h\",\n      \"targets\": [\n        { \"hostname\": \"api.example.com\" },\n        { \"hostname\": \"www.example.com\" }\n      ]\n    }\n  },\n  \"transport\": {\n    \"batch_size\": 50,\n    \"flush_interval\": \"30s\",\n    \"retry_max\": 5,\n    \"retry_backoff\": \"exponential\"\n  },\n  \"logging\": {\n    \"level\": \"info\",\n    \"format\": \"json\"\n  }\n}\n```\n\n### 4. Run\n\n```bash\n# Daemon mode (long-running)\nnpx @bluewhaleops/agent start --config ./bluewhale.config.json\n\n# One-shot mode (collect once and exit — good for cron)\nnpx @bluewhaleops/agent collect --config ./bluewhale.config.json\n\n# Validate config\nnpx @bluewhaleops/agent validate --config ./bluewhale.config.json\n```\n\n## Deployment Options\n\n### Docker\n\n```bash\n# Build\ndocker build -t @bluewhaleops/agent .\n\n# Run\ndocker run -d \\\n  --name @bluewhaleops/agent \\\n  -e BW_API_KEY=bw_agent_xxxxxxxxxxxx \\\n  -v ./bluewhale.config.json:/app/bluewhale.config.json:ro \\\n  @bluewhaleops/agent start --config /app/bluewhale.config.json\n```\n\nOr with Docker Compose:\n\n```bash\nBW_API_KEY=bw_agent_xxxxxxxxxxxx docker compose up -d\n```\n\n### Kubernetes\n\nDeploy as a DaemonSet (runs on every node):\n\n```bash\n# Create namespace\nkubectl create namespace monitoring\n\n# Store your API key\nkubectl create secret generic @bluewhaleops/agent-secret \\\n  --namespace monitoring \\\n  --from-literal=BW_API_KEY=bw_agent_xxxxxxxxxxxx\n\n# Apply config\nkubectl apply -f k8s/configmap.yaml\nkubectl apply -f k8s/daemonset.yaml\n```\n\nOr as a CronJob (periodic collection):\n\n```bash\nkubectl apply -f k8s/cronjob.yaml\n```\n\n### Systemd (Bare Metal / VMs)\n\n```ini\n# /etc/systemd/system/@bluewhaleops/agent.service\n[Unit]\nDescription=BLUEWHALE Monitoring Agent\nAfter=network.target\n\n[Service]\nType=simple\nUser=bluewhale\nExecStart=/usr/local/bin/node /opt/bluewhale/dist/cli/index.js start --config /etc/bluewhale/config.json\nRestart=always\nRestartSec=10\nEnvironment=BW_API_KEY=bw_agent_xxxxxxxxxxxx\n\n[Install]\nWantedBy=multi-user.target\n```\n\n### AWS Lambda / Cron\n\nUse `collect` mode for serverless:\n\n```typescript\nimport { BlueWhaleAgent, loadConfig } from '@bluewhaleops/agent';\n\nexport async function handler() {\n  const config = loadConfig('./bluewhale.config.json');\n  const agent = new BlueWhaleAgent(config);\n  const result = await agent.collect();\n  return { statusCode: 200, body: JSON.stringify(result) };\n}\n```\n\n## Programmatic Usage\n\n```typescript\nimport { BlueWhaleAgent, loadConfig, createCustomCollector } from '@bluewhaleops/agent';\n\nconst config = loadConfig('./bluewhale.config.json');\nconst agent = new BlueWhaleAgent(config);\n\n// Add a custom collector\nconst redisCollector = createCustomCollector({\n  name: 'redis_health',\n  description: 'Check Redis connectivity',\n  collect: async () => ({\n    health_checks: [{\n      venture_id: config.venture_id,\n      endpoint: 'redis://redis:6379',\n      status_code: 200,\n      response_time_ms: 2,\n      is_healthy: true,\n      checked_at: new Date().toISOString(),\n    }],\n  }),\n});\n\nagent.registerCollector(redisCollector, 60_000); // every 60s\n\n// Event listeners\nagent.on('pushed', (data) => console.log('Data sent:', data));\nagent.on('error', (data) => console.error('Error:', data));\nagent.on('retry', (data) => console.warn('Retrying:', data));\n\nawait agent.start();\n```\n\n## Collectors\n\n| Collector | What it monitors | Interval |\n|-----------|-----------------|----------|\n| `health_check` | HTTP endpoints (status, response time, headers) | 5m default |\n| `ssl_certificate` | TLS cert expiry, version, grade | 6h default |\n| `database` | PostgreSQL connectivity & stats | 30m default |\n| Custom | Anything — write your own `collect()` function | You decide |\n\n### Optional Peer Dependencies\n\nInstall only what you need:\n\n```bash\n# PostgreSQL monitoring\nnpm install pg\n\n# AWS CloudWatch metrics\nnpm install @aws-sdk/client-cloudwatch\n\n# Azure Monitor metrics\nnpm install @azure/monitor-query\n\n# Google Cloud Monitoring\nnpm install @google-cloud/monitoring\n```\n\n## Environment Variables\n\n| Variable | Description |\n|----------|-------------|\n| `BW_API_KEY` | API key (overrides config file) |\n| `DATABASE_URL` | PostgreSQL connection string |\n| `BW_ENDPOINT` | Ingest endpoint override |\n| `BW_LOG_LEVEL` | Log level: debug, info, warn, error |\n\nEnvironment variables in config values are interpolated: `\"${DATABASE_URL}\"` becomes the actual value at runtime.\n\n## Resource Footprint\n\n| Metric | Value |\n|--------|-------|\n| Memory | 32-64 MB typical |\n| CPU | < 0.1 core |\n| Disk | ~2 MB (binary + deps) |\n| Network | ~1 KB per health check batch |\n\n## Architecture\n\n```\nYour Infrastructure                    BLUEWHALE Cloud\n┌─────────────────────┐               ┌──────────────────┐\n│  @bluewhaleops/agent    │               │  bluewhaleops.com │\n│  ┌───────────────┐  │   HTTPS POST  │  ┌────────────┐  │\n│  │ Health Check  ├──┼──────────────►│  │ /api/ingest│  │\n│  │ SSL Cert      │  │  (batched)    │  │   /batch   │  │\n│  │ Database      │  │               │  └─────┬──────┘  │\n│  │ Custom        │  │               │        │         │\n│  └───────┬───────┘  │               │  ┌─────▼──────┐  │\n│          │          │               │  │  Supabase   │  │\n│  ┌───────▼───────┐  │               │  │  (storage)  │  │\n│  │ Batch Queue   │  │               │  └─────┬──────┘  │\n│  │ Retry Queue   │  │               │        │         │\n│  └───────────────┘  │               │  ┌─────▼──────┐  │\n└─────────────────────┘               │  │ Dashboard   │  │\n                                      │  └────────────┘  │\n                                      └──────────────────┘\n```\n\n- **Push-based**: Agent pushes to your BLUEWHALE instance. No inbound ports needed.\n- **Batched**: Collects data, batches it, and flushes on interval or batch size.\n- **Resilient**: Failed pushes are queued to disk and retried with exponential backoff.\n- **Minimal**: Zero runtime dependencies beyond Node.js 18+. Optional peer deps for cloud/DB.\n\n## License\n\nMIT\n","readmeFilename":"README.md"}