Analyzing Dynamodb

DynamoDB Analysis Skill

Analyze and optimize DynamoDB tables with safe, read-only operations.

MANDATORY: Two-Phase Execution

You MUST follow this two-phase pattern. Skipping Phase 1 causes hallucinated table names and attribute errors.

Phase 1: Discovery (ALWAYS run first)

#!/bin/bash

# 1. List all tables in the region
aws dynamodb list-tables --output json | jq -r '.TableNames[]'

# 2. Describe target table (schema, capacity, indexes)
aws dynamodb describe-table --table-name "$TABLE_NAME" --output json | jq '{
  TableName: .Table.TableName,
  Status: .Table.TableStatus,
  ItemCount: .Table.ItemCount,
  TableSizeBytes: .Table.TableSizeBytes,
  BillingMode: .Table.BillingModeSummary.BillingMode,
  KeySchema: .Table.KeySchema,
  AttributeDefinitions: .Table.AttributeDefinitions,
  GSICount: (.Table.GlobalSecondaryIndexes | length // 0),
  LSICount: (.Table.LocalSecondaryIndexes | length // 0)
}'

# 3. Sample items to understand actual attribute names
aws dynamodb scan --table-name "$TABLE_NAME" --max-items 5 --output json | jq '.Items[0]'

Phase 1 outputs:

• List of tables in the account/region
• Table schema with key attributes and billing mode
• Sample items to understand actual attribute names

Phase 2: Analysis (only after Phase 1)

Only reference tables, attributes, and indexes confirmed in Phase 1.

Shell Script Patterns

Helper Function

#!/bin/bash

# Core DynamoDB helper — always use this
ddb_cmd() {
    aws dynamodb "$@" --output json
}

# Describe table helper
ddb_describe() {
    local table="$1"
    ddb_cmd describe-table --table-name "$table"
}

# CloudWatch metric helper for DynamoDB
ddb_metric() {
    local table="$1" metric="$2" stat="${3:-Sum}" period="${4:-300}"
    aws cloudwatch get-metric-statistics \
        --namespace AWS/DynamoDB \
        --metric-name "$metric" \
        --dimensions Name=TableName,Value="$table" \
        --start-time "$(date -u -v-1H +%Y-%m-%dT%H:%M:%S 2>/dev/null || date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%S)" \
        --end-time "$(date -u +%Y-%m-%dT%H:%M:%S)" \
        --period "$period" \
        --statistics "$stat" \
        --output json
}

Anti-Hallucination Rules

• NEVER reference a table name without confirming it exists via list-tables
• NEVER reference attribute names without seeing them in describe-table or a sample scan
• NEVER assume GSI/LSI names — always get them from describe-table
• NEVER guess capacity units — always read from table description or CloudWatch metrics
• NEVER assume billing mode — confirm on-demand vs provisioned from table description

Safety Rules

• READ-ONLY ONLY: Use only describe-table, list-tables, scan (with --max-items), query, get-item
• FORBIDDEN: create-table, delete-table, update-table, put-item, delete-item, batch-write-item without explicit user request
• ALWAYS add --max-items to scan operations — tables can have billions of items
• NEVER run full table scans on production without --max-items
• Use --select COUNT when you only need item counts, not full items

Common Operations

Table Health Overview

#!/bin/bash
echo "=== DynamoDB Tables ==="
TABLES=$(aws dynamodb list-tables --output json | jq -r '.TableNames[]')

for TABLE in $TABLES; do
    INFO=$(ddb_describe "$TABLE" | jq -r '.Table | "\(.TableName)\t\(.TableStatus)\t\(.ItemCount) items\t\((.TableSizeBytes/1024/1024)|round)MB\t\(.BillingModeSummary.BillingMode // "PROVISIONED")"')
    echo "$INFO"
done

echo ""
echo "=== Table Details: $TABLE_NAME ==="
ddb_describe "$TABLE_NAME" | jq '.Table | {
    KeySchema,
    AttributeDefinitions,
    BillingMode: .BillingModeSummary.BillingMode,
    ProvisionedThroughput: (if .BillingModeSummary.BillingMode == "PAY_PER_REQUEST" then "On-Demand" else .ProvisionedThroughput end),
    ItemCount,
    TableSizeMB: ((.TableSizeBytes/1024/1024)|round)
}'

GSI/LSI Analysis

#!/bin/bash
TABLE_NAME="$1"

echo "=== Global Secondary Indexes ==="
ddb_describe "$TABLE_NAME" | jq -r '.Table.GlobalSecondaryIndexes[]? | "\(.IndexName)\t\(.IndexStatus)\t\(.ItemCount) items\t\(.KeySchema | map(.AttributeName + "=" + .KeyType) | join(","))\tProjection=\(.Projection.ProjectionType)"'

