Skip to main content

Collector API Methods and Examples

The Collector Management API gives you the ability to manage Collectors and Sources from HTTP endpoints.

danger

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

Before You Begin

info

You need the Manage or View Collectors role capability to manage or view Collection configurations.

See the following topics for additional information:

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

To determine which Sumo Logic API endpoint you should use, find the deployment pod referenced in your browser's Sumo Logic service URL.

If you see https://service.us2.sumologic.com, for example, that means you're running on the US2 pod and need to use the API endpoint https://api.us2.sumologic.com/api/. For the service URL https://service.eu.sumologic.com, you'd need to use the API endpoint https://api.eu.sumologic.com/api/, and so on. The only exception is the US1 pod (https://service.sumologic.com), which uses the API endpoint https://api.sumologic.com/api/.

To view all available endpoints, see Sumo Logic Endpoints.

Collector API Methods and Examples

The Collector Management API allows you to manage Collectors and Sources from an HTTP endpoint. This topic describes the Collector API parameters, methods, and lists error codes.

Rate limiting

  • A rate limit of four API requests per second (240 requests per minute) applies to all API calls from a user.
  • A rate limit of 10 concurrent requests to any API endpoint applies to an access key.

If a rate is exceeded, a rate limit exceeded 429 status code is returned.

Response fields

The following table lists the API response fields for installed and hosted Collectors.

ParameterTypeRequired?DefaultDescriptionAccess
aliveBooleanYesWhen a Collector is running it sends Sumo a heartbeat message every 15 seconds. If no heartbeat message is received after 30 minutes this becomes false.Transient
categoryStringNoNullThe Category of the Collector, used as metadata when searching data.Modifiable
collectorTypeStringThe Collector type: Installable or HostedNot modifiable
collectorVersionStringYesVersion of the Collector software installed.Transient
cutoffRelativeTimeStringNoCan be specified instead of cutoffTimestamp to provide a relative offset with respect to the current time. Example: use "-1h", "-1d", or "-1w" to collect data that's less than one hour, one day, or one week old, respectively. (Note that if you set this property to a relative time that overlaps with data that was previously ingested on a source, it may result in duplicated data to be ingested into Sumo Logic.)Not modifiable
cutoffTimestampLongNo0 (collects all data)Only collect data from files with a modified date more recent than this timestamp, specified as milliseconds since epoch. (Note that if you set this property to a timestamp that overlaps with data that was previously ingested on a source, it may result in duplicated data to be ingested into Sumo Logic.)Modifiable
descriptionStringNoNullDescription of the Collector.Modifiable
ephemeralBooleanYesWhen true, the collector will be deleted after 12 hours of inactivity. For more information, see Setting a Collector as Ephemeral.Modifiable
fieldsJSON ObjectNoJSON map of key-value fields (metadata) to apply to the Collector. To assign an Ingest Budget to the Collector use the field _budget with the Field Value of the Ingest Budget to assign. For example, if you have a budget with a Field Value of Dev_20GB, you would add:

fields=_budget=Dev_20GB

Modifiable
hostNameStringNoNullHost name of the Collector. The hostname can be a maximum of 128 characters.Modifiable
idLongYesIdentifierNot modifiable
lastSeenAliveLongNoThe last time the Sumo Logic service received an active heartbeat from the Collector, specified as milliseconds since epoch.Transient
nameStringYesName of the Collector. It must be unique on your account.Modifiable
sourceSyncModeStringNoUIFor installed Collectors, whether the Collector is using local source configuration management (using a JSON file), or cloud management (using the UI)Modifiable

To assign to JSON, learn more.

timeZoneStringNoNullTime zone of the Collector. For a list of possible values, refer to the "TZ" column in this Wikipedia article.Modifiable
targetCpuLongNoNullWhen CPU utilization exceeds this threshold, the Collector will slow down its rate of ingestion to lower its CPU utilization. Currently only Local and Remote File Sources are supported. The value must be expressed as a whole number percentage. The collector will adjust resources to attempt to limit the CPU usage to at most 20%. For more information, see Set the Collector CPU Usage Target.Modifiable

The following table lists additional response fields for Installed Collectors only.

ParameterTypeRequired?DescriptionAccess
osNameStringYesName of OS that Collector is installed on.Not modifiable
osVersionStringYesVersion of the OS that Collector is installed on.Not modifiable
osArchYesArchitecture of the OS that Collector is installed on.Not modifiable
osTimeLongYesTime that the Collector has been running, in milliseconds.Not modifiable

GET methods

List Collectors

Get a list of Collectors with an optional limit and offset.

Method: GET Path: /collectors

