I Tried Implementing Lambda-less Disk Monitoring with Step Functions + JSONata Using Kiro with Opus 4.6 Support

# ディスク使用量監視 Step Functions 実装計画書 v4

## 変更履歴

| バージョン | 変更内容 |
|---|---|
| v3 | 初版。ListMetrics による全ディスク自動検出、二重 Map 構造 |
| v4 | 実装との差分を反映。空配列ガード、予測ロジック改善、MetricPeriod パラメータ追加 |

## 1. 概要

CloudWatch Agent が収集する HDD 使用率カスタムメトリクスを Step Functions（SDK 統合 + JSONata）で監視し、ディスク枯渇リスクを検知して SNS に構造化 JSON で通知する。Lambda レスで実現する。

監視ロジック:
- ListMetrics で各インスタンスの全ディスク（Dimension 組み合わせ）を自動検出
- 過去14日間の日次データから最大日次増分を特定
- その増分が継続した場合に3日以内にディスクフル（100%）に到達するかを判定
- 現在値が閾値（デフォルト95%）以上の場合は即時アラート

## 2. 前提条件

- CloudWatch Agent が対象 EC2 に設定済み（名前空間: `CWAgent`、メトリクス: `disk_used_percent`）
- 監視対象 EC2 に識別用タグが付与されている（例: `Monitor:DiskCheck`）
- SNS トピックが作成済み
- CWAgent の Dimensions 設定（append_dimensions 等）は問わない。ListMetrics で自動検出するため

## 3. アーキテクチャ

EventBridge Scheduler (定期実行: rate(1 hour))
    |
    v
Step Functions (デフォルト: EXPRESS / 引数で STANDARD 切替可)
    |
    +-- [1] EC2 DescribeInstances (タグフィルタ + running のみ)
    |
    +-- [2] Pass/JSONata (インスタンスID・名前を配列に整形)
    |
    +-- [2.5] Choice (インスタンス0件なら正常終了)
    |
    +-- [3] Map (並列: インスタンスごと)
    |       |
    |       +-- [3-1] CloudWatch ListMetrics (全ディスクの Dimension 組み合わせを取得)
    |       |
    |       +-- [3-2] Pass/JSONata (Dimension 組み合わせを配列に整形)
    |       |
    |       +-- [3-2.5] Choice (ディスク0件なら空結果で終了)
    |       |
    |       +-- [3-3] Map (並列: ディスクごと)
    |       |       +-- CloudWatch GetMetricStatistics (過去14日分、Period はパラメータ)
    |       |       +-- Pass/JSONata (全ペア比較で最大増分算出、枯渇リスク判定)
    |       |
    |       +-- Output で instanceId/instanceName/results を集約
    |
    +-- [4] Pass/JSONata (CRITICAL/WARNING/OK に振り分け、レポート生成)
    |
    +-- [5] Choice -- CRITICAL or WARNING あり -- SNS Publish
                   -- なし -- 正常終了

Express モード時は CloudWatch Logs に出力（14日保持）

## 4. ステートマシン定義

