Get started with Whale

1Step 1: Register

You need two things: a Whale account, and an API key so Whale knows the data is yours.

Create your account

1. Go to app.whale.balajitech.xyz/register.
2. Choose a plan. Free needs no card, so you can start there and move up later.
3. Enter your details — your name, email and a password of at least 8 characters. Company is optional.
4. Verify your email. We email you a 6-digit code that works for 15 minutes. Nothing arrived? Check your spam folder, or choose Send a new code.
5. That’s it — you’re signed in to your dashboard.

Create an API key

1. In the dashboard, open API keys — the last item in the left sidebar, under Account. (The sidebar shows icons until you point at it.)
2. Type a name you’ll recognise later, like production. Leave App empty.
3. Click Create key, then Copy. A new key starts working within 30 seconds.

2Step 2: Install

Pick what you want to monitor. You can set up several — everything lands in the same account.

Node.js app

NeedsNode.js 20.6 or newer.

1. Install the package in your app’s folder:
   terminal

   Copy

   npm install whalewatch

2. Start your app with Whale loaded first. Use your own entry file instead of app.js, and the key you copied instead of your-key:
   terminal

   Copy

   WHALE_API_KEY=your-key \
     node --import whalewatch/register app.js

   On Windows (PowerShell), set the key with $env:WHALE_API_KEY="your-key" first, then run the same node command without the key in front.

3. Use your app for a moment — open a page or call an endpoint. Within a minute it shows up in the dashboard, in the app called default.

That’s all the code you write. Whale records every incoming request, outgoing call and database query — Express, Fastify, Koa, Postgres, MySQL, MongoDB, Redis, GraphQL, Kafka and about 40 more — plus console, pino, winston and bunyan logs, each linked to the request that wrote it.

Starting it with npm start, Docker or PM2? See Node.js in production.

Linux server

NeedsLinux with systemd (Ubuntu, Debian, Amazon Linux, RHEL and similar), x86-64 or ARM64, and sudo.

1. Run this on the server, with your key:
   on the server

   Copy

   curl -fsSL https://app.whale.balajitech.xyz/agent/install.sh |
     sudo bash -s -- --key your-key

2. The server shows up in Infrastructure → Hosts within a minute.

This installs whale-agent: the OpenTelemetry Collector, pinned to a checked version and run as a systemd service. It reports CPU, memory, load, disks and network, the busiest processes, Docker containers, and on AWS the instance type, region and zone. Command lines never leave the server, because they can contain secrets.

To upgrade, run the same command again. To tail log files or remove the agent, see Server options.

Website

NeedsA publishable key (whk_pub_…). Never put a secret key in a web page.

1. Install the package:
   terminal

   Copy

   npm install whalewatch-browser

2. Call it once when your site starts — for example in main.js:
   main.js

   Copy

   import { initWhaleRum } from 'whalewatch-browser'
   
   initWhaleRum({
     key: 'whk_pub_…',      // your publishable key
     service: 'my-website', // the name you'll see in Whale
   })

3. Open a few pages, then switch tabs or close one — measurements are sent when a page is hidden. They appear under Apps → Browser.

No build step? Paste this just before </body> instead:

<script type="module">
  import { initWhaleRum } from 'https://cdn.jsdelivr.net/npm/whalewatch-browser@0.1.0/+esm'
  initWhaleRum({ key: 'whk_pub_…', service: 'my-website' })
</script>

It records page views and the Core Web Vitals (LCP, INP, CLS, FCP and TTFB). It sets no cookies and doesn’t fingerprint visitors. In Next.js, call it from a client component, inside useEffect.

Python, Java, Go, .NET and others

Whale accepts standard OpenTelemetry, so you use the official OpenTelemetry SDK or agent for your language and point it at Whale with these environment variables:

export OTEL_EXPORTER_OTLP_ENDPOINT=https://ingest.whale.balajitech.xyz
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-key
export OTEL_SERVICE_NAME=checkout-api

Python — no code changes

pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install

# with the variables above set
OTEL_LOGS_EXPORTER=otlp opentelemetry-instrument python app.py

Java — no code changes

curl -LO https://github.com/open-telemetry/opentelemetry-java-instrumentation/releases/latest/download/opentelemetry-javaagent.jar

