Universal Agent REST APIs

The Universal Agent API is a Controller REST API that enables you to monitor and manage a Universal Agent deployment programmatically. 

The Universal Agent API enables you to act on Universal Agent groups, individual Universal Agents, rulebooks, and Universal Agent events.

Permissions

The following RBAC permissions and roles authorize the use of the Universal Agent REST APIs.

• Permissions 
  • Configure Universal Agent
  • View Universal Agent
• Roles
  • Universal Agent Administrator with both view and configure permissions
  • Universal Agent User with view permission

Universal Agent Administrator and Universal Agent User roles are added to all new and existing accounts. Also Universal Agent Administrator and Universal Agent User roles are added to users who have "Account Administrator" role. Configure Universal Agent and View Universal Agent permissions are added to "Account Administrator" role of all accounts.

See Roles and Permissions for more information on AppDynamics permissions and roles. 

Using Environment Data

You can get information about the running environment for each Universal Agent and the runtime agents using the API call described in Get Complete Information for Universal Agents to get environment values. You can then use the values to populate rulebook properties, such as tier and application names. See the section "Dynamic Field Values" in Runtime Agent Rulebooks for more information.

To read environment variable data from JVM environments, the Universal Agent needs to have sufficient permissions. See more information about these requirement and how to provision the Universal Agent with sudo access if necessary in Java Agent Rules. 

As an API response, the environment data is made up of the following name/value pairs:

• Information about the underlying platform:
  • platform_machine: Machine type, for example - 'i386'
  • platform_processor: Processor name, for example - 'amdk6'
  • platform_release: System/OS release, for example - '2.2.0' or 'NT'
  • platform_system: System/OS name, for example - 'Linux', 'Windows'
  • platform_version: System release version, for example - 'Darwin Kernel Version 14.4.0’
• Network-related information:
  • hostname: Fully qualified domain name
  • ip_addresses: List of IP addresses for machines where the Universal Agent is running 
  • mac_addresses: List of MAC addresses for machines where the Universal Agent is running
• Names and values of each environment variable. The keys are the name of each environment variable, prefixed with “env_”. For example if the environment contains the variables HOME and SHELL, then this section may look like:
  • env_HOME: /Users/john.smith
  • env_SHELL: /bin/bash
• Time information:
  • time_utc: current UTC date and time in ISO 8601 format
• Information about the Universal Agent
  • universalagent_version: Current version, for example, ‘4.2.0.0'
  • universalagent_build: Build number
• Information about the Java runtime agent:
  • java_targets: List of running Java processes on the machine. This is organized as a map of pid to process command line

  • java_installs: Absolute paths of the Java runtime agents installed by the Universal Agent. This is organized as nested maps, using the app/tier/node name as the key. For example:

    “java_installs": {
        “MyApp”: {
            “MyTier”: {
                “MyNode1”: “/path/to/java/app/monitor/1”,
                “MyNode2”: “/path/to/java/app/monitor/2”,
            }
        },
        “MyApp2”: {
            “MyTier2a”: {
                “Node”: “/path/to/java/app/monitor/3"
            },
            “MyTier2b”: {
                “Node”: “/path/to/java/app/monitor/4"
            },
    	“null”: {
                “null”: “/path/to/java/app/monitor/that/only/had/app/specified/in/controller/info/xml”
            }
        }
    }

• Information about the machine agents:
  • machine_installs: list of absolute paths to machine agents installed by the Universal Agent
  • machine_starts: list of absolute paths to the machine agents started by the Universal Agent

API Rate and Total Count Limits

The following rate limits apply by default:

• Maximum 5000 agent registrations per minute per account
• Maximum 5000 event registrations per minute per account
• Maximum 500 user requests per minute per account 

The following total count limits apply by default: 

• Maximum 5000 agents per account
• Maximum 500 rulebooks per account
• Maximum 500 groups per account 

For on-premises Controllers, you can configure rate and total count limits from the Controller Administration Console. 

Get Complete Information for Universal Agents

Returns information about running and previously running Universal Agents. When used with the "groups" query parameter, this API returns information only for the agents under the specified groups.

Format   

GET controller/universalagent/v1/user/agents?agents=<value1, value2>

GET /controller/universalagent/v1/user/agents?agents=<value1, value2>&groups=<value>

GET /controller/universalagent/v1/user/agents?groups=<value1, value2>

Query Parameters

Example

curl -i -X GET -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/agents 

Response Format

{
    "agent1": {
        "version": <string>,
        "ruleBookName": <string>,
        "environment": {
            "key1": <object>,
            ...
        }
    },
    ...
}

Response Fields

• "agent1" is the name of the Universal Agent
• "version" is the key for the version of the Universal Agent 
• "ruleBookName" is the key for the name of the Universal Agent's current rulebook
• "environment" is the key for the environment data collected by the Environment Modules

