Find Idle ElastiCache Clusters

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ListCaches",
      "Effect": "Allow",
      "Action": [
        "elasticache:DescribeCacheClusters",
        "elasticache:DescribeServerlessCaches"
      ],
      "Resource": "*"
    },
    {
      "Sid": "ReadCacheMetrics",
      "Effect": "Allow",
      "Action": "cloudwatch:GetMetricData",
      "Resource": "*"
    }
  ]
}

// find-idle-elasticache.ts
// Finds ElastiCache node-based clusters and serverless caches that served no reads or writes over the last N days,
// using CloudWatch command and connection metrics. Read-only: it never deletes, snapshots or modifies a cache.
// Usage: npx tsx find-idle-elasticache.ts [--regions us-east-1,eu-west-1] [--days 14] [--csv idle-caches.csv]
import { writeFileSync } from "node:fs";
import {
  ElastiCacheClient,
  paginateDescribeCacheClusters,
  paginateDescribeServerlessCaches,
} from "@aws-sdk/client-elasticache";
import { CloudWatchClient, GetMetricDataCommand, 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 = Number(flag("--days") ?? 14);
const csvPath = flag("--csv");

// ElastiCache keeps a few connections open to monitor each node: 4 to 6 for Valkey/Redis OSS.
const MONITORING_CONNECTIONS = 6;

// One thing to measure: a node (CacheClusterId + CacheNodeId) or a serverless cache (clusterId).
interface Target {
  group: string; // replication group, cluster or serverless cache name
  kind: "valkey/redis" | "memcached" | "serverless";
  dimensions: { Name: string; Value: string }[];
  nodeType: string;
  memcached: boolean; // Memcached reports CmdGet/CmdSet instead of GetTypeCmds/SetTypeCmds
}

interface Row {
  Region: string;
  Cache: string;
  Kind: string;
  NodeType: string;
  Nodes: number;
  Reads: number;
  Writes: number;
  MaxConnections: number;
  Verdict: string;
}

async function listTargets(region: string): Promise<Target[]> {
  const ec = new ElastiCacheClient({ region });
  const targets: Target[] = [];
  for await (const page of paginateDescribeCacheClusters({ client: ec }, { ShowCacheNodeInfo: true, MaxRecords: 100 })) {
    for (const c of page.CacheClusters ?? []) {
      const id = c.CacheClusterId ?? "";
      const kind = c.Engine === "memcached" ? "memcached" : "valkey/redis";
      for (const node of c.CacheNodes ?? []) {
        targets.push({
          group: c.ReplicationGroupId ?? id,
          kind,
          nodeType: c.CacheNodeType ?? "",
          memcached: kind === "memcached",
          dimensions: [{ Name: "CacheClusterId", Value: id }, { Name: "CacheNodeId", Value: node.CacheNodeId ?? "0001" }],
        });
      }
    }
  }
  for await (const page of paginateDescribeServerlessCaches({ client: ec }, { MaxResults: 50 })) {
    for (const s of page.ServerlessCaches ?? []) {
      const name = s.ServerlessCacheName ?? "";
      targets.push({
        group: name,
        kind: "serverless",
        nodeType: `serverless ${s.Engine ?? ""}`,
        memcached: s.Engine === "memcached",
        dimensions: [{ Name: "clusterId", Value: name }], // serverless caches use clusterId = cache name
      });
    }
  }
  return targets;
}

// Read and write command metrics differ by engine, for node-based and serverless caches alike.
function metricNames(t: Target): { reads: string; writes: string } {
  return t.memcached ? { reads: "CmdGet", writes: "CmdSet" } : { reads: "GetTypeCmds", writes: "SetTypeCmds" };
}

async function measure(region: string, targets: Target[]): Promise<Map<number, { reads: number; writes: number; conns: number }>> {
  const cw = new CloudWatchClient({ region });
  const end = new Date();
  const start = new Date(end.getTime() - days * 86_400_000);
  const queries: MetricDataQuery[] = targets.flatMap((t, i) => {
    const { reads, writes } = metricNames(t);
    const q = (id: string, MetricName: string, Stat: string): MetricDataQuery => ({
      Id: `${id}${i}`,
      MetricStat: { Metric: { Namespace: "AWS/ElastiCache", MetricName, Dimensions: t.dimensions }, Period: 86_400, Stat },
      ReturnData: true,
    });
    return [q("r", reads, "Sum"), q("w", writes, "Sum"), q("c", "CurrConnections", "Maximum")];
  });

  const totals = new Map<number, { reads: number; writes: number; conns: number }>();
  targets.forEach((_, i) => totals.set(i, { reads: 0, writes: 0, conns: 0 }));
  for (let n = 0; n < queries.length; n += 500) { // GetMetricData accepts up to 500 queries per call
    let NextToken: string | undefined;
    do {
      const res = await cw.send(new GetMetricDataCommand({
        MetricDataQueries: queries.slice(n, n + 500), StartTime: start, EndTime: end, NextToken,
      }));
      for (const r of res.MetricDataResults ?? []) {
        const [kind, idx] = [r.Id?.[0], Number(r.Id?.slice(1))];
        const t = totals.get(idx);
        if (!t) continue;
        const values = r.Values ?? [];
        if (kind === "r") t.reads += values.reduce((a, b) => a + b, 0);
        if (kind === "w") t.writes += values.reduce((a, b) => a + b, 0);
        if (kind === "c") t.conns = Math.max(t.conns, ...values);
      }
      NextToken = res.NextToken;
    } while (NextToken);
  }
  return totals;
}

async function scanRegion(region: string): Promise<Row[]> {
  const targets = await listTargets(region);
  if (!targets.length) return [];
  const totals = await measure(region, targets);
  const byGroup = new Map<string, Row>();
  targets.forEach((t, i) => {
    const m = totals.get(i) ?? { reads: 0, writes: 0, conns: 0 };
    const row = byGroup.get(t.group) ?? {
      Region: region, Cache: t.group, Kind: t.kind, NodeType: t.nodeType, Nodes: 0, Reads: 0, Writes: 0, MaxConnections: 0, Verdict: "",
    };
    if (t.kind !== "serverless") row.Nodes += 1;
    row.Reads += m.reads;
    row.Writes += m.writes;
    row.MaxConnections = Math.max(row.MaxConnections, m.conns);
    byGroup.set(t.group, row);
  });
  for (const row of byGroup.values()) {
    const commands = row.Reads + row.Writes;
    const noClients = row.Kind === "valkey/redis" ? row.MaxConnections <= MONITORING_CONNECTIONS : row.MaxConnections === 0;
    row.Verdict = commands === 0 ? (noClients ? "IDLE: no commands, no clients" : "IDLE: no commands, connections open")
      : row.Writes === 0 ? "read-only: check data is still refreshed" : "in use";
  }
  return [...byGroup.values()];
}

function toCsv(rows: Row[]): string {
  const cols: (keyof Row)[] = ["Region", "Cache", "Kind", "NodeType", "Nodes", "Reads", "Writes", "MaxConnections", "Verdict"];
  const cell = (v: string | number) => `"${String(v).replace(/"/g, '""')}"`;
  return [cols.join(","), ...rows.map((r) => cols.map((c) => cell(r[c])).join(","))].join("\n") + "\n";
}

async function main(): Promise<void> {
  const rows: Row[] = [];
  for (const region of regions) rows.push(...(await scanRegion(region)));
  rows.sort((a, b) => a.Reads + a.Writes - (b.Reads + b.Writes));
  console.table(rows);
  const idle = rows.filter((r) => r.Verdict.startsWith("IDLE"));
  console.log(`${idle.length} of ${rows.length} caches had no reads or writes in the last ${days} days (${regions.join(", ")})`);
  if (csvPath) {
    writeFileSync(csvPath, toCsv(rows));
    console.log(`Wrote ${rows.length} rows to ${csvPath}`);
  }
  console.log("Report only: no cache was deleted, snapshotted or changed.");
}

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

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

# Last 14 days in two Regions
AWS_PROFILE=readonly npx tsx find-idle-elasticache.ts --regions us-east-1,eu-west-1

# A 30-day window and a CSV for the owning teams
AWS_PROFILE=readonly npx tsx find-idle-elasticache.ts --regions us-east-1 --days 30 --csv idle-caches.csv

┌─────────┬─────────────┬──────────────────┬────────────────┬───────────────────┬───────┬──────────┬────────┬────────────────┬─────────────────────────────────────────────┐
│ (index) │ Region      │ Cache            │ Kind           │ NodeType          │ Nodes │ Reads    │ Writes │ MaxConnections │ Verdict                                     │
├─────────┼─────────────┼──────────────────┼────────────────┼───────────────────┼───────┼──────────┼────────┼────────────────┼─────────────────────────────────────────────┤
│ 0       │ 'us-east-1' │ 'legacy-session' │ 'valkey/redis' │ 'cache.r7g.large' │ 2     │ 0        │ 0      │ 6              │ 'IDLE: no commands, no clients'             │
│ 1       │ 'us-east-1' │ 'feature-flags'  │ 'serverless'   │ 'serverless redis'│ 0     │ 0        │ 0      │ 3              │ 'IDLE: no commands, connections open'       │
│ 2       │ 'eu-west-1' │ 'geo-lookup'     │ 'valkey/redis' │ 'cache.m7g.large' │ 3     │ 1842210  │ 0      │ 41             │ 'read-only: check data is still refreshed'  │
│ 3       │ 'us-east-1' │ 'api-cache'      │ 'valkey/redis' │ 'cache.r7g.large' │ 3     │ 98412733 │ 212004 │ 388            │ 'in use'                                    │
└─────────┴─────────────┴──────────────────┴────────────────┴───────────────────┴───────┴──────────┴────────┴────────────────┴─────────────────────────────────────────────┘
2 of 4 caches had no reads or writes in the last 14 days (us-east-1, eu-west-1)
Report only: no cache was deleted, snapshotted or changed.