Report EC2 Instances by Type, Launch Time and Region

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListInstancesInAllRegions",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeRegions",
        "ec2:DescribeInstances"
      ],
      "Resource": "*"
    }
  ]
}

// ec2-instance-report.ts
// Lists EC2 instances in every enabled region with type, state, launch time and
// how long each has been running, then summarizes by type and by region. Read-only.
// Flags: --all-states (include stopped instances)  --csv (write CSV to stdout)
import {
  EC2Client,
  DescribeRegionsCommand,
  paginateDescribeInstances,
  type Instance,
} from "@aws-sdk/client-ec2";

const args = process.argv.slice(2);
const ALL_STATES = args.includes("--all-states");
const AS_CSV = args.includes("--csv");
const HOME_REGION = process.env.AWS_REGION ?? "us-east-1";

type Row = {
  region: string;
  zone: string;
  instanceId: string;
  name: string;
  type: string;
  state: string;
  launchTime: string;
  firstLaunch: string;
  runningHours: number;
};

async function enabledRegions(): Promise<string[]> {
  const ec2 = new EC2Client({ region: HOME_REGION });
  const { Regions = [] } = await ec2.send(new DescribeRegionsCommand({}));
  return Regions.map((r) => r.RegionName).filter((r): r is string => !!r).sort();
}

// LaunchTime resets on every stop/start. The primary network interface's attach
// time usually still shows when the instance was first launched.
function firstLaunch(i: Instance): Date | undefined {
  const primary = i.NetworkInterfaces?.find((n) => n.Attachment?.DeviceIndex === 0);
  return primary?.Attachment?.AttachTime ?? i.LaunchTime;
}

async function instancesIn(region: string, now: number): Promise<Row[]> {
  const ec2 = new EC2Client({ region });
  const states = ALL_STATES ? ["pending", "running", "stopping", "stopped"] : ["running"];
  const rows: Row[] = [];
  for await (const page of paginateDescribeInstances(
    { client: ec2 },
    { Filters: [{ Name: "instance-state-name", Values: states }] },
  )) {
    for (const reservation of page.Reservations ?? []) {
      for (const i of reservation.Instances ?? []) {
        const running = i.State?.Name === "running" && i.LaunchTime;
        rows.push({
          region,
          zone: i.Placement?.AvailabilityZone ?? "-",
          instanceId: i.InstanceId ?? "-",
          name: i.Tags?.find((t) => t.Key === "Name")?.Value ?? "",
          type: i.InstanceType ?? "-",
          state: i.State?.Name ?? "-",
          launchTime: i.LaunchTime?.toISOString() ?? "-",
          firstLaunch: firstLaunch(i)?.toISOString() ?? "-",
          runningHours: running ? Math.floor((now - i.LaunchTime!.getTime()) / 3_600_000) : 0,
        });
      }
    }
  }
  return rows;
}

function countBy(rows: Row[], key: "type" | "region"): Record<string, number> {
  const counts: Record<string, number> = {};
  for (const r of rows) counts[r[key]] = (counts[r[key]] ?? 0) + 1;
  return Object.fromEntries(Object.entries(counts).sort((a, b) => b[1] - a[1]));
}

function toCsv(rows: Row[]): string {
  const headers = Object.keys(rows[0]) as (keyof Row)[];
  const escape = (v: string | number) => `"${String(v).replace(/"/g, '""')}"`;
  return [headers.join(","), ...rows.map((r) => headers.map((h) => escape(r[h])).join(","))].join("\n");
}

async function main(): Promise<void> {
  const now = Date.now();
  const regions = await enabledRegions();

  // One failing region (an SCP, an opt-in problem) shouldn't sink the whole report.
  const results = await Promise.allSettled(regions.map((r) => instancesIn(r, now)));
  const rows: Row[] = [];
  results.forEach((result, idx) => {
    if (result.status === "fulfilled") rows.push(...result.value);
    else console.error(`Skipped ${regions[idx]}: ${(result.reason as Error).message}`);
  });

  if (rows.length === 0) {
    console.log(`No ${ALL_STATES ? "" : "running "}instances in ${regions.length} regions.`);
    return;
  }
  rows.sort((a, b) => a.region.localeCompare(b.region) || b.runningHours - a.runningHours);

  if (AS_CSV) {
    console.log(toCsv(rows));
    return;
  }
  // firstLaunch is in the CSV; the console table leaves it out to stay readable.
  console.table(rows.map(({ firstLaunch: _omit, ...rest }) => rest));
  console.log("Instances by type:", countBy(rows, "type"));
  console.log("Instances by region:", countBy(rows, "region"));
}

main().catch((err) => {
  console.error(err);
  process.exit(1);
});

npm install @aws-sdk/client-ec2
npm install --save-dev tsx typescript

# Running instances in every enabled region
AWS_PROFILE=readonly npx tsx ec2-instance-report.ts

# Include stopped instances and save a spreadsheet
AWS_PROFILE=readonly npx tsx ec2-instance-report.ts --all-states --csv > ec2-inventory.csv

┌─────────┬─────────────┬──────────────┬───────────────────────┬────────────────┬───────────────┬───────────┬────────────────────────────┬──────────────┐
│ (index) │ region      │ zone         │ instanceId            │ name           │ type          │ state     │ launchTime                 │ runningHours │
├─────────┼─────────────┼──────────────┼───────────────────────┼────────────────┼───────────────┼───────────┼────────────────────────────┼──────────────┤
│ 0       │ 'eu-west-1' │ 'eu-west-1b' │ 'i-0d4c3b2a19f8e7d6c' │ 'eu-api-1'     │ 'm6i.large'   │ 'running' │ '2026-06-11T08:02:19.000Z' │ 2593         │
│ 1       │ 'us-east-1' │ 'us-east-1a' │ 'i-0a1b2c3d4e5f60718' │ 'web-1'        │ 't3.medium'   │ 'running' │ '2026-03-02T14:21:07.000Z' │ 5011         │
│ 2       │ 'us-east-1' │ 'us-east-1c' │ 'i-0f1e2d3c4b5a69788' │ 'web-2'        │ 't3.medium'   │ 'running' │ '2026-09-20T10:45:51.000Z' │ 167          │
│ 3       │ 'us-east-1' │ 'us-east-1a' │ 'i-09a8b7c6d5e4f3021' │ 'batch-worker' │ 'c6i.2xlarge' │ 'running' │ '2026-09-27T06:30:00.000Z' │ 3            │
└─────────┴─────────────┴──────────────┴───────────────────────┴────────────────┴───────────────┴───────────┴────────────────────────────┴──────────────┘
Instances by type: { 't3.medium': 2, 'm6i.large': 1, 'c6i.2xlarge': 1 }
Instances by region: { 'us-east-1': 3, 'eu-west-1': 1 }