Collector API Methods and Examples
The Collector Management API gives you the ability to manage Collectors and Sources from HTTP endpoints.
Collector Management APIs are not yet built with OpenAPI specifications and therefore not included in our Swagger docs. Instead, refer to the below documentation.
Prerequisites
You need the Manage or View Collectors role capability to manage or view Collection configurations.
See the following topics for additional information:
- API Authentication for information on API authentication options.
- Sumo Logic Endpoints for a list of API endpoints to use to connect your API client to the Sumo Logic API.
- Use JSON to Configure Sources for a description of Source parameters.
- View or Download Collector or Source JSON Configuration for instructions on viewing or downloading the current JSON configuration file for a collector or source from the web application.
- Troubleshooting APIs for information on troubleshooting Sumo Logic API errors.
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 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.
Parameter | Type | Required? | Default | Description | Access |
alive | Boolean | Yes | When 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 | |
category | String | No | Null | The Category of the Collector, used as metadata when searching data. | Modifiable |
collectorType | String | The Collector type: Installable or Hosted | Not modifiable | ||
collectorVersion | String | Yes | Version of the Collector software installed. | Transient | |
cutoffRelativeTime | String | No | Can 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 | |
cutoffTimestamp | Long | No | 0 (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 |
description | String | No | Null | Description of the Collector. | Modifiable |
ephemeral | Boolean | Yes | When true, the collector will be deleted after 12 hours of inactivity. For more information, see Setting a Collector as Ephemeral. | Modifiable | |
fields | JSON Object | No | JSON 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:
| Modifiable | |
hostName | String | No | Null | Host name of the Collector. The hostname can be a maximum of 128 characters. | Modifiable |
id | Long | Yes | Identifier | Not modifiable | |
lastSeenAlive | Long | No | The last time the Sumo Logic service received an active heartbeat from the Collector, specified as milliseconds since epoch. | Transient | |
name | String | Yes | Name of the Collector. It must be unique on your account. | Modifiable | |
sourceSyncMode | String | No | UI | For 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 |
timeZone | String | No | Null | Time zone of the Collector. For a list of possible values, refer to the "TZ" column in this Wikipedia article. | Modifiable |
targetCpu | Long | No | Null | When 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.
Parameter | Type | Required? | Description | Access |
---|---|---|---|---|
osName | String | Yes | Name of OS that Collector is installed on. | Not modifiable |
osVersion | String | Yes | Version of the OS that Collector is installed on. | Not modifiable |
osArch | Yes | Architecture of the OS that Collector is installed on. | Not modifiable | |
osTime | Long | Yes | Time that the Collector has been running, in milliseconds. | Not modifiable |