Skip to main content
Sumo Logic

Upgrade or Downgrade Collectors Using the API

Use this API to upgrade or downgrade a Collector and manage upgrade tasks.

Create an upgrade or downgrade task

Method: POST 
Path: /collectors/upgrades

Request headers

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

Query Parameters

Parameter Type Required Default Description
collectorId Long Yes   ID 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"
    }
} 

Get upgrade task status

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

Method: GET 
Path: /collectors/upgrades/{upgradeID}

Request Headers

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

Query Parameters

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

Status Code

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

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 but not responsed by 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 <user>:<password> -X GET

Sample response:

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

Get Collectors ready for upgrade

Method: GET 
Path: collectors/upgrades/collectors

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 1000 Max number of Collectors to return.

Status Code

Code Text Description
200 OK The Collectors has been returned in response.
415 Unsupported Media Type Content-Type wasn't set to application/json.
400 Bad Request Parameter is not valid.

Success Result

A JSON document containing the upgradable collectors.

Sample Session

Sample request:

curl -i -u <user>:<pass> -X GET https://api.sumologic.com/api/v1/collectors/upgrades/collectors?toVersion=19.155-
1

 

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 information

Method: GET 
Path: /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 response.
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 following fields

Field Description
version (string) Version of the collector build
latest (boolean) Whether the version is latest one.

Sample Session

Sample request:

curl -i -u <user>:<pass> -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
        }
    ]
}