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.

You cannot use the Source API to create Microsoft Office 365 sources, Google Audit sources, or any other sources that require OAuth-based authentication with another vendor.

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.

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

See Use JSON to Configure Sources for a description of Source parameters.

GET methods

List Sources

GET/collectors/{collectorId}/sources

Gets information about all Sources for a specified Collector.

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*",
    "denylist":[],
    "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*",
    "denylist":[],
    "sourceType":"LocalFile"
  },
  ...
  ]
}

Get Source by ID

GET/collectors/[collectorId]/sources/{sourceId}

Gets information about a specified Collector and Source.

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*",
    "denylist":[],
    "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*",
    "denylist":[],
    "sourceType":"LocalFile"
  }
}

POST methods

Create a Source

POST/collectors/{collectorId}/sources

Creates a new Source for a Collector. See Use JSON to Configure Sources for required fields for the request JSON file.

Parameter	Type	Required?	Default	Description
`collectorId`	integer	Yes	NA	Unique Collector identifier.

POST creates a single Source per request.

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 a Source

PUT/collectors/{collectorId}/sources/{sourceId}

Updates an existing source. All modifiable fields must be provided, and all not modifiable fields must match those existing in the system.

You need to include the id parameter in your JSON file.

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

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
   }
}

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 a Source

DELETE/collectors/{collectorId}/sources/{sourceId}

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.

Example

This example deletes a Source.

Request
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

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.

Rate limiting​

Response fields​

GET methods​

List Sources​

Examples​

Get Source by ID​

Examples​

POST methods​

Create a Source​

Example​

PUT methods​

Update a Source​

Example​

DELETE methods​

Delete a Source​

Example​

Error Codes and Messages​

Rate limiting

Response fields

GET methods

List Sources

Examples

Get Source by ID

Examples

POST methods

Create a Source

Example

PUT methods

Update a Source

Example

DELETE methods

Delete a Source

Example

Error Codes and Messages