template.yaml

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: >
  (P9E-MONITOR) -Personalize monitoring tools including CloudWatch metrics, alarms, and dashboard; optional automated cost optimization

Metadata:
  AWS::ServerlessRepo::Application:
    Name: Amazon-Personalize-Monitor
    Description: >
      Creates a CloudWatch dashboard for monitoring the utilization of Amazon Personalize
      campaigns and recommenders; creates CloudWatch alarms based on a user-defined threshold; and
      includes automated cost optimization actions.
    Author: AWS Applied AI - Personalize
    SpdxLicenseId: MIT-0
    LicenseUrl: LICENSE
    ReadmeUrl: README-SAR.md
    Labels: ['Personalize', 'CloudWatch', 'Monitoring']
    HomePageUrl: https://github.com/aws-samples/amazon-personalize-monitor
    SemanticVersion: 1.2.1
    SourceCodeUrl: https://github.com/aws-samples/amazon-personalize-monitor

  AWS::CloudFormation::Interface:
    ParameterGroups:
      - Label:
          default: "Amazon Personalize inference resources to monitor"
        Parameters:
          - CampaignARNs
          - RecommenderARNs
          - Regions
      - Label:
          default: "CloudWatch alarm configuration"
        Parameters:
          - AutoCreateUtilizationAlarms
          - UtilizationThresholdAlarmLowerBound
          - AutoCreateIdleAlarms
          - IdleThresholdHours
      - Label:
          default: "Cost optimization actions"
        Parameters:
          - AutoAdjustMinTPS
          - AutoDeleteOrStopIdleResources
      - Label:
          default: "Notifications"
        Parameters:
          - NotificationEndpoint
    ParameterLabels:
      CampaignARNs:
        default: "Personalize campaign ARNs to monitor"
      RecommenderARNs:
        default: "Personalize recommender ARNs to monitor"
      Regions:
        default: "AWS regions to monitor"
      AutoCreateUtilizationAlarms:
        default: "Automatically create campaign/recommender utilization CloudWatch alarms?"
      UtilizationThresholdAlarmLowerBound:
        default: "Campaign/recommender utilization alarm lower bound threshold"
      AutoCreateIdleAlarms:
        default: "Automatically create idle campaign/recommender CloudWatch alarms?"
      IdleThresholdHours:
        default: "Number of hours without requests to be considered idle"
      AutoDeleteOrStopIdleResources:
        default: "Automatically delete idle campaigns and stop idle recommenders in idle alarm state?"
      AutoAdjustMinTPS:
        default: "Automatically adjust/lower minProvisionedTPS/minRecommendationRequestsPerSecond for campaigns/recommenders in utilization alarm state?"
      NotificationEndpoint:
        default: "Email address to receive notifications"

Parameters:
  CampaignARNs:
    Type: String
    Description: >
      Comma separated list of Amazon Personalize campaign ARNs to monitor or 'all' to dynamically monitor all active campaigns.
    Default: 'all'

  RecommenderARNs:
    Type: String
    Description: >
      Comma separated list of Amazon Personalize recommender ARNs to monitor or 'all' to dynamically monitor all active recommenders.
    Default: 'all'

  Regions:
    Type: String
    Description: >
      Comma separated list of AWS region names. When using 'all' for CampaignARNs or RecommenderARNs, this parameter can be used
      to control the region(s) where the Personalize Monitor looks for active Personalize campaigns and recommenders. When not specified,
      the region where you deploy this application will be used.

  AutoCreateUtilizationAlarms:
    Type: String
    Description: >
      Whether to automatically create CloudWatch alarms for campaign/recommender utilization for monitored campaigns/recommenders. Valid values: Yes/No.
    AllowedValues:
      - 'Yes'
      - 'No'
    Default: 'Yes'

  UtilizationThresholdAlarmLowerBound:
    Type: Number
    Description: >
      Utilization alarm threshold value (in percent). When a monitored campaign's or recommender's utilization falls below this value,
      the alarm state will be set to ALARM. Valid values: 0-1000 (integer).
    MinValue: 0
    MaxValue: 1000
    Default: 100

  AutoAdjustMinTPS:
    Type: String
    Description: >
      Whether to automatically adjust minProvisionedTPS (campaigns) or minRecommendationRequestsPerSecond (recommenders) down to lowest average TPS over
      rolling 24 hour window. The minProvisionedTPS/minRecommendationRequestsPerSecond will never be increased. Valid values: Yes/No.
    AllowedValues:
      - 'Yes'
      - 'No'
    Default: 'Yes'

  AutoCreateIdleAlarms:
    Type: String
    Description: >
      Whether to automatically create CloudWatch alarms for detecting idle campaigns and recommenders. Valid values: Yes/No.
    AllowedValues:
      - 'Yes'
      - 'No'
    Default: 'Yes'

  IdleThresholdHours:
    Type: Number
    Description: >
      Number of consecutive idle hours before a campaign is automatically deleted or recommender is automatically stopped only if AutoDeleteOrStopIdleResources
      is Yes. Valid values: 2-48 (integer).
    MinValue: 2
    MaxValue: 48
    Default: 24

  AutoDeleteOrStopIdleResources:
    Type: String
    Description: >
      Whether to automatically delete campaigns and stop recommenders that have been idle for IdleThresholdHours consecutive hours. Valid values: Yes/No.
    AllowedValues:
      - 'Yes'
      - 'No'
    Default: 'No'

  NotificationEndpoint:
    Type: String
    Description: >
      Email address to receive CloudWatch alarm and other monitoring notifications.

