Skip to main content

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

KeyValue
Content-Typeapplication/json
Acceptapplication/json

Query Parameters

ParameterTypeRequiredDefaultDescription
toVersionStringNoLatest VersionCollector build to upgrade (or downgrade) to. If not specified, upgrades to the latest version.
offsetIntNo0Offset into the list of Collectors.
limitIntNo50Maximum number of Collectors to return.

Status Code

CodeTextDescription
200OKUpgradable Collectors were retrieved and provided in the response payload.
415Unsupported Media TypeContent-Type wasn't set to application/json.
400Bad RequestA 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

KeyValue
Content-Typeapplication/json
Acceptapplication/json

Query Parameters

None

Status Code

CodeTextDescription
200OKThe build information has been returned in the response payload.
415Unsupported Media TypeContent-Type wasn't set to application/json.

Success Result

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

FieldData TypeDescription
versionstringVersion of the collector build.
latestbooleanWhether 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

KeyValue
Content-Typeapplication/json
Acceptapplication/json

Query Parameters

ParameterTypeRequiredDescription
upgradeTaskIDLongYesTask ID from the upgrade task.

Status Code

CodeTextDescription
200OKThe upgrade task status has been returned in the response.
415Unsupported Media TypeContent-Type wasn't set to application/json.
404Not foundThe upgrade task ID was not found.

Success Result

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

FieldDescription
collectorIdCollector ID of this upgrade task (long).
toVersionTarget version of this upgrade task (string).
requestedTimeUNIX timestamp when the upgrade task is requested (long).
statusStatus 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.
messageAny 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

KeyValue
Content-Typeapplication/json
Acceptapplication/json

Query Parameters

None

JSON Payload Parameters

ParameterTypeRequiredDefaultDescription
collectorIdLongYesIdentifier of the Collector to upgrade (or downgrade).
toVersionStringNoLatest versionCollector build to upgrade (or downgrade) to. If not specified, upgrades to the latest version.

Status Code

CodeTextDescription
202AcceptedThe upgrade task has been created successfully.
415Unsupported Media TypeContent-Type wasn't set to application/json.
400Bad RequestGeneric 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.

CodeDescription
collector.invalidThe Collector ID was not provided, doesn't exist, or the user doesn't have permission to use it.
collector.type.invalidThe Collector is not an Installed Collector (it is a Hosted Collector).
collector.not.aliveThe Collector is not running.
collector.in.upgradingThe Collector is currently being upgraded.
collector.version.invalidThe 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"
}
}
Status
Legal
Privacy Statement
Terms of Use

Copyright © 2024 by Sumo Logic, Inc.