# with the variables above set
java -javaagent:opentelemetry-javaagent.jar -jar app.jar

For other languages, follow the OpenTelemetry guide for your language and use the same variables. In Docker, Kubernetes or a .env file, set the same names without export. Already run an OpenTelemetry Collector? See OpenTelemetry Collector.

3Step 3: Integrate

Make Whale part of how your software really runs: clear names, loaded on every start, and the rest of your stack connected.

Name your services, apps and environments

Whale sorts your data into three levels. The defaults work, but clear names make the dashboard much easier to read.

Your account
├─ storefront      app
│  ├─ checkout-api service
│  ├─ web          service
│  └─ worker       service
└─ internal-tools  app
   └─ admin-api    service

Set them next to your key, wherever your app gets its environment:

export WHALE_API_KEY=your-key
export WHALE_SERVICE=checkout-api
export WHALE_PROJECT=storefront
export WHALE_ENV=production

Why WHALE_PROJECT? Apps used to be called projects, and the setting kept its name. With an OpenTelemetry SDK, set the app and environment as resource attributes:

export OTEL_RESOURCE_ATTRIBUTES=service.namespace=storefront,deployment.environment.name=production

Node.js in production

Whale has to load before your own code, so it can hook into Express, your database driver and the rest. The simplest way is to add --import whalewatch/register to whatever starts your app.

npm start

{
  "scripts": {
    "start": "node --import whalewatch/register app.js"
  }
}

Docker

CMD ["node", "--import", "whalewatch/register", "app.js"]

docker run -e WHALE_API_KEY=your-key -e WHALE_SERVICE=checkout-api my-image

PM2

module.exports = {
  apps: [{
    name: 'checkout-api',
    script: 'app.js',
    node_args: '--import whalewatch/register',
    env: {
      WHALE_API_KEY: process.env.WHALE_API_KEY,
      WHALE_ENV: 'production',
    },
  }],
}

PM2 reads the environment when the app starts. After changing a variable, run pm2 restart checkout-api --update-env.

systemd

# in your app's unit file
[Service]
WorkingDirectory=/srv/checkout-api
Environment=WHALE_API_KEY=your-key
ExecStart=/usr/bin/node --import whalewatch/register app.js

Can’t change the start command?

Set NODE_OPTIONS=--import whalewatch/register in that app’s own environment instead — your hosting platform’s settings, or a Dockerfile ENV placed after npm ci. Don’t export it in your shell profile: every Node command you run would then try to load Whale.

Or load it on the first line (CommonJS, Node 22.12+)

If your app uses require, you can load Whale at the very top of your entry file instead. Everything required below that line is recorded.

require('dotenv').config()      // if you use dotenv, keep it first
require('whalewatch/register')  // before any other require

const express = require('express')

Apps that use import (ES modules) need --import.

Add your own spans (optional)

Wrap work that isn’t a request or a query — charging a card, building a report — to see it in traces too:

import { trace } from 'whalewatch'

const tracer = trace.getTracer('billing')
await tracer.startActiveSpan('charge-card', async (span) => {
  try {
    await chargeCard()
  } finally {
    span.end()
  }
})

Server options

Add options to the install command. Running it again updates the agent — include every option you want each time, because each run starts from the defaults. The new config is checked before it replaces the running one.

curl -fsSL https://app.whale.balajitech.xyz/agent/install.sh |
  sudo bash -s -- --key your-key \
    --logs 'nginx=/var/log/nginx/*.log' \
    --logs 'api=/srv/api/logs/*.log'

To remove the agent and everything it installed:

curl -fsSL https://app.whale.balajitech.xyz/agent/install.sh | sudo bash -s -- --uninstall

All options are in the Reference. The agent’s own logs: sudo journalctl -u whale-agent. Also running a Node.js app with Whale on the same server? Set WHALE_HOST_METRICS=false in that app so the machine isn’t reported twice.

Connect your AWS account

Nothing to install in AWS. Whale reads your account from outside, with a key that can look but can’t change anything.

