Upgrade or Downgrade Collectors Using the API

View and manage the software versions of your Installed Collectors through HTTP endpoints. Use these HTTP endpoints to upgrade or downgrade Collectors. We recommend you follow our best practices when you upgrade your Collectors.

warning

Collector Management APIs are not yet built with OpenAPI specifications and therefore not included in our Swagger docs. Instead, refer to the below documentation.

The upgrade may automatically be done in increments. In this case, you may experience longer upgrade times.

There is a community-supported script available on GitHub that allows you to conduct bulk actions to Collectors, see Collector Management Script.

Timeout

If an upgrade task does not complete successfully after 30 minutes, it will automatically time out with a status of failed.

GET methods

Get upgradable Collectors

GETcollectors/upgrades/collectors

Sends a request to get Collectors you can upgrade.

Request Headers

Key	Value
Content-Type	`application/json`
Accept	`application/json`

Query Parameters

Parameter	Type	Required	Default	Description
`toVersion`	String	No	Latest Version	Collector build to upgrade (or downgrade) to. If not specified, upgrades to the latest version.
`offset`	Int	No	0	Offset into the list of Collectors.
`limit`	Int	No	50	Maximum number of Collectors to return.

Status Code

Code	Text	Description
`200`	OK	Upgradable Collectors were retrieved and provided in the response payload.
`415`	Unsupported Media Type	Content-Type wasn't set to `application/json`.
`400`	Bad Request	A parameter wasn't valid.

Success Result

A JSON document containing the upgradable collectors.

Sample Session

Sample request
curl -i -u "<accessId>:<accessKey>" -X GET https://api.sumologic.com/api/v1/collectors/upgrades/collectors

Sample response
{
    "collectors": [
        {
            "id": 100000000,
            "name": "SumoCollector_Local",
            "hostName": "TestHost",
            "timeZone": "UTC",
            "links": [
                {
                    "rel": "sources",
                    "href": "/v1/collectors/100000000/sources"
                }
            ],
            "ephemeral": false,
            "sourceSyncMode": "UI",
            "collectorType": "Installable",
            "collectorVersion": "20.1-2749",
            "osVersion": "10.11.5",
            "osName": "Mac OS X",
            "osArch": "x86_64",
            "lastSeenAlive": 1465848876035,
            "alive": true
        }
    ]
}

Get available builds

GET/collectors/upgrades/targets

Request Headers

Key	Value
Content-Type	`application/json`
Accept	`application/json`

Query Parameters

None

Status Code

Code	Text	Description
`200`	OK	The build information has been returned in the response payload.
`415`	Unsupported Media Type	Content-Type wasn't set to `application/json`.

Success Result

A JSON document containing the versions of collector builds, which includes the following fields.

Field	Data Type	Description
`version`	string	Version of the collector build.
`latest`	boolean	Whether it's the latest version.

Examples

Sample request
curl -i -u "<accessId>:<accessKey>" -X GET https://api.sumologic.com/api/v1/collectors/upgrades/targets

Sample response
{
  "targets": [
  {
    "version": "19.115-37",
    "latest": false
  },
  ...
  {
    "version": "20.1-2749",
    "latest": true
  }
 ]
}

Get upgrade task status

GET/collectors/upgrades/{upgradeTaskID}

After obtaining the upgrade job ID, you can obtain the status of the upgrade task from the status endpoint.

Request Headers

Key	Value
Content-Type	`application/json`
Accept	`application/json`

Query Parameters

Parameter	Type	Required	Description
`upgradeTaskID`	Long	Yes	Task ID from the upgrade task.

Status Code

Code	Text	Description
`200`	OK	The upgrade task status has been returned in the response.
`415`	Unsupported Media Type	Content-Type wasn't set to `application/json`.
`404`	Not found	The upgrade task ID was not found.

Success Result

A success result generates a JSON document containing the upgrade task status, including the following fields.

Field	Description
`collectorId`	Collector ID of this upgrade task (long).
`toVersion`	Target version of this upgrade task (string).
`requestedTime`	UNIX timestamp when the upgrade task is requested (long).
status	Status code for the upgrade task (integer): 0 - not started 1 - pending, the upgrade is issued awaiting a response from the Collector. 2 - succeeded 3 - failed 6 - Progressing, the upgrade is running on the Collector.
`message`	Any additional message, normally a failed reason (string).

Sample session

Sample request
curl -i -u "<accessId>:<accessKey>" -X GET https://api.sumologic.com/api/v1/collectors/upgrades/12345

Sample response
{
    "upgrade": {
        "id": 12345,
        "collectorId": 100000000,
        "toVersion": "19.152-1",
        "requestTime": 1465855411044,
        "status": 2,
        "message": ""
    }
}

POST Methods

Create an upgrade or downgrade task

POST/collectors/upgrades

Request Headers

Key	Value
Content-Type	`application/json`
Accept	`application/json`

Query Parameters

None

JSON Payload Parameters

Parameter	Type	Required	Default	Description
collectorId	Long	Yes		Identifier of the Collector to upgrade (or downgrade).
toVersion	String	No	Latest version	Collector build to upgrade (or downgrade) to. If not specified, upgrades to the latest version.

Status Code

Code	Text	Description
202	Accepted	The upgrade task has been created successfully.
415	Unsupported Media Type	`Content-Type` wasn't set to `application/json`.
400	Bad Request	Generic request error by the client.

Success Result

With success, a JSON document is returned containing the ID and link of the newly created upgrade task. This is an opaque string to use for following upgrade status checking API.

Error Result

A status code 400 will be returned with following error codes.

Code	Description
collector.invalid	The Collector ID was not provided, doesn't exist, or the user doesn't have permission to use it.
collector.type.invalid	The Collector is not an Installed Collector (it is a Hosted Collector).
collector.not.alive	The Collector is not running.
collector.in.upgrading	The Collector is currently being upgraded.
collector.version.invalid	The upgrade version was not provided, or the version is not valid.

Sample Session

Sample request
curl -i -u "<accessId>:<accessKey>" -H "Content-Type: application/json" -X POST -d '{"collectorId":100000000,"toVersion":"19.152-1"}'
https://api.sumologic.com/api/v1/collectors/upgrades

Sample response
{
    "id": "12345",
    "link": {
        "rel": "self",
        "href": "/v1/collectors/upgrades/12345"
    }
}

Timeout​

GET methods​

Get upgradable Collectors​

Get available builds​

Examples​

Get upgrade task status​

POST Methods​

Create an upgrade or downgrade task​

Timeout

GET methods

Get upgradable Collectors

Get available builds

Examples

Get upgrade task status

POST Methods

Create an upgrade or downgrade task