Globals:
  Function:
    Timeout: 5
    Runtime: python3.9

Resources:
  CommonLayer:
    Type: AWS::Serverless::LayerVersion
    Properties:
      ContentUri: src/layer
      CompatibleRuntimes:
        - python3.9
    Metadata:
      BuildMethod: python3.9

  MonitorFunction:
    Type: AWS::Serverless::Function
    Properties:
      Description: Amazon Personalize monitor function that updates custom CloudWatch metrics and monitors campaign utilization every 5 minutes
      Timeout: 30
      CodeUri: src/personalize_monitor_function
      Handler: personalize_monitor.lambda_handler
      Layers:
        - !Sub 'arn:${AWS::Partition}:lambda:${AWS::Region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:24'
        - !Ref CommonLayer
      Policies:
        - Statement:
          - Sid: PersonalizePolicy
            Effect: Allow
            Action:
              - personalize:DescribeCampaign
              - personalize:DescribeRecommender
              - personalize:DescribeSolutionVersion
              - personalize:ListCampaigns
              - personalize:ListRecommenders
            Resource: '*'
          - Sid: CloudWatchPolicy
            Effect: Allow
            Action:
              - cloudwatch:DescribeAlarmsForMetric
              - cloudwatch:DisableAlarmActions
              - cloudwatch:EnableAlarmActions
              - cloudwatch:GetMetricData
              - cloudwatch:PutMetricAlarm
              - cloudwatch:PutMetricData
            Resource: '*'
          - Sid: EventBridgePolicy
            Effect: Allow
            Action:
              - events:DescribeRule
              - events:PutEvents
              - events:PutRule
              - events:PutTargets
            Resource: '*'
          - Sid: SnsPolicy
            Effect: Allow
            Action:
              - sns:CreateTopic
              - sns:ListSubscriptionsByTopic
              - sns:SetTopicAttributes
              - sns:Subscribe
            Resource: !Sub 'arn:${AWS::Partition}:sns:*:${AWS::AccountId}:PersonalizeMonitorNotifications'
          - Sid: SnsSubPolicy
            Effect: Allow
            Action:
              - sns:GetSubscriptionAttributes
            Resource: '*'
      Events:
        ScheduledEvent:
          Type: Schedule
          Properties:
            Description: Triggers primary Personalize Monitor monitoring logic
            Schedule: cron(0/5 * * * ? *)
            Enabled: True
      Environment:
        Variables:
          CampaignARNs: !Ref CampaignARNs
          RecommenderARNs: !Ref RecommenderARNs
          Regions: !Ref Regions
          NotificationEndpoint: !Ref NotificationEndpoint
          AutoCreateUtilizationAlarms: !Ref AutoCreateUtilizationAlarms
          UtilizationThresholdAlarmLowerBound: !Ref UtilizationThresholdAlarmLowerBound
          AutoCreateIdleAlarms: !Ref AutoCreateIdleAlarms
          IdleThresholdHours: !Ref IdleThresholdHours
          AutoDeleteOrStopIdleResources: !Ref AutoDeleteOrStopIdleResources
          AutoAdjustMinTPS: !Ref AutoAdjustMinTPS

  DashboardManagementFunction:
    Type: AWS::Serverless::Function
    Properties:
      Description: Amazon Personalize monitor function that updates the CloudWatch dashboard hourly and when campaigns are added/deleted
      Timeout: 15
      CodeUri: src/dashboard_mgmt_function
      Handler: dashboard_mgmt.lambda_handler
      AutoPublishAlias: live
      Layers:
        - !Sub 'arn:${AWS::Partition}:lambda:${AWS::Region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:24'
        - !Ref CommonLayer
      Policies:
        - Statement:
          - Sid: PersonalizePolicy
            Effect: Allow
            Action:
              - personalize:DescribeCampaign
              - personalize:DescribeDatasetGroup
              - personalize:DescribeRecommender
              - personalize:DescribeSolutionVersion
              - personalize:ListCampaigns
              - personalize:ListRecommenders
            Resource: '*'
          - Sid: DashboardPolicy
            Effect: Allow
            Action:
              - cloudwatch:DeleteDashboards
              - cloudwatch:PutDashboard
            Resource: '*'
      Environment:
        Variables:
          CampaignARNs: !Ref CampaignARNs
          RecommenderARNs: !Ref RecommenderARNs
          Regions: !Ref Regions
      Events:
        EBRule:
          Type: EventBridgeRule
          Properties:
            Pattern:
              source:
                - personalize.monitor
              detail-type:
                - BuildPersonalizeMonitorDashboard
        ScheduledEvent:
          Type: Schedule
          Properties:
            Description: Hourly rebuild of Personalize Monitor CloudWatch dashboard
            Schedule: cron(3 * * * ? *)
            Enabled: True

  DeployDashboardCustomResource:
    Type: Custom::DashboardCreate
    Properties:
      ServiceToken: !GetAtt DashboardManagementFunction.Arn
      CampaignARNs: !Ref CampaignARNs
      RecommenderARNs: !Ref RecommenderARNs
      Regions: !Ref Regions
      AutoCreateUtilizationAlarms: !Ref AutoCreateUtilizationAlarms
      UtilizationThresholdAlarmLowerBound: !Ref UtilizationThresholdAlarmLowerBound
      AutoCreateIdleAlarms: !Ref AutoCreateIdleAlarms
      IdleThresholdHours: !Ref IdleThresholdHours
      AutoDeleteOrStopIdleResources: !Ref AutoDeleteOrStopIdleResources
      AutoAdjustMinTPS: !Ref AutoAdjustMinTPS

  UpdateTPSFunction:
    Type: AWS::Serverless::Function
    Properties:
      Description: Amazon Personalize monitor function that updates the minProvisionedTPS for a campaign or the minRecommendationRequestsPerSecond for a recommender in response to an event
      CodeUri: src/personalize_update_tps_function
      Handler: personalize_update_tps.lambda_handler
      Layers:
        - !Sub 'arn:${AWS::Partition}:lambda:${AWS::Region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:24'
        - !Ref CommonLayer
      Policies:
        - Statement:
          - Sid: PersonalizePolicy
            Effect: Allow
            Action:
              - personalize:DescribeRecommender
              - personalize:UpdateCampaign
              - personalize:UpdateRecommender
            Resource: '*'
          - Sid: EventBridgePolicy
            Effect: Allow
            Action:
              - events:PutEvents
            Resource: '*'
      Events:
        EBRule:
          Type: EventBridgeRule
          Properties:
            Pattern:
              source:
                - personalize.monitor
              detail-type:
                - UpdatePersonalizeCampaignMinProvisionedTPS
                - UpdatePersonalizeRecommenderMinRecommendationRPS

  DeleteCampaignFunction:
    Type: AWS::Serverless::Function
    Properties:
      Description: Amazon Personalize monitor function that deletes a campaign in response to an event
      CodeUri: src/personalize_delete_campaign_function
      Handler: personalize_delete_campaign.lambda_handler
      Layers:
        - !Sub 'arn:${AWS::Partition}:lambda:${AWS::Region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:24'
        - !Ref CommonLayer
      Policies:
        - Statement:
          - Sid: PersonalizePolicy
            Effect: Allow
            Action:
              - personalize:DeleteCampaign
            Resource: '*'
          - Sid: EventBridgePolicy
            Effect: Allow
            Action:
              - events:PutEvents
            Resource: '*'
          - Sid: CloudWatchFindAlarmsPolicy
            Effect: Allow
            Action:
              - cloudwatch:DescribeAlarms
              - cloudwatch:ListTagsForResource
            Resource: '*'
          - Sid: CloudWatchDeletePolicy
            Effect: Allow
            Action:
              - cloudwatch:DeleteAlarms
            Resource: !Sub 'arn:${AWS::Partition}:cloudwatch:*:${AWS::AccountId}:alarm:PersonalizeMonitor-*'
      Events:
        EBCustomRule:
          Type: EventBridgeRule
          Properties:
            Pattern:
              source:
                - personalize.monitor
              detail-type:
                - DeletePersonalizeCampaign

  StopRecommenderFunction:
    Type: AWS::Serverless::Function
    Properties:
      Description: Amazon Personalize monitor function that stops a recommender in response to an event
      CodeUri: src/personalize_stop_recommender_function
      Handler: personalize_stop_recommender.lambda_handler
      Layers:
        - !Sub 'arn:${AWS::Partition}:lambda:${AWS::Region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:24'
        - !Ref CommonLayer
      Policies:
        - Statement:
          - Sid: PersonalizePolicy
            Effect: Allow
            Action:
              - personalize:StopRecommender
            Resource: '*'
          - Sid: EventBridgePolicy
            Effect: Allow
            Action:
              - events:PutEvents
            Resource: '*'
          - Sid: CloudWatchFindAlarmsPolicy
            Effect: Allow
            Action:
              - cloudwatch:DescribeAlarms
              - cloudwatch:ListTagsForResource
            Resource: '*'
          - Sid: CloudWatchDeletePolicy
            Effect: Allow
            Action:
              - cloudwatch:DeleteAlarms
            Resource: !Sub 'arn:${AWS::Partition}:cloudwatch:*:${AWS::AccountId}:alarm:PersonalizeMonitor-*'
      Events:
        EBCustomRule:
          Type: EventBridgeRule
          Properties:
            Pattern:
              source:
                - personalize.monitor
              detail-type:
                - StopPersonalizeRecommender

  CleanupFunction:
    Type: AWS::Serverless::Function
    Properties:
      Description: Amazon Personalize monitor custom resource function that cleans up directly created resources when the application is deleted
      Timeout: 15
      CodeUri: src/cleanup_resources_function
      Handler: cleanup_resources.lambda_handler
      AutoPublishAlias: live
      Layers:
        - !Sub 'arn:${AWS::Partition}:lambda:${AWS::Region}:017000801446:layer:AWSLambdaPowertoolsPythonV2:24'
        - !Ref CommonLayer
      Policies:
        - Statement:
          - Sid: PersonalizePolicy
            Effect: Allow
            Action:
              - personalize:ListCampaigns
              - personalize:ListRecommenders
            Resource: '*'
          - Sid: CloudWatchFindAlarmsPolicy
            Effect: Allow
            Action:
              - cloudwatch:DescribeAlarms
              - cloudwatch:ListTagsForResource
            Resource: '*'
          - Sid: CloudWatchDeletePolicy
            Effect: Allow
            Action:
              - cloudwatch:DeleteAlarms
            Resource: !Sub 'arn:${AWS::Partition}:cloudwatch:*:${AWS::AccountId}:alarm:PersonalizeMonitor-*'
          - Sid: EventBridgePolicy
            Effect: Allow
            Action:
              - events:DeleteRule
              - events:RemoveTargets
            Resource: !Sub 'arn:${AWS::Partition}:events:*:${AWS::AccountId}:rule/PersonalizeMonitor-NotificationsRule'
          - Sid: SnsPolicy
            Effect: Allow
            Action:
              - sns:DeleteTopic
            Resource: !Sub 'arn:${AWS::Partition}:sns:*:${AWS::AccountId}:PersonalizeMonitorNotifications'
      Environment:
        Variables:
          CampaignARNs: !Ref CampaignARNs
          RecommenderARNs: !Ref RecommenderARNs
          Regions: !Ref Regions

  CleanupCustomResource:
    Type: Custom::Cleanup
    Properties:
      ServiceToken: !GetAtt CleanupFunction.Arn
      CampaignARNs: !Ref CampaignARNs
      RecommenderARNs: !Ref RecommenderARNs
      Regions: !Ref Regions
      AutoCreateUtilizationAlarms: !Ref AutoCreateUtilizationAlarms
      UtilizationThresholdAlarmLowerBound: !Ref UtilizationThresholdAlarmLowerBound
      AutoCreateIdleAlarms: !Ref AutoCreateIdleAlarms
      IdleThresholdHours: !Ref IdleThresholdHours
      AutoDeleteOrStopIdleResources: !Ref AutoDeleteOrStopIdleResources
      AutoAdjustMinTPS: !Ref AutoAdjustMinTPS

Outputs:
  MonitorFunction:
    Description: "Personalize monitor Function ARN"
    Value: !GetAtt MonitorFunction.Arn

  DashboardManagementFunction:
    Description: "CloudWatch Dashboard Management Function ARN"
    Value: !GetAtt DashboardManagementFunction.Arn

  UpdateTPSFunction:
    Description: "Update Personalize Campaign/Recommender TPS Function ARN"
    Value: !GetAtt UpdateTPSFunction.Arn

  DeleteCampaignFunction:
    Description: "Delete Personalize Campaign Function ARN"
    Value: !GetAtt DeleteCampaignFunction.Arn

  StopRecommenderFunction:
    Description: "Stop Personalize Recommender Function ARN"
    Value: !GetAtt StopRecommenderFunction.Arn