Get Summary Information for Universal Agents

View summary information about all running Universal Agents. The environment data is suppressed. When used with the "groups" query parameter, this API returns information only for the agents under the specified groups.

Format

GET /controller/universalagent/v1/user/agents/summary?agents=<value>

GET /controller/universalagent/v1/user/agents/summary?agents=<value1, value2>&groups=<value>

GET /controller/universalagent/v1/user/agents/summary?groups=<value1, value2>

Query Parameters

Example

curl -i -X GET -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/agents/summary

Response Format

{
    "agent1": {
        "version": <string>,
        "ruleBookName": <string>
    },
    ...
}

Response Fields

• "agent1" is the name of the Universal Agent
• "version" is the key for the version of the Universal Agent
• "ruleBookName" is the key for the name of the Universal Agent's current rulebook

Get Universal Agent By Name

View details for the Universal Agent with a specified name.

Format

GET /controller/universalagent/v1/user/agents/byName/name

Path Parameters

Example

curl -i -X GET -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/agents/byName/agent1

Response Format

{
    "version": <string>,
    "ruleBookName": <string>,
    "environment": {
        "key1": <object>,
        ...
    }
}

Response Fields

• "version" is the key for the version of the Universal Agent
• "ruleBookName" is the key for the name of the Universal Agent's current rulebook
• "environment" is the key for the environment data collected by the Environment Modules

Delete Universal Agent by Name

Delete an agent by name. Deleting an agent also deletes events associated with it.

Format

DELETE /controller/universalagent/v1/user/agents/byName/name

Path Parameters

Example

curl -i -X DELETE -u '<userName>@<accountName>:<password>' 
-H 'Content-type: application/json' 
http://<controller-host>:8080/controller/universalagent/v1/user/agents/byName/agent1

Create or Update a Group 

Creates the group. If the group exists, it is updated. Universal Agent groups are a logical way of grouping different Unifed Agents that are running on different machines. You can add different Universal Agents to a group and then add a common rulebook to that group. All Universal Agents in the group execute the same set of rules (that apply to their environment).

Format

PUT /controller/universalagent/v1/user/groups/byName/name

Path Parameters 

Example 

curl -i -X PUT -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json' 
-H 'Accept:application/json' 
http://<controller-host>:8080/controller/universalagent/v1/user/groups/byName/group1 
-d '{"name":"","comments":"This is group1"}'

Response Format

{
    “name": <string>,
    “comments": <string>
}

Add Universal Agent to a Group

Adds the specified Universal Agent to the specified group.

Format

PUT /controller/universalagent/v1/user/agents/membership/agentName/groups/groupName

Path Parameters

Example

curl -i -X PUT -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
-H 'Accept:application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/agents/membership/agent1/groups/group1

Response Format

{
    "agent1": {
        "version": <string>,
        "ruleBookName": <string>,
        "environment": {
            "key1": <object>,
            ...
        }
    },
    ...
}

Delete Universal Agent From a Group

Deletes the specified Universal Agent from the specified group.

Format

DELETE /controller/universalagent/v1/user/agents/membership/agentName/groups/groupName

Path Parameters

Example

curl -i -X DELETE -su '<userName>@<accountName>:<password>'
-H 'Content-type: application/json' 
-H 'Accept:application/json' 
http://<controller-host>:8080/controller/universalagent/v1/user/agents/membership/agent1/groups/group1

Move Universal Agent to Multiple Groups

Universal Agent is added to multiple groups and removed from previous groups.

Format

PUT /controller/universalagent/v1/user/agents/groupsMembership/agentName

Path Parameters

Example

curl -i -X PUT -su '<userName>@<accountName>:<password>' 
-H 'Content-type: application/json' 
-H 'Accept:application/json' 
http://<controller-host>:8080/controller/universalagent/v1/user/agents/groupsMembership/agent1 
-d '[{"groupName":"group1"},{"groupName":"group2"}]'

Response Format

{
    "agent1": {
        "version": <string>,
        "ruleBookName": <string>,
        "environment": {
            "key1": <object>,
            ...
        }
    },
    ...
}

Get a Group By Name

Return information for the named group. 

Format

GET /controller/universalagent/v1/user/groups/byName/name

Path Parameters

Example

curl -i -X GET -u '<userName>@<accountName>:<password>' 
-H 'Content-type: application/json'  
http://<controller-host>:8080/controller/universalagent/v1/user/groups/byName/group1

Response Format

{
    “name": <string>,
    “comments": <string>
}

Get Multiple Groups

Get all groups or specific groups, groups having specific agents or groups having specific rulebooks.

Format

GET /controller/universalagent/v1/user/groups?groups=group1,group2&agents=agent1,agent2&rulebooks=rulebook1

Query Parameters

Example

