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).

to

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

to

String

No

Org Download Version

The version to upgrade to. If not specified, uses the original download 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?to=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
        }
    ]
}