Preparing fleet indexing
With Amazon IoT fleet indexing, you can search and aggregate data by using the reserved named shadow ($package
). You can also group Amazon IoT things by querying the Reserved named shadow and dynamic thing groups. For example, you can find information about which Amazon IoT things use a specific package version, don't have a specific package version installed, or don’t have any package version installed. You can gain further insight by combining attributes. For example, identifying things that have a specific version and are of a specific thing type (such as version 1.0.0 and thing type of pump_sensor). For more information, see Fleet indexing.
Setting the $package
shadow as a data source
To use fleet indexing with Software Package Catalog, you must enable fleet indexing, set the named shadow as the data source,
and define $package
as the named shadow filter. If you haven’t enabled fleet indexing, you can enable
it within this process. From Amazon IoT Core
Alternately, you can enable fleet indexing when you create your first package. When the Enable dependencies for package management dialog box appears, choose the option to add device software packages and versions as data sources to fleet indexing. By selecting this option, you also enable fleet indexing.
Note
Enabling fleet indexing for Software Package Catalog incurs standard service costs.
For more information, see Amazon IoT Device Management, Pricing
Metrics displayed in the console
On the Amazon IoT console software package details page, the Discovery panel displays standard metrics ingested through the $package
shadow.
The Current version distribution chart shows the number of devices and percentage for the 10 most recent package versions that are associated to an Amazon IoT thing from all the devices associated to this software package. Note: If the software package has more package versions than those labeled in the chart, you can find them grouped within Other.
The Historical chart shows the number of devices associated with selected package versions over a specified time period. The chart is initially empty until you select up to 5 package versions and define the date range and time interval. To select the chart’s parameters, choose Settings. The data displayed in the Historical chart might be different than the Current version distribution chart because of the difference in number of package versions that they display and also because you can choose which package versions to analyze in the Historical chart. Note: When you select a package version to visualize, it counts toward the maximum number of fleet metrics limits. For more information, see Fleet indexing limits and quotas.
For another method to gain insight into collecting package version distribution, see Collecting package version distribution through getBucketsAggregation
.
Query patterns
Fleet indexing with Software Package Catalog uses most of the supported features (for example, terms and phrases and search fields) that are standard for fleet indexing. The exception is that the comparison
and range
queries aren't available for the reserved named shadow ($package
) version
key. However, these queries are available for the attributes
key.
For more information, see Query syntax.
Example data
Note: for information about the reserved named shadow and its structure, see Reserved named shadow.
In this example, a first device is named AnyThing
and has the following packages installed:
-
Software package:
SamplePackage
Package version:
1.0.0
Package ID:
1111
The shadow looks as follows:
{
"state": {
"reported": {
"SamplePackage": {
"version": "1.0.0",
"attributes": {
"s3UrlForSamplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile1",
"packageID": "1111"
}
}
}
}
}
A second device is named AnotherThing
and has the following package installed:
-
Software package:
SamplePackage
Package version:
1.0.0
Package ID:
1111
-
Software package:
OtherPackage
Package version:
1.2.5
Package ID:
2222
The shadow looks as follows:
{
"state": {
"reported": {
"SamplePackage": {
"version": "1.0.0",
"attributes": {
"s3UrlForSamplePackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile1",
"packageID": "1111"
}
},
"OtherPackage": {
"version": "1.2.5",
"attributes": {
"s3UrlForOtherPackage": "https://EXAMPIEBUCKET.s3.us-west-2.amazonaws.com/exampleCodeFile2",
"packageID": "2222"
}
},
}
}
}
Sample queries
The following table lists sample queries based on the example device shadows for AnyThing
and AnotherThing
.
For more information, see Example thing queries.
Requested information |
Query |
Result |
---|---|---|
Things that have a specific package version installed |
|
|
Things that don't have a specific package version installed |
|
|
Any device using a package version whose package ID is greater than 1500 |
|
|
Things that have a specific package installed and have more than one package installed |
|
|
Collecting package version distribution through getBucketsAggregation
In addition to the Discovery panel within the Amazon IoT console, you can also get package version distribution information by using the GetBucketsAggregation
API operation. To get the package version distribution information, you must do the following:
Define a custom field within fleet indexing for each software package. Note: Creating custom fields count toward Amazon IoT fleet indexing service quotas.
Format the custom field as follows:
shadow.name.$package.reported.
<packageName>
.version
For more information, see the Custom fields section in Amazon IoT fleet indexing.