Source API Methods and Examples
The Collector Management API allows you to manage Collectors and Sources from an HTTP endpoint. This topic describes the Source API methods, which you can use to create installed or hosted Sources of any type by specifying the sourceType
parameter. When using local configuration file management you can no longer manage Sources through the Collector Management API.
See the following topics for additional information:
- API Authentication for information on API authentication options.
- Sumo Logic Endpoints for a list of the API endpoints to use to connect your API client to the Sumo Logic API.
- Collector API Methods and Examples for Collector API methods.
- Use JSON to Configure Sources for a description of Source parameters.
Response fields
See Use JSON to Configure Sources for a description of Source parameters.
GET methods
List Sources
Gets information about all Sources for a specified Collector.
Method: GET Path: /collectors/[collectorId]/sources
Parameter | Type | Required? | Default | Description |
collectorId | integer | Yes | NA | Unique Collector identifier. |
download | boolean | No | false | When set to true , the response will be a JSON array of Sources that can be used to register a new Collector. |
Examples
This example gets all Sources for a Collector.
Request:
curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/25/sources
Response:
{ "sources":[{ "id":101792472, "name":"collector_logs", "category":"collector_logs", "hostName":"dev-host-1", "automaticDateParsing":true, "multilineProcessingEnabled":true, "useAutolineMatching":true, "forceTimeZone":false, "filters":[], "cutoffTimestamp":0, "encoding":"UTF-8", "pathExpression":"/usr/logs/collector/collector.log*", "blacklist":[], "sourceType":"LocalFile", "alive":true }, ... ] }
This example gets a ready-to-go JSON configuration of the Sources of a Collector, which can be used to register a new Collector.
Request:
curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/25/sources?download=true
Response:
{ "api.version": "v1", "sources":[{ "name":"collector_logs", "category":"collector_logs", "hostName":"dev-host-1", "automaticDateParsing":true, "multilineProcessingEnabled":true, "useAutolineMatching":true, "forceTimeZone":false, "filters":[], "cutoffTimestamp":0, "encoding":"UTF-8", "pathExpression":"/usr/logs/collector/collector.log*", "blacklist":[], "sourceType":"LocalFile" }, ... ] }
Get Source by ID
Gets information about a specified Collector and Source.
Method: GET Path: /collectors/[collectorId]/sources/[sourceId]
Parameter | Type | Required? | Default | Description |
collectorId | integer | Yes | NA | Unique Collector identifier. |
sourceId | integer | Yes | NA | Unique Source identifier. |
download | boolean | No | false | When set to true , the response will be a JSON Source object that can be used to create a new Source. |
Examples
This example gets data for a Source with a specified ID.
Request:
curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/25/sources/101792472
Response:
{ "source":{ "id":101792472, "name":"collector_gc", "category":"collector_gc", "hostName":"nite-receiver-1", "automaticDateParsing":true, "multilineProcessingEnabled":true, "useAutolineMatching":true, "forceTimeZone":false, "filters":[], "cutoffTimestamp":0, "encoding":"UTF-8", "pathExpression":"/usr/sumo/logs/collector/collector.gc.log*", "blacklist":[], "sourceType":"LocalFile", "alive":true } }
This example gets a ready-to-go JSON configuration of a Source with a specified ID, which can be used when managing a folder of multiple sources, or uploading a new source via the API.
Request:
curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/25/sources/101792472?download=true
Response:
{ "api.version": "v1", "source":{ "name":"collector_gc", "category":"collector_gc", "hostName":"nite-receiver-1", "automaticDateParsing":true, "multilineProcessingEnabled":true, "useAutolineMatching":true, "forceTimeZone":false, "filters":[], "cutoffTimestamp":0, "encoding":"UTF-8", "pathExpression":"/usr/sumo/logs/collector/collector.gc.log*", "blacklist":[], "sourceType":"LocalFile" } }
POST methods
Create Source
Creates a new Source for a Collector. See Use JSON to Configure Sources for required fields for the request JSON file.
Method: POST Path: /collectors/[collectorId]/sources
Parameter | Type | Required? | Default | Description |
collectorId | integer | Yes | NA | Unique Collector identifier. |
Example
This example creates a new Host Metrics Source on Collector with ID 10 using the parameters in the JSON file.
Request:
curl -u '<accessId>:<accessKey>' -X POST -H "Content-Type: application/json" -T host_metrics.json https://api.sumologic.com/api/v1/collectors/10/sources
Request JSON (host_metrics.json):
{ "source":{ "sourceType":"SystemStats", "name":"Host_Metrics", "interval":60000, "hostName":"my_host", "metrics":[ "CPU_User", "CPU_Sys" ] } }
Response:
{ "source": { "id": 101833059, "name": "Host_Metrics", "hostName": "my_host", "automaticDateParsing": true, "multilineProcessingEnabled": true, "useAutolineMatching": true, "contentType": "HostMetrics", "forceTimeZone": false, "filters": [ { "filterType": "Exclude", "name": "Filter keyword", "regexp": "(?s).*EventCode = (?:700|701).*Logfile = \"Directory Service\".*(?s)" } ], "cutoffTimestamp": 0, "encoding": "UTF-8", "interval": 60000, "metrics": [ "CPU_User", "CPU_Sys" ], "sourceType": "SystemStats", "alive": true } }
Note that the filter value shown above is an example for excluding a keyword. Filter values are specified to do batch edits to Processing Rules for Sources. For details on the different types of filters available, see Creating Processing Rules Using a JSON File.
PUT methods
Update Source
Updates an existing source. All modifiable fields must be provided, and all not modifiable fields must match those existing in the system.
Updating a Source 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/[collectorId]/sources/[sourceId]
Parameter | Type | Required? | Default | Description |
collectorId | integer | Yes | NA | Unique Collector identifier. |
sourceId | integer | Yes | NA | Unique Source identifier. |
Example
This example updates the Host Metrics Source created in the previous example with "interval" = 15000.
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/sources/101833059
Initial GET Response:
< HTTP/1.1 200 OK < ETag: "5f6bbe49f8b5a19dd43c806411225a5f" ... { "source":{ "id":101833059, "name":"Host_Metrics", "hostName":"my_host", ...
Next, modify the Source's JSON attributes as needed (in this example, setting "interval" to "15000"), 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: \"5f6bbe49f8b5a19dd43c806411225a5f\"" -T updated_host_metrics.json https://api.sumologic.com/api/v1/collectors/15/sources/101833059
Request JSON (updated_host_metrics.json)
{ "source": { "id": 101833059, "name": "Host_Metrics", "hostName": "my_host", "automaticDateParsing": true, "multilineProcessingEnabled": true, "useAutolineMatching": true, "contentType": "HostMetrics", "forceTimeZone": false, "filters": [ { "filterType": "Exclude", "name": "Filter keyword", "regexp": "(?s).*EventCode = (?:700|701).*Logfile = \"Directory Service\".*(?s)" } ], "cutoffTimestamp": 0, "encoding": "UTF-8", "interval": 15000, "metrics": [ "CPU_User", "CPU_Sys" ], "sourceType": "SystemStats", "alive": true } }
Note that the filter value shown above is an example for excluding a keyword. Filter values are specified to do batch edits to Processing Rules for Sources. For details on the different types of filters available, see Creating Processing Rules Using a JSON File.
Response:
{ "source": { "id": 101833059, "name": "Host_Metrics", "hostName": "my_host", "automaticDateParsing": true, "multilineProcessingEnabled": true, "useAutolineMatching": true, "contentType": "HostMetrics", "forceTimeZone": false, "filters": [ { "filterType": "Exclude", "name": "Filter keyword", "regexp": "(?s).*EventCode = (?:700|701).*Logfile = \"Directory Service\".*(?s)" } ], "cutoffTimestamp": 0, "encoding": "UTF-8", "interval": 15000, "metrics": [ "CPU_User", "CPU_Sys" ], "sourceType": "SystemStats", "alive": true } }
DELETE methods
Delete Source
Deletes the specified Source from the specified Collector.
Requests to delete Sources from the Cloud-to-Cloud Integration Framework are asynchronous. When you delete the Source it is placed in a Stopping state, when it has successfully stopped it is deleted from your Hosted Collector. Use a GET request to track the Source's state.
Method: DELETE Path: /collectors/[collectorId]/sources/[sourceId]
Parameter | Type | Required? | Default | Description |
collectorId | integer | Yes | NA | Unique Collector identifier. |
sourceId | integer | Yes | NA | Unique Source identifier. |
Example
This example deletes a Source.
curl -u '<accessId>:<accessKey>' -X DELETE https://api.sumologic.com/api/v1/collectors/15/sources/101833059
Response: There will be no response body, only a 200 OK response code.
Error Codes and Messages for Source API
Code | Message |
BadRequestBladeId | Request body contains an invalid Source ID. |
CannotModifySources | Collector is in JSON mode, user cannot create, delete, or update sources using the API. |
CollectorDescriptionTooLong | Maximum description length is 1024 characters. |
CollectorNameTooLong | Maximum name length is 128 characters. |
createValidationError | The specified ID is invalid. |
DuplicateResourceName | A resource with the same name already exists. |
EmptySourceType | Need to specify a source type. |
InvalidSourceType | Invalid Source type for the requested operation. |