| ステート | タイプ | 処理内容 |
|---|---|---|
| GetInstances | Task (SDK: EC2) | DescribeInstances。タグフィルタ + instance-state-name=running で監視対象を取得 |
| ExtractInstanceList | Pass (JSONata) | インスタンスID・Name タグを配列に整形 |
| CheckHasInstances | Choice | インスタンス0件なら NoAction へ。Map の空配列エラーを防止 |
| CheckEachInstance | Map (並列) | 各インスタンスに対して以下を実行（外側 Map）。ToleratedFailurePercentage: 100 |
| -- ListDiskMetrics | Task (SDK: CloudWatch) | ListMetrics で該当インスタンスの全ディスク Dimension を取得 |
| -- ExtractDimensions | Pass (JSONata) | Dimension 組み合わせを配列に整形。metrics が null/空の場合は空配列を返す |
| -- CheckHasDisks | Choice | ディスク0件なら NoDisksFound へ。Map の空配列エラーを防止 |
| -- NoDisksFound | Pass | 空の results を返して終了 |
| -- CheckEachDisk | Map (並列) | 各ディスクに対して以下を実行（内側 Map）。ToleratedFailurePercentage: 100 |
| ---- GetDiskMetrics | Task (SDK: CloudWatch) | GetMetricStatistics で過去 LookbackDays 分を取得。Period は MetricPeriod パラメータ |
| ---- EvaluateRisk | Pass (JSONata) | 全ペア比較で最大増分を算出、枯渇リスク判定 |
| AggregateReport | Pass (JSONata) | CRITICAL/WARNING/OK に振り分け、JSON レポート生成 |
| HasAlerts | Choice | criticalCount > 0 or warningCount > 0 |
| SendReport | Task (SDK: SNS) | JSON レポートを Publish。Subject: "Disk Usage Alert" |
| NoAction | Succeed | 正常終了 |

## 5. CloudWatch API 仕様

### 5.1 ListMetrics（ディスク自動検出）

インスタンスあたり1回。そのインスタンスが持つ全ディスクの Dimension 組み合わせを取得。

| パラメータ | 値 |
|---|---|
| Namespace | CWAgent |
| MetricName | disk_used_percent |
| Dimensions | [{"Name": "InstanceId", "Value": "<対象ID>"}] |
| RecentlyActive | PT3H |

RecentlyActive: PT3H により、直近3時間以内にデータ送信があるディスクのみを返す。

### 5.2 GetMetricStatistics（トレンドデータ取得）

ディスクあたり1回。ListMetrics で取得した完全な Dimensions をそのまま指定。

| パラメータ | 値 |
|---|---|
| Namespace | CWAgent |
| MetricName | disk_used_percent |
| Period | MetricPeriod パラメータ（デフォルト: 86400秒 = 1日） |
| Statistics | ["Average"] |
| StartTime | 現在 - LookbackDays |
| EndTime | 現在 |
| Dimensions | ListMetrics のレスポンスをそのまま使用 |

### 5.3 コスト見積もり

10台 x 平均2ディスク/台の場合:
- ListMetrics: 10回/実行
- GetMetricStatistics: 20回/実行
- 合計: 30回/実行 x 24回/日 x 30日 = 21,600回/月 -> 約 $0.22/月

## 6. 予測ロジック（JSONata）

### 6.1 処理フロー

1. $reduce で最新データポイントを取得（$sort は Step Functions の JSONata で不安定なため不使用）
2. データポイントが2未満 -> 予測不能（INSUFFICIENT_DATA）
3. 全ペア比較（$map + $reduce）で、任意の2点間の最大増分とその日付を算出
4. 最大増分が0以下 -> 増加傾向なし（daysUntilFull: null）
5. daysUntilFull = (100 - currentUsage) / maxDailyIncrease

### 6.2 判定基準

| 条件 | ステータス | 優先度 |
|---|---|---|
| currentUsage >= thresholdPercent | CRITICAL | 1（最優先） |
| データポイント < 2 | INSUFFICIENT_DATA | 2 |
| daysUntilFull <= predictionDays | WARNING | 3 |
| 上記以外 | OK | 4 |

### 6.3 コーナーケース対応

| ケース | 挙動 |
|---|---|
| 新規インスタンス（データ1点以下） | INSUFFICIENT_DATA。アラート対象外 |
| ディスク掃除で使用率が下がった日がある | 全ペア比較で正の増分のみを対象 |
| 全日で使用率が横ばいまたは減少 | 正の増分なし -> daysUntilFull: null -> OK |
| 現在値が既に100% | CRITICAL（閾値超過で即時判定、データ不足でも発動） |
| インスタンスにディスクメトリクスなし | 空の results を返す（NoDisksFound ステート） |
| 監視対象インスタンスが0台 | CheckHasInstances で正常終了 |

