LATEST VERSION: 3.2 - CHANGELOG
Pivotal tc Server v3.2

Agent Management API

Note: Spring Insight templates are no longer supported. The documentation is here for reference only.

The agent management API has commands for managing agents, plugins, tracing, and user-defined endpoints. The API URL for an Insight Agent begins with insight_ur l/services/agent-management/.

agents

GET /services/agent-management/agents

Returns a list of agents and their attributes.

Parameters

Table 1. Command Options
Parameter Description Default
pageNum Page number to return, first page is 1.

(Optional)

1
pageSize Size of each page.

(Optional)

20

Example Request

GET http://localhost:8080/insight/services/agent-management/agents
{
    "agents": [
        {
            "name": "tal-ubuntu.local-27889",
            "id": "42fbe22c-864d-408c-8d29-d0803a06020d",
            "roles": ["AGENT", "ANALYZER", "DASHBOARD"],
            "version": "1.9.0-CI-SNAPSHOT",
            "status": "on",
            "heartbeat": 15,
            "licensed": true,
            "sameVersionAsDashboard": true,
            "througput": 200,
            "lastHeartBeat": 1339331100771,
            "clockSkew": 0,
            "installPath": "/work/env/apache-tomcat-7.0.50",
            "containerName": "Tomcat",
            "containerVersion": "7.0.50",
            "toggleUrl": "/services/agent-management/agents/status",
            "toggleMethod": "PUT",
            "toggleBody": "{\"status\":\"off\",\"agentId\":\"42fbe22c-864d-408c-8d29-d0803a06020d\"}"
        }
    ]
}

Notes

  • You can use the properties prefaced bytoggle to start or stop an agent.
  • If you use the paging options, the results include page data:

    {
        "agents": [
            {
                "name": "tal-ubuntu.local-27889",
                 ...
            }],
        "currentPage": 2,
        "totalPages": 20,
        "pageSize": 10,
        "nextPage": "/services/agent-management/agents?pageSize=10&pageNum=3"
        "prevPage": "/services/agent-management/agents?pageSize=10&pageNum=1"
    }
    

GET /services/agent-management/agents/{agent id}

Returns the details for one agent.

Example Request

GET http://localhost:8080/insight/services/agent-management/agents/42fbe22c-864d-408c-8d29-d0803a06020d
{
    "name": "tal-ubuntu.local-27889",
    "id": "42fbe22c-864d-408c-8d29-d0803a06020d",
    "roles": ["AGENT", "ANALYZER", "DASHBOARD"],
    "version": "1.9.0-CI-SNAPSHOT",
    "status": "on",
    "heartbeat": 15,
    "licensed": true,
    "sameVersionAsDashboard": true,
    "througput": 200,
    "lastHeartBeat": 1339331160771,
    "clockSkew": 0,
    "installPath": "/work/env/apache-tomcat-7.0.50",
    "containerName": "Tomcat",
    "containerVersion": "7.0.50",
    "toggleUrl": "/services/agent-management/agents/status",
    "toggleMethod": "PUT",
    "toggleBody": "{\"status\":\"off\",\"agentId\":\"42fbe22c-864d-408c-8d29-d0803a06020d\"}"
}

Notes -

  • You can use the properties prefaced bytoggle to start or stop an agent.

PUT /services/agent-management/agents/status

Turns an agent on or off.

Example Request

PUT http://localhost:8080/insight/services/agent-management/agents/status

Put body:

{"status":"on","agentId":"42fbe22c-864d-408c-8d29-d0803a06020d"}

Response

200 for success; otherwise 500.

Setting multiple agents’ status

Set the value of multiple agents with one call to /agents/status by sending a list of statuses in the PUT body. This is especially useful for batch operations in UI grids.

[{"status":"off","agentId":"123"}, {"status":"on","agentId":"456"}]

Plugins

GET /services/agent-management/plugins

Returns a list of plugins and their properties.

Parameters

Table 2. Command Options
Parameter Description Default
pageNum Page number to return, first page is 1.

(Optional)

1
pageSize Size of each page.

(Optional)

20

Example Request

