AWS IoT Events Diagnostics
When to use
Any AWS IoT Events investigation — detector models, inputs, alarms, actions, state transitions, Lambda actions, or event evaluation troubleshooting.
Investigation workflow
Step 1 — Collect and triage
aws iotevents list-detector-models
aws iotevents describe-detector-model --detector-model-name <name>
aws iotevents list-inputs
aws iotevents describe-input --input-name <name>
Step 2 — Domain deep dive
aws iotevents-data list-detectors --detector-model-name <name>
aws iotevents-data describe-detector --detector-model-name <name> --key-value <key>
aws iotevents list-alarm-models
aws iotevents describe-alarm-model --alarm-model-name <name>
Step 3 — Detailed investigation
aws iotevents-data list-alarms --alarm-model-name <name>
aws iotevents-data describe-alarm --alarm-model-name <name> --key-value <key>
aws cloudwatch get-metric-statistics --namespace AWS/IoTEvents --metric-name ActionExecutionError --start-time <start> --end-time <end> --period 300 --statistics Sum
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=iotevents.amazonaws.com --max-results 20
Read references/guardrails.md before concluding on any IoT Events issue.
Tool quick reference
| Tool / API |
When to use |
describe-detector-model |
Check model definition and states |
describe-input |
Check input schema |
describe-detector |
Check runtime detector state |
describe-alarm-model |
Check alarm configuration |
describe-alarm |
Check alarm runtime state |
| CloudWatch Metrics |
Check action errors and evaluation |
Gotchas: AWS IoT Events
- Detector models are state machines. Each state has onEnter, onInput, and onExit events. Transitions are evaluated on each input message.
- Inputs define the schema for incoming data. Input attribute paths must match the JSON payload structure exactly. Case-sensitive matching.
- Detectors are instances of detector models. Each unique key value creates a separate detector instance with its own state.
- Actions execute on events (onEnter, onInput, onExit) and transitions. Actions include SNS, SQS, Lambda, IoT topic publish, and more.
- Alarm models are simplified detector models for threshold monitoring. They have predefined states (NORMAL, ACTIVE, ACKNOWLEDGED, etc.).
- Conditions use a specific expression language, not standard SQL. Expressions support comparison, logical, and arithmetic operators.
Anti-hallucination rules
- Always cite specific detector model names, input names, or API responses as evidence.
- Detector model conditions use IoT Events expression language, not SQL.
- Each key value creates a separate detector instance. Never assume shared state.
- Actions require IAM role permissions. Never assume automatic access.
- Alarm models have predefined state machines. Never suggest custom alarm states.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
12 runbooks
| Category |
IDs |
Covers |
| A — Detector Models |
A1-A2 |
Model creation, validation errors |
| B — Inputs |
B1-B2 |
Input routing, schema issues |
| C — Alarms |
C1-C2 |
Alarm evaluation, state issues |
| D — Actions |
D1-D2 |
Action execution, Lambda actions |
| E — State Transitions |
E1-E2 |
Transition logic, condition errors |
| Z — Catch-All |
Z1-Z2 |
General troubleshooting, performance |
1---2name: iotevents-diagnostics3description: "Use this skill to investigate and troubleshoot AWS IoT Events problems by analyzing detector models, inputs, alarms, actions, state transitions, Lambda actions, and event evaluation using structured runbooks. Activate when: detector model creation failures, input routing errors, alarm evaluation issues, action execution failures, state transition problems, or the user says something is wrong with IoT Events."4---56# AWS IoT Events Diagnostics78## When to use910Any AWS IoT Events investigation — detector models, inputs, alarms, actions, state transitions, Lambda actions, or event evaluation troubleshooting.1112## Investigation workflow1314### Step 1 — Collect and triage1516```17aws iotevents list-detector-models18aws iotevents describe-detector-model --detector-model-name <name>19aws iotevents list-inputs20aws iotevents describe-input --input-name <name>21```2223### Step 2 — Domain deep dive2425```26aws iotevents-data list-detectors --detector-model-name <name>27aws iotevents-data describe-detector --detector-model-name <name> --key-value <key>28aws iotevents list-alarm-models29aws iotevents describe-alarm-model --alarm-model-name <name>30```3132### Step 3 — Detailed investigation3334```35aws iotevents-data list-alarms --alarm-model-name <name>36aws iotevents-data describe-alarm --alarm-model-name <name> --key-value <key>37aws cloudwatch get-metric-statistics --namespace AWS/IoTEvents --metric-name ActionExecutionError --start-time <start> --end-time <end> --period 300 --statistics Sum38aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=iotevents.amazonaws.com --max-results 2039```4041Read `references/guardrails.md` before concluding on any IoT Events issue.4243## Tool quick reference4445| Tool / API | When to use |46|------------|-------------|47| `describe-detector-model` | Check model definition and states |48| `describe-input` | Check input schema |49| `describe-detector` | Check runtime detector state |50| `describe-alarm-model` | Check alarm configuration |51| `describe-alarm` | Check alarm runtime state |52| CloudWatch Metrics | Check action errors and evaluation |5354## Gotchas: AWS IoT Events5556- Detector models are state machines. Each state has onEnter, onInput, and onExit events. Transitions are evaluated on each input message.57- Inputs define the schema for incoming data. Input attribute paths must match the JSON payload structure exactly. Case-sensitive matching.58- Detectors are instances of detector models. Each unique key value creates a separate detector instance with its own state.59- Actions execute on events (onEnter, onInput, onExit) and transitions. Actions include SNS, SQS, Lambda, IoT topic publish, and more.60- Alarm models are simplified detector models for threshold monitoring. They have predefined states (NORMAL, ACTIVE, ACKNOWLEDGED, etc.).61- Conditions use a specific expression language, not standard SQL. Expressions support comparison, logical, and arithmetic operators.6263## Anti-hallucination rules64651. Always cite specific detector model names, input names, or API responses as evidence.662. Detector model conditions use IoT Events expression language, not SQL.673. Each key value creates a separate detector instance. Never assume shared state.684. Actions require IAM role permissions. Never assume automatic access.695. Alarm models have predefined state machines. Never suggest custom alarm states.706. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.7172## 12 runbooks7374| Category | IDs | Covers |75|----------|-----|--------|76| A — Detector Models | A1-A2 | Model creation, validation errors |77| B — Inputs | B1-B2 | Input routing, schema issues |78| C — Alarms | C1-C2 | Alarm evaluation, state issues |79| D — Actions | D1-D2 | Action execution, Lambda actions |80| E — State Transitions | E1-E2 | Transition logic, condition errors |81| Z — Catch-All | Z1-Z2 | General troubleshooting, performance |
aws-samples