echo ""
echo "=== Local Secondary Indexes ==="
ddb_describe "$TABLE_NAME" | jq -r '.Table.LocalSecondaryIndexes[]? | "\(.IndexName)\t\(.KeySchema | map(.AttributeName + "=" + .KeyType) | join(","))\tProjection=\(.Projection.ProjectionType)"'

echo ""
echo "=== GSI Capacity Utilization ==="
ddb_describe "$TABLE_NAME" | jq -r '.Table.GlobalSecondaryIndexes[]? | select(.ProvisionedThroughput) | "\(.IndexName)\tRCU=\(.ProvisionedThroughput.ReadCapacityUnits)\tWCU=\(.ProvisionedThroughput.WriteCapacityUnits)"'

Capacity & Throttling Analysis

#!/bin/bash
TABLE_NAME="$1"

echo "=== Consumed Read Capacity ==="
ddb_metric "$TABLE_NAME" "ConsumedReadCapacityUnits" "Sum" 300 | jq -r '.Datapoints | sort_by(.Timestamp) | .[] | "\(.Timestamp)\t\(.Sum)"'

echo ""
echo "=== Consumed Write Capacity ==="
ddb_metric "$TABLE_NAME" "ConsumedWriteCapacityUnits" "Sum" 300 | jq -r '.Datapoints | sort_by(.Timestamp) | .[] | "\(.Timestamp)\t\(.Sum)"'

echo ""
echo "=== Throttled Requests (last 1h) ==="
for METRIC in ReadThrottleEvents WriteThrottleEvents; do
    echo "--- $METRIC ---"
    ddb_metric "$TABLE_NAME" "$METRIC" "Sum" 300 | jq -r '.Datapoints | sort_by(.Timestamp) | .[] | select(.Sum > 0) | "\(.Timestamp)\t\(.Sum)"'
done

Access Pattern Analysis

#!/bin/bash
TABLE_NAME="$1"

echo "=== Successful Request Latency ==="
ddb_metric "$TABLE_NAME" "SuccessfulRequestLatency" "Average" 60 | jq -r '.Datapoints | sort_by(.Timestamp) | .[-5:][] | "\(.Timestamp)\t\(.Average)ms"'

echo ""
echo "=== System Errors ==="
ddb_metric "$TABLE_NAME" "SystemErrors" "Sum" 300 | jq -r '.Datapoints | sort_by(.Timestamp) | .[] | select(.Sum > 0) | "\(.Timestamp)\t\(.Sum)"'

echo ""
echo "=== User Errors ==="
ddb_metric "$TABLE_NAME" "UserErrors" "Sum" 300 | jq -r '.Datapoints | sort_by(.Timestamp) | .[] | select(.Sum > 0) | "\(.Timestamp)\t\(.Sum)"'

Cost Estimation

#!/bin/bash
TABLE_NAME="$1"

echo "=== Table Size & Item Count ==="
ddb_describe "$TABLE_NAME" | jq '.Table | {
    TableSizeGB: ((.TableSizeBytes/1024/1024/1024)*100|round/100),
    ItemCount: .ItemCount,
    BillingMode: .BillingModeSummary.BillingMode,
    StorageCostEstimate: "\(((.TableSizeBytes/1024/1024/1024)*0.25)*100|round/100) USD/month (at $0.25/GB)"
}'

echo ""
echo "=== GSI Storage Overhead ==="
ddb_describe "$TABLE_NAME" | jq '[.Table.GlobalSecondaryIndexes[]? | {IndexName, SizeGB: ((.IndexSizeBytes/1024/1024/1024)*100|round/100)}]'

Output Format

Present results as a structured report:

Analyzing Dynamodb Report
═════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Counter-Rationalizations

Common Pitfalls

• Scan vs Query: Scans read every item — always prefer Query with key conditions for production analysis
• Eventually consistent reads: Default reads are eventually consistent; specify --consistent-read only when needed
• GSI eventual consistency: GSI data is always eventually consistent — do not rely on immediate GSI updates
• Capacity calculation: 1 RCU = 1 strongly consistent read/s (4KB) or 2 eventually consistent reads/s; 1 WCU = 1 write/s (1KB)
• Hot partitions: Adaptive capacity helps but does not eliminate hot key issues — check partition key distribution
• Item size limit: 400KB per item — check for items approaching this limit
• --max-items vs --limit: --max-items limits CLI output (client-side); --limit limits DynamoDB scan (server-side and costs less RCU)