GET http://localhost:8080/insight/services/agent-management/plugins
{
    "plugins": [
        {
            "name": "annotation",
            "version": "1.9.0-CI-SNAPSHOT",
            "href": "http://www.springsource.org/insight",
            "publisher": "Pivotal",
            "status": "on",
            "toggleUrl": "/services/agent-management/plugins/status",
            "toggleMethod": "PUT",
            "toggleBody": "{\"pluginName\":\"annotation\",\"status\":\"off\"}"
        },
        {
            "name": "apache-httpclient3",
            "version": "1.9.0-CI-SNAPSHOT",
            "href": "http://www.springsource.org/insight",
            "publisher": "Pivotal",
            "status": "on",
            "toggleUrl": "/services/agent-management/plugins/status",
            "toggleMethod": "PUT",
            "toggleBody": "{\"pluginName\":\"apache-httpclient3\",\"status\":\"off\"}"
        }
   ]
}

Notes -

  • You can use the properties prefaced by toggle to start or stop a plugin.
  • If you use the paging options, the results include page data:

    {
        "plugins": [
            {
                "name": "tal-ubuntu.local-27889",
                 ...
            }],
        "currentPage": 2,
        "totalPages": 20,
        "pageSize": 10,
        "nextPage": "/services/agent-management/plugins?pageSize=10&pageNum=3"
        "prevPage": "/services/agent-management/plugins?pageSize=10&pageNum=1"
    }
    

PUT /services/agent-management/plugins/status

Turns a plugin on or off.

Example Request

PUT http://localhost:8080/insight/services/agent-management/plugins/status

Put Body

{"status":"on","pluginName":"tomcat"}

Allowable values for “status” are “on” or “off”

Response

200 for success; otherwise 500.

Setting multiple plugins status

Set the value of multiple plugins with one call to /plugins/status by sending a list of statuses in the PUT body. This is especially useful for batch operations in UI grids.

[{"status":"off","pluginName":"tomcat"}, {"status":"on","pluginName":"annotation"}]

Collection Strategies

GET /services/agent-management/strategy/tracing

Get the cross server tracing ratio.

Example Request

GET http://localhost:8080/insight/services/agent-management/strategy/tracing
{"ratio": 10}

PUT /services/agent-management/strategy/tracing

Set the cross server tracing ratio.

Example Request

PUT http://localhost:8080/insight/services/agent-management/strategy/tracing

Put Body

{"ratio": 10}

Valid values for “ratio” are 0-100.

Response

200 for success; otherwise 500.

User Defined End point Analyzers

GET /services/agent-management/userdefinedendpoints

Returns a list of all user defined end point analyzers

Parameters

Table 3. Command Options
Parameter Description Default
pageNum Page number to return, first page is 1.

(Optional)

1
pageSize Size of each page.

(Optional)

20

Example Request

GET http://localhost:8080/insight/services/agent-management/userdefinedendpoints
{
    "user_defined_analyzers": [
        {
            "operationType": "spring_event_publish",
            "className": "org.springframework.context.event.SimpleApplicationEventMulticaster",
            "methodSignature": "multicastEvent",
            "key": "51010fe51",
            "deleteUrl": "/services/agent-management/userdefinedendpoints/delete",
            "deleteMethod": "PUT",
            "deleteBody": "{\"key\":\"51010fe51\"}"
        }
    ]
}

Note -

To delete a user defined endpoint analyzer, use the properties prefaced by toggle.

PUT /services/agent-management/agents/userdefinedendpoints/create

Creates one or more user defined endpoint analyzers.

Example Request

PUT http://localhost:8080/insight/services/agent-management/userdefinedendpoints/create

Put Body

[{"className":"org.springframework.context.event.SimpleApplicationEventMulticaster","methodSignature":"multicastEvent","operationTypeString":"spring_event_publish"}]

Response

200 for success; otherwise 500.

PUT /services/agent-management/agents/userdefinedendpoints/delete

Deletes one or more user defined endpoint analyzers.

Example Request

PUT http://localhost:8080/insight/services/agent-management/userdefinedendpoints/delete

Put Body

[{"key":"51010fe51"}]

Response

200 for success; otherwise 500.

Deleting or creating multiple user defined endpoint analyzers

You can delete/create multiple user defined endpoint analyzers with one call by sending a list in the PUT body.

[{"key":"51010fe51"}, {"key":"51010fe52"}]