ParameterTypeRequired?DefaultDescription
filterStringNoAll CollectorsFilter the Collectors returned using one of the available filter types: installed, hosted, dead, or alive.
limitIntegerNo1000Max number of Collectors to return.
offsetIntegerNo0Offset into the list of Collectors.

Example

In this example, setting limit=10 limits the responses to 10.

Request:

curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors?limit=10

Response:

{  
"collectors":[
{
"id":2,
"name":"OtherCollector",
"collectorType":"Installable",
"alive":true,
"links":[
{
"rel":"sources",
"href":"/v1/collectors/2/sources"
}
],
"collectorVersion":"19.33-28",
"ephemeral":false,
"description":"Local Windows Collection",
"osName":"Windows 7",
"osArch":"amd64",
"osVersion":"6.1",
"category":"local"
},
...
]
}

List Offline Collectors

Get a list of Installed Collectors last seen alive before a specified number of days with an optional limit and offset.

Method: GET Path: /collectors/offline

ParameterTypeRequired?DefaultDescription
aliveBeforeDaysIntegerNo100Minimum number of days the Collectors have been offline. Must be at least 1 day.
limitIntegerNo1000Max number of Collectors to return.
offsetIntegerNo0Offset into the list of Collectors.

Example

In this example, setting aliveBeforeDays=10 returns a list of Installed Collectors that have been offline for at least 10 days.

Request:

curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/offline?aliveBeforeDays=10

Response:

{
"collectors":[{
"id":101622144,
"name":"My Installed Collector",
"timeZone":"Etc/UTC",
"fields":{
"_budget":"test_budget"
},
"links":[{
"rel":"sources",
"href":"/v1/collectors/101622144/sources"
}],
"ephemeral":false,
"targetCpu":-1,
"sourceSyncMode":"UI",
"collectorType":"Installable",
"collectorVersion":"19.162-12",
"osVersion":"10.12.6",
"osName":"Mac OS X",
"osArch":"x86_64",
"lastSeenAlive":1521143016128,
"alive":false
}]
}

Get Collector by ID

Get the Collector with the specified Identifier.

Method: GET Path: /collectors/[id]

ParameterTypeRequired?DefaultDescription
idIntegerYesNAUnique identifier of the Collector.

Example

This example gets the Collector with an ID of 25.

Request:

curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/25

Response:

{
"collector":{
"id":25,
"name":"dev-host-1",
"timeZone":"UTC",
"ephemeral":false,
"sourceSyncMode":"Json",
"collectorType":"Installable",
"collectorVersion":"19.162-12",
"osVersion":"3.13.0-92-generic",
"osName":"Linux",
"osArch":"amd64",
"lastSeenAlive":1471553524302,
"alive":true
}
}

Get Collector by Name

Method: GET Path: /collectors/name/[name]

ParameterTypeRequired?DefaultDescription
nameStringYesNAName of the Collector.

Rules

  • Names with special characters are not supported, such as ; / % \ even if they are URL encoded.
  • Spaces in names are supported when they are URL encoded. A space character URL encoded is %20. For example, a Collector named Staging Area would be encoded as https://api.sumologic.com/api/v1/collectors/name/Staging%20Area.
  • Names with a period . need to have a trailing forward slash / at the end of the request URL. For example, a Collector named Staging.Area should be provided as https://api.sumologic.com/api/v1/collectors/name/Staging.Area/.

Example

This example gets the Collector with the name test.

Request:

curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/name/test

Response:

{
"collector":{
"id":31,
"name":"test",
"timeZone":"UTC",
"ephemeral":false,
"sourceSyncMode":"Json",
"collectorType":"Installable",
"collectorVersion":"19.162-12",
"osVersion":"3.13.0-92-generic",
"osName":"Linux",
"osArch":"amd64",
"lastSeenAlive":1471553524302,
"alive":true
}
}

POST methods

Create Hosted Collector

Use the POST method with a JSON file to create a new Hosted Collector. The required parameters can be referenced in the Response fields table above. Note that "id" field should be omitted when creating a new Hosted Collector.

This method can only be used to create Hosted Collectors. You must install a Collector manually to create an Installed Collector.

Method: POST Path: /collectors

Example

This example creates a new Hosted Collector using the parameters in the JSON file.

Request:

curl -u '<accessId>:<accessKey>' -X POST -H "Content-Type: application/json" -T hosted_collector.json https://api.sumologic.com/api/v1/collectors

Request JSON (hosted_collector.json):

{
"collector":{
"collectorType":"Hosted",
"name":"My Hosted Collector",
"description":"An example Hosted Collector",
"category":"HTTP Collection",
"fields": {
"_budget":"test_budget"
}
}
}

Response:

{
"collector":{
"id":102087219,
"name":"My Hosted Collector",
"description":"An example Hosted Collector",
"category":"HTTP Collection",
"timeZone":"UTC",
"fields":{
"_budget":"test_budget"
},
"links":[{
"rel":"sources",
"href":"/v1/collectors/102087219/sources"
}],
"collectorType":"Hosted",
"collectorVersion":"",
"lastSeenAlive":1536618284387,
"alive":true
}

PUT methods

Update a Collector

Use the PUT method with your JSON file to update an existing Collector. Available parameters can be referenced in the Response fields table above. The JSON request file must specify values for all required fields. Not modifiable fields must match their current values in the system. This is in accordance with HTTP 1.1 RFC-2616 Section 9.6.

Updating a Collector also requires the "If-Match" header to be specified with the "ETag" provided in the headers of a previous GET request.

Method: PUT Path: /collectors/[id]

ParameterTypeRequired?DefaultDescription
idIntegerYesNAID of the Collector.

Example

This example changes the Collector to set the parameter "ephemeral" to true.

First, use a GET request with -v flag to obtain the "ETag" header value.

Initial GET Request:

curl -v -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/15

Initial GET Response:

< HTTP/1.1 200 OK
< ETag: "f58d12c6986f80d6ca25ed8a3943daa9"
...
{
"collector":{
"id":15,
"name":"dev-host-1",
"timeZone":"UTC",
"ephemeral":false,
"sourceSyncMode":"Json",
"collectorType":"Installable",
"collectorVersion":"19.162",
"osVersion":"3.13.0-92-generic",
"osName":"Linux",
"osArch":"amd64",
"lastSeenAlive":1471553974526,
"alive":true
}
* Connection #0 to host api.sumologic.com left intact

Next, modify the Collector's JSON attributes as needed (in this example, setting "ephemeral" to "true"), and use a PUT request, passing the "ETag" value obtained above with the "If-Match" header.

Request:

curl -u '<accessId>:<accessKey>' -X PUT -H "Content-Type: application/json" -H "If-Match: \"f58d12c6986f80d6ca25ed8a3943daa9\"" -T updated_collector.json https://api.sumologic.com/api/v1/collectors/15

Request JSON (updated_collector.json):

{
"collector":{
"id":15,
"name":"dev-host-1",
"timeZone":"UTC",
"ephemeral":true,
"sourceSyncMode":"Json",
"collectorType":"Installable",
"collectorVersion":"19.162",
"osVersion":"3.13.0-92-generic",
"osName":"Linux",
"osArch":"amd64",
"lastSeenAlive":1471553974526,
"alive":true
}
}

Response:

{
"collector":{
"id":15,
"name":"dev-host-1",
"timeZone":"UTC",
"ephemeral":true,
"sourceSyncMode":"Json",
"collectorType":"Installable",
"collectorVersion":"19.162",
"osVersion":"3.13.0-92-generic",
"osName":"Linux",
"osArch":"amd64",
"lastSeenAlive":1471554424736,
"alive":true
}
}

DELETE methods

Delete Collector by ID

Use the DELETE method to delete an existing Collector.

Method: DELETE Path: /collectors/[id]

ParameterTypeRequired?DefaultDescription
idIntegerYesNAUnique identifier of the Collector.

This example deletes the Collector with ID 15.

Request:

curl -u '<accessId>:<accessKey>' -X DELETE https://api.sumologic.com/api/v1/collectors/15

Response: There will be no response body, only a 200 OK response code.

Delete Offline Collectors

Delete Installed Collectors last seen alive before a specified number of days.

Method: DELETE Path: /collectors/offline

ParameterTypeRequired?DefaultDescription
aliveBeforeDaysIntegerNo100The minimum number of days the Collectors have been offline. Must be at least 1 day.

Example

In this example, setting aliveBeforeDays=10 deletes all the Installed Collectors that have been offline for at least 10 days.

Request:

curl -u '<accessId>:<accessKey>' -X DELETE https://api.sumologic.com/api/v1/collectors/offline?aliveBeforeDays=10

Response:

There will be no response body, only a 200 OK response with the message "The delete task has been initiated.". To check the status make GET requests and see if the Collectors have been deleted.

Error Codes and Messages

CodeMessage
BadRequestCollectorIdRequest body contains an invalid Collector ID.
CannotModifyCollectorUser is not authorized to modify the specified Collector.
CollectorDescriptionTooLongMaximum description length is 1024 characters.
CollectorNameTooLongMaximum name length is 128 characters.
createValidationErrorThe specified ID is invalid.
DuplicateResourceNameA resource with the same name already exists.
InvalidCollectorThe specified Collector ID is invalid.
InvalidCollectorTypeInvalid Collector type for the requested operation.
Legal
Privacy Statement
Terms of Use

Copyright © 2024 by Sumo Logic, Inc.