### 6.4 EvaluateRisk 出力フィールド

| フィールド | 型 | 説明 |
|---|---|---|
| path | string | マウントパス（例: /, /data, C:） |
| device | string | デバイス名（例: nvme0n1p1, C:） |
| fstype | string | ファイルシステム（例: xfs, NTFS） |
| currentUsage | number | 現在の使用率（小数点1桁） |
| maxDailyIncrease | number/null | 最大日次増分（小数点2桁）。データ不足時は null |
| daysUntilFull | number/null | 100%到達までの残日数（小数点1桁）。増加傾向なしは null |
| worstDay | string/null | 最大増分が発生した日付（YYYY-MM-DD）。増加傾向なしは null |
| status | string | CRITICAL / WARNING / INSUFFICIENT_DATA / OK |

## 7. SNS 通知メッセージ

Subject: Disk Usage Alert

json
{
  "subject": "Disk Usage Alert",
  "timestamp": "2026-02-07T08:47:49.163Z",
  "summary": {
    "totalInstances": 10,
    "totalDisks": 18,
    "criticalCount": 1,
    "warningCount": 2,
    "okCount": 15
  },
  "critical": [
    {
      "instanceId": "i-0123456789abcdef0",
      "instanceName": "db-server",
      "path": "/data",
      "device": "nvme1n1",
      "fstype": "xfs",
      "currentUsage": 96.2,
      "maxDailyIncrease": 2.8,
      "daysUntilFull": 1.4,
      "worstDay": "2026-02-03"
    }
  ],
  "warning": [
    {
      "instanceId": "i-0abcdef1234567890",
      "instanceName": "app-server",
      "path": "/",
      "device": "nvme0n1p1",
      "fstype": "xfs",
      "currentUsage": 87.3,
      "maxDailyIncrease": 5.1,
      "daysUntilFull": 2.5,
      "worstDay": "2026-02-05"
    }
  ]
}

## 8. CloudFormation パラメータ

| パラメータ | デフォルト | 説明 |
|---|---|---|
| StateMachineType | EXPRESS | EXPRESS or STANDARD |
| TagKey | Monitor | 監視対象タグキー |
| TagValue | DiskCheck | 監視対象タグ値 |
| ThresholdPercent | 95 | CRITICAL 判定閾値（%） |
| PredictionDays | 3 | WARNING 判定日数 |
| LookbackDays | 14 | トレンド分析の過去参照日数 |
| MetricPeriod | 86400 | メトリクス集約期間（秒）。テスト時は 300 に設定 |
| SnsTopicArn | （必須） | 通知先 SNS トピック ARN |
| ScheduleExpression | rate(1 hour) | 実行スケジュール |

AWSTemplateFormatVersion: '2010-09-09'
Description: Disk Usage Monitor - Step Functions (Lambdaless / JSONata)

Parameters:
  StateMachineType:
    Type: String
    Default: EXPRESS
    AllowedValues: [EXPRESS, STANDARD]
  TagKey:
    Type: String
    Default: Monitor
  TagValue:
    Type: String
    Default: DiskCheck
  ThresholdPercent:
    Type: Number
    Default: 95
  PredictionDays:
    Type: Number
    Default: 3
  LookbackDays:
    Type: Number
    Default: 14
  SnsTopicArn:
    Type: String
    AllowedPattern: arn:aws:sns:.+
  MetricPeriod:
    Type: Number
    Default: 86400
    Description: Metric aggregation period in seconds (86400=daily, 300=5min for testing)
  ScheduleExpression:
    Type: String
    Default: rate(1 hour)

Conditions:
  IsExpress: !Equals [!Ref StateMachineType, EXPRESS]