curl -i -X GET -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/groups

Response Format

{
    “name": <string>,
    “comments": <string>
},
{
    “name": <string>,
    “comments": <string>
}

Delete a Group

Deletes the group. Deletion of the default group named "default" is not allowed.

Format

DELETE /controller/universalagent/v1/user/groups/byName/name

Path Parameters

Example

curl -i -X DELETE -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/groups/byName/group1

Create or Update a Rulebook

Create a rulebook. If a rulebook with "name" already exists, it is updated.

Format

PUT /controller/universalagent/v1/user/rulebooks/byName/name

Path Parameters

Example

curl -i -X PUT -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
-H 'Accept:application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/rulebooks/byName/rulebook1
-d ' {
 "name": "rulebook1",
 "comments": "An example rulebook with a rule to start a machine agent",
 "config": {
     "controller_host": "localhost",
     "controller_port": "8080",
     "account_name": "",
     "account_access_key": ""
 },
 "rules": [
     {
         "name": "Example rule to start a 4.1.0.0 machine agent",
         "comments": "Enable by changing 'condition' to 'True'. Controller information is inherited from the 'config' section above. The machine agent will be installed in <universal_agent_dir>/monitor/machine/4.1/...",
         "monitor": "machine",
         "config": {
             "version": "4.1.0.0",
             "state": "started"
         },
         "condition": "True"
     }
 ]
}'

Response Format

{
    "name": <string>
    "comments": <string>,
    "config": {
        "key1": <object>
        ...
    },
    "rules": [
        {
            "name": <string>,
            "comments": <string>,
            "monitor": <string>,
            "config": {
                "key1": <object>
                ...
            },
            "condition": <string>
        },
        ...
    ]
}

Response Fields

• "name" is the key for the name of the rulebook
• "comments" is the key for comments describing the rulebook
• "config" is the key for an optional map that is inherited by each rule
• "rules" is the key for a list of rules in the rulebook

Get Rulebooks

View specific rulebooks by name or group or view a list of all rulebooks. Returns the name, comments, and the configuration rules.

Format

GET /controller/universalagent/v1/user/rulebooks 

GET /controller/universalagent/v1/user/rulebooks/byName/name 

GET /controller/universalagent/v1/user/rulebooks/current/groupName

Path Parameters 

Example 

curl -i -X GET -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/rulebooks

Response Format

This version returns a list of rulebooks similar to the following:

[
    {
        "name": <string>,
        "comments": <string>,
        "config": {
            "key1": <object>
            ...
        },
        "rules": [
            {
                "name": <string>,
                "comments": <string>,
                "monitor": <string>,
                "config": {
                    "key1": <object>,
                    ...
                },
                "condition": <string>
            },
            ...
        ]
    },
    ...
]

Example

curl -i -X GET -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/rulebooks/byName/rulebook1

Example

curl -i -X GET -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/rulebooks/current/group1

Response Format

The versions using name and groupName return a single rulebook similar to the following:

{
        "name": <string>,
        "comments": <string>,
        "config": {
            "key1": <object>
            ...
        },
        "rules": [
            {
                "name": <string>,
                "comments": <string>,
                "monitor": <string>,
                "config": {
                    "key1": <object>,
                    ...
                },
                "condition": <string>
            },
            ...
        ]
    }

Response Fields

• "name" is the key for the name of the rulebook
• "comments" is the key for comments describing the rulebook
• "config" is the key for an optional map that is inherited by each rule
• "rules" is the key for a list of rules in the rulebook

Add a Rulebook to a Group

Indicates which rulebook should be used by the universal Agents in the group indicated by groupName.

Format

PUT /controller/universalagent/v1/user/rulebooks/current/groupName

Path Parameters 

Example

curl -i -X PUT -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
-H 'Accept:application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/rulebooks/current/group1
-d '{"ruleBookName":"rulebook1"}'

Response Format

{
    "name": <string>
    "comments": <string>,
    "config": {
        "key1": <object>
        ...
    },
    "rules": [
        {
            "name": <string>,
            "comments": <string>,
            "monitor": <string>,
            "config": {
                "key1": <object>
                ...
            },
            "condition": <string>
        },
        ...
    ]
}

Response Fields

• "name" is the key for the name of the rulebook
• "comments" is the key for comments describing the rulebook
• "config" is the key for an optional map that is inherited by each rule
• "rules" is the key for a list of rules in the rulebook

Get a Rulebook Associated with a Group

View the name of the current book for the specified group of Universal Agents.

Format

GET /universalagent/v1/user/rulebooks/current/groupName 

Path Parameters 

Example

 curl -i -X GET -u '<userName>@<accountName>:<password>' 
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/rulebooks/current/group1

Response Format

