AWS IoT SiteWise Diagnostics
When to use
Any AWS IoT SiteWise investigation — asset models, measurements, transforms, metrics, portals, gateways, data ingestion, or property value troubleshooting.
Investigation workflow
Step 1 — Collect and triage
aws iotsitewise list-asset-models --max-results 25
aws iotsitewise describe-asset-model --asset-model-id <id>
aws iotsitewise list-assets --asset-model-id <id>
aws iotsitewise describe-asset --asset-id <id>
Step 2 — Domain deep dive
aws iotsitewise list-gateways
aws iotsitewise describe-gateway --gateway-id <id>
aws iotsitewise describe-gateway-capability-configuration --gateway-id <id> --capability-namespace "iotsitewise:opcuacollector:2"
aws iotsitewise get-asset-property-value --asset-id <id> --property-id <prop-id>
aws iotsitewise batch-get-asset-property-value-history --entries '[{"assetId":"<id>","propertyId":"<prop-id>","entryId":"1"}]'
Step 3 — Detailed investigation
aws iotsitewise list-portals
aws iotsitewise describe-portal --portal-id <id>
aws cloudwatch get-metric-statistics --namespace AWS/IoTSiteWise --metric-name BatchPutAssetPropertyValue.Success --start-time <start> --end-time <end> --period 300 --statistics Sum
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=iotsitewise.amazonaws.com --max-results 20
Read references/guardrails.md before concluding on any IoT SiteWise issue.
Tool quick reference
| Tool / API |
When to use |
describe-asset-model |
Check model definition and properties |
describe-asset |
Check asset status and hierarchy |
get-asset-property-value |
Get latest property value |
describe-gateway |
Check gateway status and config |
describe-portal |
Check portal configuration |
| CloudWatch Metrics |
Check ingestion rates and errors |
Gotchas: AWS IoT SiteWise
- Asset models define the structure; assets are instances. Models have measurements (raw data), transforms (computed from measurements), and metrics (aggregated over time windows).
- Transforms compute in near real-time from other properties. They use a formula language with mathematical and comparison functions. Circular references cause model validation failures.
- Metrics aggregate data over time windows (1m, 5m, 1h, 1d). They can reference measurements, transforms, or other metrics. Metric computation has eventual consistency.
- Gateways run on Greengrass V2 and collect data from OPC-UA, Modbus, or Ethernet/IP sources. Gateway capability configuration defines the data sources.
- Portals use IAM Identity Center (SSO) for authentication. Portal users need explicit access to projects and assets.
- Data ingestion via BatchPutAssetPropertyValue has rate limits per property and per account. Timestamps must be within the allowed time range.
Anti-hallucination rules
- Always cite specific asset model IDs, property IDs, or API responses as evidence.
- Transforms and metrics have different computation models. Never confuse them.
- Gateway data sources require specific capability namespace configuration.
- Portal access requires IAM Identity Center. Never suggest IAM user access.
- Property data types must match between model definition and ingested data.
- Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.
14 runbooks
| Category |
IDs |
Covers |
| A — Asset Models |
A1-A2 |
Model creation, hierarchy issues |
| B — Properties |
B1-B3 |
Measurements, transforms, metrics |
| C — Portals |
C1-C2 |
Portal access, dashboard issues |
| D — Gateways |
D1-D2 |
Gateway connectivity, data source config |
| E — Ingestion |
E1-E2 |
Data ingestion, batch operations |
| F — Integration |
F1-F2 |
Alarms, notifications |
| Z — Catch-All |
Z1 |
General troubleshooting |
1---2name: iotsitewise-diagnostics3description: Use this skill to investigate and troubleshoot AWS IoT SiteWise problems by analyzing asset models, measurements, transforms, metrics, portals, gateways, data ingestion, and property value issues using structured runbooks. Activate when: asset model creation failures, measurement ingestion errors, transform computation issues, metric aggregation problems, portal access failures, gateway connectivity issues, or the user says something is wrong with IoT SiteWise.4---56# AWS IoT SiteWise Diagnostics78## When to use910Any AWS IoT SiteWise investigation — asset models, measurements, transforms, metrics, portals, gateways, data ingestion, or property value troubleshooting.1112## Investigation workflow1314### Step 1 — Collect and triage1516```17aws iotsitewise list-asset-models --max-results 2518aws iotsitewise describe-asset-model --asset-model-id <id>19aws iotsitewise list-assets --asset-model-id <id>20aws iotsitewise describe-asset --asset-id <id>21```2223### Step 2 — Domain deep dive2425```26aws iotsitewise list-gateways27aws iotsitewise describe-gateway --gateway-id <id>28aws iotsitewise describe-gateway-capability-configuration --gateway-id <id> --capability-namespace "iotsitewise:opcuacollector:2"29aws iotsitewise get-asset-property-value --asset-id <id> --property-id <prop-id>30aws iotsitewise batch-get-asset-property-value-history --entries '[{"assetId":"<id>","propertyId":"<prop-id>","entryId":"1"}]'31```3233### Step 3 — Detailed investigation3435```36aws iotsitewise list-portals37aws iotsitewise describe-portal --portal-id <id>38aws cloudwatch get-metric-statistics --namespace AWS/IoTSiteWise --metric-name BatchPutAssetPropertyValue.Success --start-time <start> --end-time <end> --period 300 --statistics Sum39aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=iotsitewise.amazonaws.com --max-results 2040```4142Read `references/guardrails.md` before concluding on any IoT SiteWise issue.4344## Tool quick reference4546| Tool / API | When to use |47|------------|-------------|48| `describe-asset-model` | Check model definition and properties |49| `describe-asset` | Check asset status and hierarchy |50| `get-asset-property-value` | Get latest property value |51| `describe-gateway` | Check gateway status and config |52| `describe-portal` | Check portal configuration |53| CloudWatch Metrics | Check ingestion rates and errors |5455## Gotchas: AWS IoT SiteWise5657- Asset models define the structure; assets are instances. Models have measurements (raw data), transforms (computed from measurements), and metrics (aggregated over time windows).58- Transforms compute in near real-time from other properties. They use a formula language with mathematical and comparison functions. Circular references cause model validation failures.59- Metrics aggregate data over time windows (1m, 5m, 1h, 1d). They can reference measurements, transforms, or other metrics. Metric computation has eventual consistency.60- Gateways run on Greengrass V2 and collect data from OPC-UA, Modbus, or Ethernet/IP sources. Gateway capability configuration defines the data sources.61- Portals use IAM Identity Center (SSO) for authentication. Portal users need explicit access to projects and assets.62- Data ingestion via BatchPutAssetPropertyValue has rate limits per property and per account. Timestamps must be within the allowed time range.6364## Anti-hallucination rules65661. Always cite specific asset model IDs, property IDs, or API responses as evidence.672. Transforms and metrics have different computation models. Never confuse them.683. Gateway data sources require specific capability namespace configuration.694. Portal access requires IAM Identity Center. Never suggest IAM user access.705. Property data types must match between model definition and ingested data.716. Spend no more than 2 minutes on any single hypothesis. Pivot if inconclusive.7273## 14 runbooks7475| Category | IDs | Covers |76|----------|-----|--------|77| A — Asset Models | A1-A2 | Model creation, hierarchy issues |78| B — Properties | B1-B3 | Measurements, transforms, metrics |79| C — Portals | C1-C2 | Portal access, dashboard issues |80| D — Gateways | D1-D2 | Gateway connectivity, data source config |81| E — Ingestion | E1-E2 | Data ingestion, batch operations |82| F — Integration | F1-F2 | Alarms, notifications |83| Z — Catch-All | Z1 | General troubleshooting |
aws-samples