1. Create an IAM user for Whale in the AWS console (it doesn’t need console access). Attach the read-only policy Whale gives you: open AWS in Whale’s sidebar and expand Least-privilege policy for the IAM user.
2. Create an access key for that user: IAM → Users → the user → Security credentials → Create access key.
3. Back on Whale’s AWS page, enter a name, the Access key ID, the Secret access key and your Regions (for example ap-south-1, us-east-1), then click Connect. Already connected one? Add more with + Connect AWS.
4. Your account map appears within a minute or so, and CloudWatch metrics within five. After that the map is redrawn every 10 minutes and metrics arrive every 5.

Whale checks the key with AWS before saving it, stores it encrypted, and never shows it again. Root keys are refused. Route 53 and CloudFront come along with the first region.

Or let AWS push to Whale

Deploy the whale-aws CloudFormation stack once per account and region instead. It streams CloudWatch metrics through Firehose and maps load balancers, EC2, RDS, ElastiCache, Lambda and SQS — fewer services than a connected key, and no network layout.

curl -fsSLO https://app.whale.balajitech.xyz/agent/aws/whale-aws.yaml
aws cloudformation deploy --stack-name whale-aws \
  --template-file whale-aws.yaml --capabilities CAPABILITY_IAM \
  --region ap-south-1 --parameter-overrides WhaleIngestKey=your-key

Already using OpenTelemetry?

Add an otlphttp/whale exporter to your OpenTelemetry Collector, then add it to the exporters of each pipeline, next to the ones already there:

exporters:
  otlphttp/whale:
    endpoint: https://ingest.whale.balajitech.xyz
    headers:
      x-api-key: ${env:WHALE_API_KEY}

service:
  pipelines:
    traces:
      exporters: [otlphttp/whale]   # plus your existing exporters
    metrics:
      exporters: [otlphttp/whale]
    logs:
      exporters: [otlphttp/whale]

Moving from another vendor

Send to both for a week, check the data matches, then remove the old exporter:

service:
  pipelines:
    traces:
      exporters: [otlphttp/incumbent, otlphttp/whale]

4Step 4: Use

Check that data is arriving, learn where things are, and try what people do most.

Check that data is arriving

Open Home in the dashboard. Every app that has sent data is listed with its traffic, errors and latency — click one to open its pages.

Want to test your key on its own? Send one log line with curl:

curl https://ingest.whale.balajitech.xyz/v1/logs \
  -H "x-api-key: your-key" \
  -H "content-type: application/json" \
  -d '{"resourceLogs": [{
    "resource": {"attributes": [
      {"key": "service.name", "value": {"stringValue": "hello-whale"}}
    ]},
    "scopeLogs": [{"logRecords": [
      {"severityNumber": 9, "severityText": "INFO", "body": {"stringValue": "Hello, Whale"}}
    ]}]
  }]}'

A reply of {} means it worked — search Logs for service:hello-whale. missing or invalid x-api-key means the key is wrong.

Find your way around

The left sidebar shows icons — point at it to see the names.

Home

Every app at a glance: traffic, errors, latency and what needs attention.

Apps

Opens a second menu for one app — pick it at the top, or choose All apps. Summary, Logs, Metrics, Traces, Services, Databases, External services, Hosts, Browser, Mobile and Issues; then Alerts, Service levels, Dashboards, Uptime and AI.

Infrastructure

All your servers, plus services like Redis and queues, and routes to watch — across every app.

AWS

A live map of your AWS account, with CloudWatch metrics and problems shown where they are.

Account

Organisation, Usage, Billing, Obfuscation (masks secrets before anything is stored), Team, Roles, Single sign-on and API keys.

Search

Press ⌘K (Ctrl+K on Windows and Linux) to jump to any page, app, service, host or log search.

Everyday tasks

What’s included depends on your plan — see Pricing.

Troubleshooting

Still stuck? Email us with what you tried and what you saw.

Reference

Node.js SDK settings

Only WHALE_API_KEY is required. Everything else has a sensible default.

Server agent options

Browser SDK options

Record your own events next to the vitals:

import { recordRumEvent } from 'whalewatch-browser'

recordRumEvent('checkout_step', 2, { plan: 'pro' })

Ingest endpoints

Hosted ingest: https://ingest.whale.balajitech.xyz. Send your key in the x-api-key header. The browser SDK and the AWS stack send it for you.

Self-hosting and help

Need Whale inside your own network? On Enterprise plans it runs on your infrastructure against your own ClickHouse — same platform, same dashboard. Most teams start hosted and move only if compliance requires it.