{
    "name": <string>
    "comments": <string>,
    "config": {
        "key1": <object>
        ...
    },
    "rules": [
        {
            "name": <string>,
            "comments": <string>,
            "monitor": <string>,
            "config": {
                "key1": <object>
                ...
            },
            "condition": <string>
        },
        ...
    ]
}

Response Fields

• "name" is the key for the name of the rulebook
• "comments" is the key for comments describing the rulebook
• "config" is the key for an optional map that is inherited by each rule
• "rules" is the key for a list of rules in the rulebook

Delete a Rulebook By Name

Removes the rulebook with the specified name. Deleting a rulebook also removes it from any group association. Deletion of the default rulebook named "default-controller" is not allowed.

Format

DELETE /controller/universalagent/v1/user/rulebooks/byName/name

Path Parameters 

Example

curl -i -X DELETE -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/rulebooks/byName/rulebook1

Delete a Rulebook From a Group

Remove a rulebook for Universal Agents by group. Universal Agents without a rulebook execute local rulebooks (thus allowing manual rulebook creation). 
Deletion of the default rulebook named "default-controller" is not allowed. 

Format

DELETE /controller/universalagent/v1/user/rulebooks/current/groupName

Path Parameters

Example

curl -i -X DELETE -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/rulebooks/current/group1

Get All Events

View events that have occurred across all the Universal Agents. When the query parameters are present, the relevant matching subset of events is returned. By default, all events are shown up to the maximum limit of 600 events. 

Format

GET /controller/universalagent/v1/user/events?agentIds=<value1,value2>&eventTypes=<value1,value2>&subTypes=<value>&timeRange=<value>

Query Parameters

Example

curl -i -X GET -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/events

Response Format

[
 {
"id":<long>,
"version":<long>,
"eventType":<string>,
"eventTime":<Date>,
"severity":<string>,
"eventSummary":<string>,
"affectedEntities":[
   {
     "id":<long>,
     "version":<long>,
 "entityType":<string>,
     "entityId":<long>,
     "prettyToString":<string>
   }...,
],

"correlationKeys":[],
"properties":<string>,
"markedAsRead":<boolean>,
"markedAsResolved":<boolean>,
"archived":<boolean>,
"endTime":<long>,
"guid":<string>,
"subType":<string>,
"triggeredEntity":{
    "id":<long>,
    "version":<long>,
 "entityType":<string>,
    "entityId":<long>,
   "prettyToString":<string>
   }
},...
]

Response Fields

• id: id of the event
• version: version of the event
• eventType: type of the event
• eventTime: time when the event was generated
• severity: can be INFO or ERROR
• eventSummary: Brief description of the event
  affectedEntities: 
  • entityType: this is a string representing universal agent, UNIVERSAL_AGENT
  • entityId: id of the Universal aAgent

• correlationKeys: Not applicable for Universal Agent

• properties: Not applicable for Universal Agent

• markedAsRead: Not applicable for Universal Agent

• markedAsResolved: Not applicable for Universal Agent

• archived: Not applicable for Universal Agent

• endTime: Not applicable for Universal Agent

• guid: Not applicable for Universal Agent

• subtype: success or error code
  triggeredEntity:
  • entityType: this is a string representing universal agent: UNIVERSAL_AGENT
  • entityId: id of the universal agent 

Get Event Details

Get event details for all events. The number of events that can be returned is limited to 600. 

Format

GET /controller/universalagent/v1/user/events/details&timeRange=<value>

Query Parameters

Example

curl -i -X GET -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/events/details?timeRange=last_5_minutes.BEFORE_NOW.-1.-1.5 

Response Format 

[
  {
   "eventDetails": [
       {
        "id":<long>,
        "version":<long>,
        "name":<string>,
        "value":<string>
       }
    ]
    eventProperties: [],
    userComments: [ ],
    eventId: <long>
  },...
]

Response Fields

• eventId: id of the event
• version: version of the event
• name: details of the event
• value: Not applicable for Universal Agent

Get Event Details By Event ID

Get details for a specific event by event id.

Format

GET /controller/universalagent/v1/user/events/detailsByEventId/eventId

Path Parameters

Example

curl -i -X GET -u '<userName>@<accountName>:<password>'
-H 'Content-type: application/json'
http://<controller-host>:8080/controller/universalagent/v1/user/events/detailsByEventId/1

Response Format 

{
   "eventDetails": [
       {
        "id":<long>,
        "version":<long>,
        "name":<string>,
        "value":<string>
       }
    ]
    eventProperties: [],
    userComments: [ ],
    eventId: <long>
 }

Response Fields

• eventDetails: Not applicable for Universal Agent
  • id: id of the event
  • version: version of the event
  • name: details of the event
  • value: Not applicable for Universal Agent
• eventProperties: Not applicable for Universal Agent
• userComments: Not applicable for Universal Agent
• eventId: Not applicable for Universal Agent