Find T3 and Other Burstable Instances With Unlimited Mode Charges

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ReadInstancesCreditsAndMetrics",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceCreditSpecifications",
        "cloudwatch:GetMetricData"
      ],
      "Resource": "*"
    },
    {
      "Sid": "SwitchToStandardOnlyWithApply",
      "Effect": "Allow",
      "Action": "ec2:ModifyInstanceCreditSpecification",
      "Resource": "arn:aws:ec2:*:123456789012:instance/*"
    }
  ]
}

// find-unlimited-mode-charges.ts
// Lists burstable EC2 instances (T2, T3, T3a, T4g, T8i) and their credit option, then prices the surplus
// CPU credits each unlimited instance was charged for over the last 30 days (CloudWatch CPUSurplusCreditsCharged).
// Report only by default. With --apply --instance-ids it switches the listed instances to standard mode.
// Usage: npx tsx find-unlimited-mode-charges.ts [--regions us-east-1,eu-west-1] [--days 30]
//        npx tsx find-unlimited-mode-charges.ts --regions us-east-1 --apply --instance-ids i-0abc,i-0def
import {
  EC2Client,
  paginateDescribeInstances,
  DescribeInstanceCreditSpecificationsCommand,
  ModifyInstanceCreditSpecificationCommand,
  type Instance,
} from "@aws-sdk/client-ec2";
import { CloudWatchClient, paginateGetMetricData, type MetricDataQuery } from "@aws-sdk/client-cloudwatch";

const args = process.argv.slice(2);
const flag = (name: string): string | undefined => {
  const i = args.indexOf(name);
  return i >= 0 ? args[i + 1] : undefined;
};
const regions = (flag("--regions") ?? process.env.AWS_REGION ?? "us-east-1").split(",").map((r) => r.trim()).filter(Boolean);
const days = Math.min(Math.max(Number(flag("--days") ?? 30), 7), 90);
const apply = args.includes("--apply");
const applyIds = new Set((flag("--instance-ids") ?? "").split(",").map((v) => v.trim()).filter(Boolean));

// Surplus credit price per vCPU-hour, us-east-1, AWS Price List (published 25 September 2026).
// One CPU credit is one vCPU at 100% for one minute, so vCPU-hours = credits / 60.
const LINUX: Record<string, number> = { t2: 0.05, t3: 0.05, t3a: 0.05, t4g: 0.04, t8i: 0.06 };
const WINDOWS: Record<string, number> = { t2: 0.096, t3: 0.096, t8i: 0.115 };
const BURSTABLE = Object.keys(LINUX);

interface Row {
  Instance: string;
  Name: string;
  Type: string;
  Credits: string;
  AvgCpu: string;
  CreditsCharged: number;
  Cost: string;
  SurplusNow: number;
  Advice: string;
  cost: number;
}

const errorText = (err: unknown): string => (err instanceof Error ? `${err.name}: ${err.message}` : String(err));
const family = (type: string): string => type.split(".")[0];

async function creditModes(ec2: EC2Client, ids: string[]): Promise<Map<string, string>> {
  const out = new Map<string, string>();
  for (let i = 0; i < ids.length; i += 1000) {
    const res = await ec2.send(new DescribeInstanceCreditSpecificationsCommand({ InstanceIds: ids.slice(i, i + 1000) }));
    for (const spec of res.InstanceCreditSpecifications ?? []) {
      if (spec.InstanceId) out.set(spec.InstanceId, spec.CpuCredits ?? "unknown");
    }
  }
  return out;
}

