Instana Agent API to match hosts and Agents
Instana UI provides a list of Agents, which are associated to their respective full qualified hostnames and information about version, update mode and runtime.
In this blog post, I describe a way to query the Instana backend to compile a list with this information for further processing from different backend endpoints.
Prerequisites
API token
To query the Instana backend API, go to "Settings" in Instana UI and either create an API Token or use an existing one. More information about API tokens can be found in the documentation.
Command line tools
The execution of this blog post builds on top of existing command line tools for Linux and macOS. Use the appropriate package manager and install:
- curl
- jq
- sort (usually part of the core OS)
- join (usually part of the core OS)
Query agents
The API endpoint to query a list of Agent data is /api/host-agent. It lists all existing Agents, which reported in the last hour.
The result set includes the field snapshotId for every Agent, which is the unique identifier for the static data set about the specific Agent instance. This data set is called "snapshot".
The API endpoint /api/host-agent/<agent-snapshot> provides the full snapshot data set for the specific Agent. Subsequent calls to this endpoint with all individual snapshotIds from the first endpoint results in a list of host ids and any snapshot information for the final result set.
Combining both calls, piping output through jq, and sorting the result will look like this:
export API_TOKEN=<your-api-token>; \
export TENANT_UNIT=<your-instana-tenant-unit>; \
curl -s --request GET --header "authorization: apiToken $API_TOKEN" \
--url https://$TENANT_UNIT.instana.io/api/host-agent | \
jq -r '.items[] | .snapshotId' | \
xargs -I {} curl -s --request GET --header "authorization: apiToken $API_TOKEN" \
--url https://$TENANT_UNIT.instana.io/api/host-agent/{} | \
jq -r '.entityId.host + ";" + .data.agentVersion' | sort -t ";" -k1
The last invocation of jq builds the result set with values .entityId.host, which is the unique identifier for the host and .data.agentVersion, which is the version of the reporting Agent. Both values are separated by ";", which is not found in either hostId or agent version.
Extra values from the agent snapshot can be appended in this invocation.
Query hosts
The API endpoint to query a list of host snapshots is /api/infrastructure-monitoring/snapshots?plugin=host. Here the query parameter plugin is used to filter only snapshot data for hosts. The result is a data set which includes the host unique identifier, just like the Agent result set, and additional information, like the full qualified domain name (FQDN) of the host.
Call the API, piping through jq and sorting the output looks like this:
export API_TOKEN=<your-api-token>; \
export TENANT_UNIT=<your-instana-tenant-unit>; \
curl -s --request GET --header "authorization: apiToken $API_TOKEN" \
--url "https://$TENANT_UNIT.instana.io/api/infrastructure-monitoring/snapshots?plugin=host" | \
jq -r '.items[] | .host + ";" + .label' | sort -t ";" -k1
Create shell scripts
To keep things tidy, I created two shell scripts to encapsulate the preceding commands.
Create the files api-query-agents.sh and api-query-hosts.sh and place the respective commands after the shebang #!/bin/bash.
Make both scripts executable by issuing chmod +x api-query-agents.sh api-query-hosts.sh.
Make sure to replace <your-api-token> and <your-instana-tenant-unit> with your API token and the domain name of your Instana SaaS account (I used "demous-instana").
Match Agent and host lists on host identifier
Each item in the resulting Agent list is a tuple of hostId;agentVersion, while entries in the host list contain hostId;FQDN. Both lists can be matched by using join on the first field, resulting in a final list with the structure hostId;agentVersion;FQDN.
With the existing shell scripts, the invocation looks like this:
join -t ";" -1 1 -2 1 <( ./api-query-agents.sh ) <( ./api-query-hosts.sh )
And the result list looks like this:
00:00:0a:ff:fe:0b:40:71;2024.10.07.1606;fyre-9-30-99-209.ibm.com
00:00:0a:ff:fe:0b:47:1f;2024.08.12.0642;AWS-EKS1.ibm.com
00:00:0a:ff:fe:0b:6d:be;2024.10.10.2225;agent-test-rhel1.ibm.com
00:00:0a:ff:fe:0b:79:2d;2024.10.10.2225;agent-retro1.ibm.com
00:00:0a:ff:fe:0b:7a:1c;2024.11.21.0619;c97508v1.ibm.com
00:00:0a:ff:fe:0b:7c:a6;2024.11.14.1430-dev;microshift-stable.ibm.com
00:00:0a:ff:fe:33:04:29;2024.11.21.0619;c54315v1.ibm.com
00:00:0a:ff:fe:33:09:37;2024.11.21.0619;wom-payara1.ibm.com
12:95:41:ff:fe:69:ee:e3;2024.11.20.1628;worker15.ocp.cp.ibm.com
2a:aa:db:ff:fe:45:d2:dc;2024.11.20.1628;worker1.instana-agent-ocp.ibm.com
3e:ea:ae:ff:fe:97:6f:ad;2024.11.20.1628;worker13.ocp.ibm.com
52:54:00:ff:fe:3d:43:0f;2024.11.20.1628;will-it-work.instana.io
Happy hacking!
#automation-featured-area-1
#Featured-area-1-home
#Featured-area-1
#AI-IT-Automation-Instana
#Instana