Amazon DynamoDB Throttled Requests and Capacity Starvation Sentinel

id: aws-dynamodb-user-errors-and-throttled-requests-sentinel
namespace: company.database
description: Audits Amazon DynamoDB table ThrottledRequests and UserErrors via
  CloudWatch metrics, flags capacity starvation, logs a GitHub DBA ticket, and
  alerts Slack.
inputs:
  - id: aws_region
    type: STRING
    displayName: AWS Region
    defaults: us-east-1
  - id: table_name
    type: STRING
    displayName: DynamoDB Table Name
    defaults: user-sessions-table
  - id: throttle_threshold
    type: INT
    displayName: Max Throttles (15m)
    defaults: 10
  - id: target_repository
    type: STRING
    displayName: Database Issue Repository
    defaults: my-org/database-operations
triggers:
  - id: periodic_dynamodb_throttle_check
    type: io.kestra.plugin.core.trigger.Schedule
    cron: '*/15 * * * *'
    disabled: true
tasks:
  - id: probe_dynamodb_throttles
    type: io.kestra.plugin.aws.cli.AwsCLI
    description: Queries CloudWatch for DynamoDB ThrottledRequests metric over the
      last 15 minutes
    accessKeyId: '{{ secret(''AWS_ACCESS_KEY_ID'') }}'
    secretKeyId: '{{ secret(''AWS_SECRET_ACCESS_KEY'') }}'
    region: '{{ inputs.aws_region }}'
    commands:
      - aws cloudwatch get-metric-data --metric-data-queries
        '[{"Id":"m1","MetricStat":{"Metric":{"Namespace":"AWS/DynamoDB","MetricName":"ThrottledRequests","Dimensions":[{"Name":"TableName","Value":"{{
        inputs.table_name }}"}]},"Period":900,"Stat":"Sum"},"ReturnData":true}]'
        --start-time $(date -u -v-15M +%Y-%m-%dT%H:%M:%SZ) --end-time $(date -u
        +%Y-%m-%dT%H:%M:%SZ) --output json | tr -d '\n' | xargs -0 -I {} echo
        '::{"outputs":{}}::'
  - id: evaluate_throttles
    type: io.kestra.plugin.core.debug.Return
    description: Evaluates throttled request sum against threshold
    format:
      table: '{{ inputs.table_name }}'
      throttle_count: '{{
        outputs.probe_dynamodb_throttles.vars.MetricDataResults[0].Values[0] ??
        0 }}'
      threshold: '{{ inputs.throttle_threshold }}'
      is_throttling_critical: '{{
        (outputs.probe_dynamodb_throttles.vars.MetricDataResults[0].Values[0] ??
        0) >= inputs.throttle_threshold }}'
  - id: branch_on_throttles
    type: io.kestra.plugin.core.flow.If
    description: Branches based on whether DynamoDB throttles exceeded threshold
    condition: '{{ outputs.evaluate_throttles.value.is_throttling_critical == true }}'
    then:
      - id: create_dynamodb_incident_issue
        type: io.kestra.plugin.github.issues.Create
        description: Logs a prioritized GitHub issue documenting DynamoDB throttling
        oauthToken: '{{ secret(''GITHUB_TOKEN'') }}'
        repository: '{{ inputs.target_repository }}'
        title: '[DynamoDB Alert] ThrottledRequests Capacity Starvation on {{
          inputs.table_name }}'
        body: "## 🚨 Amazon DynamoDB Throttling Starvation


          The NoSQL database sentinel detected excessive ThrottledRequests:

          - **Table Name:** `{{ inputs.table_name }}`

          - **Throttled Requests (15m):** **{{
          outputs.evaluate_throttles.value.throttle_count }}**

          - **Threshold:** `{{ inputs.throttle_threshold }}`


          Please verify table Read/Write Capacity Units (RCU/WCU) or
          auto-scaling policies.

          *Generated automatically by Kestra DynamoDB Sentinel.*"
      - id: alert_database_slack
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        description: Dispatches alert to database Slack channel
        url: '{{ secret(''SLACK_WEBHOOK'') }}'
        payload: "{{ {'text': '🚨 *Amazon DynamoDB Throttling Alert*\\n*Table:* `' ~
          inputs.table_name ~ '`\\n*Throttles:* *' ~
          outputs.evaluate_throttles.value.throttle_count ~ '*\\n*Incident
          Ticket:* <' ~ (outputs.create_dynamodb_incident_issue.issueUrl ?? '#')
          ~ '|View GitHub Issue>'} | toJson }}"
    else:
      - id: log_table_healthy
        type: io.kestra.plugin.core.log.Log
        message: DynamoDB table {{ inputs.table_name }} is operating within capacity
          limits ({{ outputs.evaluate_throttles.value.throttle_count }}
          throttles < {{ inputs.throttle_threshold }}).
  - id: log_audit_complete
    type: io.kestra.plugin.core.log.Log
    description: Final audit status log
    message: DynamoDB audit complete for {{ inputs.table_name }}.
errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    description: Alerts Slack on execution failure
    url: '{{ secret(''SLACK_WEBHOOK'') }}'
    payload: "{{ {'text': '⚠️ *Amazon DynamoDB Sentinel Failed* in execution `' ~
      execution.id ~ '`.'} | toJson }}"