/** Total credits charged, latest surplus balance and average CPU per instance. */
async function readMetrics(cw: CloudWatchClient, ids: string[]) {
  const end = new Date();
  const start = new Date(end.getTime() - days * 86_400_000);
  const specs: [string, string][] = [
    ["CPUSurplusCreditsCharged", "Sum"],
    ["CPUSurplusCreditBalance", "Maximum"],
    ["CPUUtilization", "Average"],
  ];
  const queries: MetricDataQuery[] = ids.flatMap((id, n) =>
    specs.map(([name, stat], m) => ({
      Id: `q${n}_${m}`,
      MetricStat: {
        Metric: { Namespace: "AWS/EC2", MetricName: name, Dimensions: [{ Name: "InstanceId", Value: id }] },
        Period: 86_400,
        Stat: stat,
      },
    })),
  );
  const out = new Map(ids.map((id) => [id, { charged: 0, surplusNow: 0, cpu: [] as number[] }]));
  for (let i = 0; i < queries.length; i += 500) {
    const pages = paginateGetMetricData(
      { client: cw },
      { MetricDataQueries: queries.slice(i, i + 500), StartTime: start, EndTime: end, ScanBy: "TimestampDescending" },
    );
    for await (const page of pages) {
      for (const r of page.MetricDataResults ?? []) {
        const match = /^q(\d+)_(\d)$/.exec(r.Id ?? "");
        const m = match ? out.get(ids[Number(match[1])]) : undefined;
        const values = r.Values ?? [];
        if (!match || !m || values.length === 0) continue;
        if (match[2] === "0") m.charged += values.reduce((a, b) => a + b, 0);
        if (match[2] === "1") m.surplusNow = Math.max(m.surplusNow, values[0]); // newest day first
        if (match[2] === "2") m.cpu.push(...values);
      }
    }
  }
  return out;
}

function advise(mode: string, charged: number, avgCpu: number | undefined): string {
  if (mode !== "unlimited") return "standard: throttled to baseline when credits run out";
  if (charged === 0) return "no surplus charges: unlimited costs nothing extra here";
  if (avgCpu !== undefined && avgCpu >= 40) return "busy all day: price a larger size or a non-burstable type";
  return "short bursts: compare the charge with one size up before switching to standard";
}

async function scanRegion(region: string): Promise<void> {
  const ec2 = new EC2Client({ region });
  const instances: Instance[] = [];
  const filters = [
    { Name: "instance-state-name", Values: ["running", "stopped"] },
    { Name: "instance-type", Values: BURSTABLE.map((f) => `${f}.*`) },
  ];
  for await (const page of paginateDescribeInstances({ client: ec2 }, { Filters: filters })) {
    for (const r of page.Reservations ?? []) instances.push(...(r.Instances ?? []).filter((i) => i.InstanceId));
  }
  if (instances.length === 0) {
    console.log(`${region}: no burstable instances`);
    return;
  }
  const ids = instances.map((i) => i.InstanceId ?? "");
  const modes = await creditModes(ec2, ids);
  const metrics = await readMetrics(new CloudWatchClient({ region }), ids);

  const rows: Row[] = instances.map((inst) => {
    const id = inst.InstanceId ?? "";
    const type = inst.InstanceType ?? "";
    const windows = (inst.PlatformDetails ?? "").toLowerCase().includes("windows");
    const rate = (windows ? WINDOWS : LINUX)[family(type)] ?? LINUX[family(type)] ?? 0.05;
    const m = metrics.get(id) ?? { charged: 0, surplusNow: 0, cpu: [] };
    const avgCpu = m.cpu.length ? m.cpu.reduce((a, b) => a + b, 0) / m.cpu.length : undefined;
    const cost = (m.charged / 60) * rate;
    const mode = modes.get(id) ?? "unknown";
    return {
      Instance: id,
      Name: inst.Tags?.find((t) => t.Key === "Name")?.Value ?? "",
      Type: type,
      Credits: mode,
      AvgCpu: avgCpu === undefined ? "-" : `${avgCpu.toFixed(1)}%`,
      CreditsCharged: Math.round(m.charged),
      Cost: `$${cost.toFixed(2)}`,
      SurplusNow: Math.round(m.surplusNow),
      Advice: advise(mode, m.charged, avgCpu),
      cost,
    };
  });
  rows.sort((a, b) => b.cost - a.cost);
  console.log(`\n${region}: burstable instances, surplus credits charged over the last ${days} days`);
  console.table(rows.map(({ cost: _cost, ...visible }) => visible));
  const total = rows.reduce((sum, r) => sum + r.cost, 0);
  const unlimited = rows.filter((r) => r.Credits === "unlimited").length;
  console.log(`${unlimited} of ${rows.length} in unlimited mode. Surplus credit charges: $${total.toFixed(2)} in ${days} days.`);

  if (!apply) return;
  const chosen = rows.filter((r) => applyIds.has(r.Instance) && r.Credits === "unlimited");
  if (chosen.length === 0) {
    console.log("Nothing to apply: none of --instance-ids is an unlimited instance in this region.");
    return;
  }
  for (const r of chosen) {
    if (r.SurplusNow > 0) console.log(`${r.Instance}: ${r.SurplusNow} spent surplus credits will be charged when it switches`);
  }
  const res = await ec2.send(
    new ModifyInstanceCreditSpecificationCommand({
      InstanceCreditSpecifications: chosen.map((r) => ({ InstanceId: r.Instance, CpuCredits: "standard" })),
    }),
  );
  for (const ok of res.SuccessfulInstanceCreditSpecifications ?? []) console.log(`${ok.InstanceId}: now standard`);
  for (const bad of res.UnsuccessfulInstanceCreditSpecifications ?? []) {
    console.error(`${bad.InstanceId}: ${bad.Error?.Code} ${bad.Error?.Message ?? ""}`);
  }
}