Resources:
  StateMachineLogGroup:
    Type: AWS::Logs::LogGroup
    Condition: IsExpress
    Properties:
      LogGroupName: !Sub /aws/vendedlogs/states/${AWS::StackName}
      RetentionInDays: 14

  StateMachineRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: states.amazonaws.com
            Action: sts:AssumeRole
      Policies:
        - PolicyName: DiskMonitorPolicy
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - ec2:DescribeInstances
                  - cloudwatch:ListMetrics
                  - cloudwatch:GetMetricStatistics
                Resource: '*'
              - Effect: Allow
                Action: sns:Publish
                Resource: !Ref SnsTopicArn
              - !If
                - IsExpress
                - Effect: Allow
                  Action:
                    - logs:CreateLogDelivery
                    - logs:GetLogDelivery
                    - logs:UpdateLogDelivery
                    - logs:DeleteLogDelivery
                    - logs:ListLogDeliveries
                    - logs:PutResourcePolicy
                    - logs:DescribeResourcePolicies
                    - logs:DescribeLogGroups
                  Resource: '*'
                - !Ref AWS::NoValue

  SchedulerRole:
    Type: AWS::IAM::Role
    Properties:
      AssumeRolePolicyDocument:
        Version: '2012-10-17'
        Statement:
          - Effect: Allow
            Principal:
              Service: scheduler.amazonaws.com
            Action: sts:AssumeRole
      Policies:
        - PolicyName: InvokeStateMachine
          PolicyDocument:
            Version: '2012-10-17'
            Statement:
              - Effect: Allow
                Action:
                  - states:StartExecution
                  - states:StartSyncExecution
                Resource: !GetAtt StateMachine.Arn

  StateMachine:
    Type: AWS::StepFunctions::StateMachine
    Properties:
      StateMachineName: !Sub ${AWS::StackName}
      StateMachineType: !Ref StateMachineType
      RoleArn: !GetAtt StateMachineRole.Arn
      LoggingConfiguration: !If
        - IsExpress
        - Level: ALL
          IncludeExecutionData: true
          Destinations:
            - CloudWatchLogsLogGroup:
                LogGroupArn: !GetAtt StateMachineLogGroup.Arn
        - !Ref AWS::NoValue
      DefinitionSubstitutions:
        TagKey: !Ref TagKey
        TagValue: !Ref TagValue
        ThresholdPercent: !Ref ThresholdPercent
        PredictionDays: !Ref PredictionDays
        LookbackDays: !Ref LookbackDays
        MetricPeriod: !Ref MetricPeriod
        SnsTopicArn: !Ref SnsTopicArn
      Definition:
        QueryLanguage: JSONata
        Comment: Disk Usage Monitor - Lambdaless
        StartAt: GetInstances
        States:
          GetInstances:
            Type: Task
            Resource: arn:aws:states:::aws-sdk:ec2:describeInstances
            Arguments:
              Filters:
                - Name: "tag:${TagKey}"
                  Values:
                    - "${TagValue}"
                - Name: instance-state-name
                  Values:
                    - running
            Next: ExtractInstanceList

          ExtractInstanceList:
            Type: Pass
            Output: >-
              {% [$states.input.Reservations[].Instances[].{
                'instanceId': InstanceId,
                'instanceName': Tags[Key='Name'].Value
              }] %}
            Next: CheckHasInstances

          CheckHasInstances:
            Type: Choice
            Choices:
              - Condition: "{% $count($states.input) > 0 %}"
                Next: CheckEachInstance
            Default: NoAction

          CheckEachInstance:
            Type: Map
            Items: "{% $states.input %}"
            MaxConcurrency: 10
            ToleratedFailurePercentage: 100
            ItemProcessor:
              ProcessorConfig:
                Mode: INLINE
              StartAt: ListDiskMetrics
              States:
                ListDiskMetrics:
                  Type: Task
                  Resource: arn:aws:states:::aws-sdk:cloudwatch:listMetrics
                  Arguments:
                    Namespace: CWAgent
                    MetricName: disk_used_percent
                    Dimensions:
                      - Name: InstanceId
                        Value: "{% $states.input.instanceId %}"
                    RecentlyActive: PT3H
                  Output:
                    instanceId: "{% $states.input.instanceId %}"
                    instanceName: "{% $states.input.instanceName %}"
                    metrics: "{% $states.result.Metrics %}"
                  Next: ExtractDimensions

                ExtractDimensions:
                  Type: Pass
                  Output:
                    instanceId: "{% $states.input.instanceId %}"
                    instanceName: "{% $states.input.instanceName %}"
                    disks: >-
                      {% $states.input.metrics
                        ? [$states.input.metrics.{ 'dimensions': Dimensions }]
                        : [] %}
                  Next: CheckHasDisks

                CheckHasDisks:
                  Type: Choice
                  Choices:
                    - Condition: "{% $count($states.input.disks) > 0 %}"
                      Next: CheckEachDisk
                  Default: NoDisksFound

                NoDisksFound:
                  Type: Pass
                  Output:
                    instanceId: "{% $states.input.instanceId %}"
                    instanceName: "{% $states.input.instanceName %}"
                    results: []
                  End: true

                CheckEachDisk:
                  Type: Map
                  Items: >-
                    {% [$states.input.disks.{
                      'dimensions': dimensions,
                      'instanceId': $states.input.instanceId,
                      'instanceName': $states.input.instanceName
                    }] %}
                  MaxConcurrency: 5
                  ToleratedFailurePercentage: 100
                  ItemProcessor:
                    ProcessorConfig:
                      Mode: INLINE
                    StartAt: GetDiskMetrics
                    States:
                      GetDiskMetrics:
                        Type: Task
                        Resource: arn:aws:states:::aws-sdk:cloudwatch:getMetricStatistics
                        Arguments:
                          Namespace: CWAgent
                          MetricName: disk_used_percent
                          Dimensions: "{% $states.input.dimensions %}"
                          StartTime: >-
                            {% $fromMillis($millis() - ${LookbackDays} * 86400000) %}
                          EndTime: "{% $fromMillis($millis()) %}"
                          Period: "{% $number('${MetricPeriod}') %}"
                          Statistics:
                            - Average
                        Output:
                          dimensions: "{% $states.input.dimensions %}"
                          datapoints: "{% $states.result.Datapoints %}"
                        Next: EvaluateRisk

                      EvaluateRisk:
                        Type: Pass
                        Output: >-
                          {% (
                            $dims := $states.input.dimensions;
                            $path := ($dims[Name='path']).Value;
                            $device := ($dims[Name='device']).Value;
                            $fstype := ($dims[Name='fstype']).Value;
                            $dp := $states.input.datapoints;
                            $cnt := $count($dp);
                            $latest := $cnt > 0
                              ? $reduce($dp, function($acc, $v) {
                                  $v.Timestamp > $acc.Timestamp ? $v : $acc
                                })
                              : {'Average': 0};
                            $current := $latest.Average;
                            $prediction := $cnt < 2
                              ? { 'daysUntilFull': null, 'maxDailyIncrease': null, 'worstDay': null }
                              : (
                                $maxes := $map($dp, function($a) {
                                  $reduce($dp, function($best, $b) {
                                    ($a.Timestamp > $b.Timestamp)
                                      ? ( $d := $a.Average - $b.Average;
                                          $d > $best.delta
                                            ? {'delta': $d, 'date': $a.Timestamp}
                                            : $best )
                                      : $best
                                  }, {'delta': 0, 'date': ''})
                                });
                                $worst := $reduce($maxes, function($acc, $m) {
                                  $m.delta > $acc.delta ? $m : $acc
                                });
                                $worst.delta > 0
                                  ? {
                                    'daysUntilFull': $round((100 - $current) / $worst.delta, 1),
                                    'maxDailyIncrease': $round($worst.delta, 2),
                                    'worstDay': $substringBefore($worst.date, 'T')
                                  }
                                  : { 'daysUntilFull': null, 'maxDailyIncrease': 0, 'worstDay': null }
                              );
                            $status := $current >= ${ThresholdPercent}
                              ? 'CRITICAL'
                              : $cnt < 2
                                ? 'INSUFFICIENT_DATA'
                                : $prediction.daysUntilFull != null
                                  ? ($prediction.daysUntilFull <= ${PredictionDays}
                                      ? 'WARNING' : 'OK')
                                  : 'OK';
                            {
                              'path': $path,
                              'device': $device,
                              'fstype': $fstype,
                              'currentUsage': $round($current, 1),
                              'maxDailyIncrease': $prediction.maxDailyIncrease,
                              'daysUntilFull': $prediction.daysUntilFull,
                              'worstDay': $prediction.worstDay,
                              'status': $status
                            }
                          ) %}
                        End: true
                  Output:
                    instanceId: "{% $states.input.instanceId %}"
                    instanceName: "{% $states.input.instanceName %}"
                    results: "{% $states.result %}"
                  End: true
            Next: AggregateReport

          AggregateReport:
            Type: Pass
            Output: >-
              {% (
                $all := $states.input;
                $allDisks := $all.results[];
                {
                  'subject': 'Disk Usage Alert',
                  'timestamp': $now(),
                  'summary': {
                    'totalInstances': $count($all),
                    'totalDisks': $count($allDisks),
                    'criticalCount': $count($filter($allDisks, function($d) { $d.status = 'CRITICAL' })),
                    'warningCount': $count($filter($allDisks, function($d) { $d.status = 'WARNING' })),
                    'okCount': $count($filter($allDisks, function($d) { $d.status = 'OK' }))
                  },
                  'critical': $all.(
                    $inst := $;
                    results[status='CRITICAL'].{
                      'instanceId': $inst.instanceId,
                      'instanceName': $inst.instanceName,
                      'path': path, 'device': device, 'fstype': fstype,
                      'currentUsage': currentUsage,
                      'maxDailyIncrease': maxDailyIncrease,
                      'daysUntilFull': daysUntilFull,
                      'worstDay': worstDay
                    }
                  )[],
                  'warning': $all.(
                    $inst := $;
                    results[status='WARNING'].{
                      'instanceId': $inst.instanceId,
                      'instanceName': $inst.instanceName,
                      'path': path, 'device': device, 'fstype': fstype,
                      'currentUsage': currentUsage,
                      'maxDailyIncrease': maxDailyIncrease,
                      'daysUntilFull': daysUntilFull,
                      'worstDay': worstDay
                    }
                  )[]
                }
              ) %}
            Next: HasAlerts

          HasAlerts:
            Type: Choice
            Choices:
              - Condition: >-
                  {% $states.input.summary.criticalCount > 0
                    or $states.input.summary.warningCount > 0 %}
                Next: SendReport
            Default: NoAction

          SendReport:
            Type: Task
            Resource: arn:aws:states:::aws-sdk:sns:publish
            Arguments:
              TopicArn: "${SnsTopicArn}"
              Subject: "{% $states.input.subject %}"
              Message: "{% $string($states.input) %}"
            End: true

          NoAction:
            Type: Succeed

  Scheduler:
    Type: AWS::Scheduler::Schedule
    Properties:
      Name: !Sub ${AWS::StackName}-scheduler
      ScheduleExpression: !Ref ScheduleExpression
      FlexibleTimeWindow:
        Mode: 'OFF'
      Target:
        Arn: !GetAtt StateMachine.Arn
        RoleArn: !GetAtt SchedulerRole.Arn
        Input: '{}'

Outputs:
  StateMachineArn:
    Value: !GetAtt StateMachine.Arn
  StateMachineType:
    Value: !Ref StateMachineType
  LogGroupName:
    Condition: IsExpress
    Value: !Ref StateMachineLogGroup