async function main(): Promise<void> {
  if (apply && applyIds.size === 0) {
    console.error("--apply needs --instance-ids i-...,i-... (the script never changes instances you didn't name)");
    process.exit(2);
  }
  for (const region of regions) {
    try {
      await scanRegion(region);
    } catch (err) {
      console.error(`${region}: ${errorText(err)}`);
    }
  }
}

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

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

# Report only
AWS_PROFILE=readonly npx tsx find-unlimited-mode-charges.ts --regions us-east-1,eu-west-1 --days 30

# Switch one instance to standard after its owner agrees
AWS_PROFILE=ec2-admin npx tsx find-unlimited-mode-charges.ts --regions us-east-1 --apply --instance-ids i-0b2

us-east-1: burstable instances, surplus credits charged over the last 30 days
┌─────────┬──────────┬───────────────────┬─────────────┬─────────────┬─────────┬────────────────┬──────────┬────────────┬──────────────────────────────────────────────────────────────────────────────────┐
│ (index) │ Instance │ Name              │ Type        │ Credits     │ AvgCpu  │ CreditsCharged │ Cost     │ SurplusNow │ Advice                                                                           │
├─────────┼──────────┼───────────────────┼─────────────┼─────────────┼─────────┼────────────────┼──────────┼────────────┼──────────────────────────────────────────────────────────────────────────────────┤
│ 0       │ 'i-0a1'  │ 'reports-worker'  │ 't3.large'  │ 'unlimited' │ '90.0%' │ 51840          │ '$43.20' │ 96         │ 'busy all day: price a larger size or a non-burstable type'                      │
│ 1       │ 'i-0c3'  │ 'win-rdp-gateway' │ 't3.xlarge' │ 'unlimited' │ '52.0%' │ 3000           │ '$4.80'  │ 12         │ 'busy all day: price a larger size or a non-burstable type'                      │
│ 2       │ 'i-0b2'  │ 'jenkins-agent'   │ 't3.medium' │ 'unlimited' │ '26.0%' │ 720            │ '$0.60'  │ 50         │ 'short bursts: compare the charge with one size up before switching to standard' │
│ 3       │ 'i-0d4'  │ 'bastion'         │ 't4g.small' │ 'unlimited' │ '4.0%'  │ 0              │ '$0.00'  │ 0          │ 'no surplus charges: unlimited costs nothing extra here'                         │
│ 4       │ 'i-0e5'  │ 'legacy-cron'     │ 't2.micro'  │ 'standard'  │ '7.0%'  │ 0              │ '$0.00'  │ 0          │ 'standard: throttled to baseline when credits run out'                           │
└─────────┴──────────┴───────────────────┴─────────────┴─────────────┴─────────┴────────────────┴──────────┴────────────┴──────────────────────────────────────────────────────────────────────────────────┘
4 of 5 in unlimited mode. Surplus credit charges: $48.60 in 30 days.