Skip to main content
Sumo Logic

Upload Data to an HTTP Source

After you have added an HTTP Logs and Metrics Source to a Hosted Collector you can begin uploading data. You can upload both logs and metrics to the same HTTP source, however not in the same HTTP request.

  • TLS 1.2 Requirement for CollectorsWe will be removing support for TLS 1.0 and TLS 1.1 from all public endpoints on Jun 20. All Sumo Logic collector agents will need to be upgraded to version 19.155 or above while running JRE 7+. All clients of Sumo Logic's public REST APIs, or clients that upload data to a Sumo Logic HTTP Source should be checked for TLS 1.2 support.

Differences between uploading logs and metrics

You can upload both logs and supported metric types to an HTTP source. There are different requirements depending on whether you are uploading logs or metrics to the source.

If you are going to upload logs to an HTTP source, when you configure the source, be sure to supply the Advanced options, as described on HTTP Logs and Metrics Source.

When you upload metrics to an HTTP source, you must specify a Content-Type header, as described below in Upload Metric Data; otherwise the HTTP payload will be ingested as log data.

Metrics units requirements

Metrics you upload to an HTTP source must be in seconds or milliseconds. Metrics in microseconds are not supported.

Upload log data

Upload log data with a GET Request

To upload log data with a GET request, append the data payload as a single query parameter to the Source's upload URL. All content after the ? will be considered part of the payload.

Data payload Sumo is #1!
Method GET
URL https://[SumoEndpoint]/receiver/v1/http/[UniqueHTTPCollectorCode]?Sumo+is+%231%21

where:

[SumoEndpoint] is your Sumo collection endpoint, and 

[UniqueHTTPCollectorCode] is the string that follows the last forward slash (/) in the upload URL for the HTTP source.  
Body  

Upload log data with a POST Request

To upload log data with a POST request, include the complete data payload as the request body. Any query parameters will be ignored.

Data payload Data line 1
Data line 2
Data line 3
Method POST
URL https://[SumoEndpoint]/receiver/v1/http/[UniqueHTTPCollectorCode]

where:

[SumoEndpoint] is your Sumo collection endpoint, and 

[UniqueHTTPCollectorCode] is the string that follows the last forward slash (/) in the upload URL for the HTTP source.  
Body Data line 1
Data line 2
Data line 3

Upload Metric Data

Sumo supports the following metric formats. To send metrics to an HTTP Source, you must specify a Content-Type header indicating the metric format of the request. If you omit the Content-Type header, or set a value not listed below, the HTTP payload will be ingested as log data. 

Depending on the Content-Type header specified, Sumo parses and interprets each line in the HTTP payload in the desired metric format.

Format Content-Type Header Format Description Example Datapoints
Graphite application/vnd.sumologic.graphite metric.name value timestamp prod.lb-1.cpu 87.2 1501753030
Carbon 2.0 application/vnd.sumologic.carbon2 intrinsic_tags meta_tags value timestamp

Note that there are two spaces between intrinsic_tags and meta_tags, and that meta_tags are optional. If no meta_tags are provided, there must be two spaces between intrinsic_tags and value.

cluster=prod node=lb-1 metric=cpu  ip=2.2.3.4 team=infra 87.2 1501753030

cluster=staging node=16 metric=memory  8589934592 1501753030

For more information about these example datapoints, see About the Carbon 2.0 example data points below.

About the Carbon 2.0 example data points

Two example Carbon 2.0 data points are shown in the table above.  

In the first data point, cluster=prod node=lb-1 metric=cpu  ip=2.2.3.4 team=infra 87.2 1501753030:

  • The  intrinsic_tags are: cluster=prod, node=lb-1, and metric=cpu.

  • The meta_tags are ip=2.2.3.4 and team=infra

  • The value is 87.2

  • The timestamp is 1501753030.

In the second data point, cluster=staging node=16 metric=memory  8589934592 1501753030:

  • The  intrinsic_tags are: cluster=staging, node=16, and metric=memory.

  • There are no meta_tags.

  • The value is 8589934592.

  • The timestamp is 1501753030.
     

Sending multiple metrics in a single payload

To minimize HTTP overhead, Sumo supports sending multiple metrics in a single HTTP payload. To send multiple metrics in a single HTTP payload, specify each metric in the same format, separated by newlines:

Content-Type: application/vnd.sumologic.graphite

prod.lb-1.cpu 87.2 1501753030
prod.lb-1.memory 32390 1501753030
prod.lb-1.disk 2.2 1501753030
prod.lb-1.cpu 84.6 1501753040
prod.lb-1.memory 32250 1501753040
...

Content-Type: application/vnd.sumologic.carbon2

cluster=prod node=lb-1 metric=cpu  ip=2.2.3.4 team=infra 87.2 1501753030
cluster=prod node=lb-1 metric=memory  ip=2.2.3.4 team=infra 32390 1501753030
cluster=prod node=lb-1 metric=disk  ip=2.2.3.4 team=infra 2.2 1501753030
cluster=prod node=lb-1 metric=cpu  ip=2.2.3.4 team=infra 84.6 1501753040
cluster=prod node=lb-1 metric=memory  ip=2.2.3.4 team=infra 32250 1501753040
...

Compressed Data

You can send Sumo plain, uncompressed data (such as plain text) or you can send data that has been compressed by either the "deflate" or the "gzip" method. Compressed data can only be sent with the POST method, not GET. You can compress log data or metric data prior to upload.

To send a compressed payload, specify a value of gzip (for gzip-compressed) or deflate (for zlib-compressed) in the Content-Encoding header of your request, and include the compressed data as the request body.

HTTP Access Control (CORS)

Sumo Logic HTTP sources support clients bound by the CORS mechanism.

To ensure the appropriate Access-Control-* response headers are set, make sure the Origin header is populated in the initial OPTIONS probe and all subsequent requests.

Supported HTTP Headers

The following parameters can be specified via headers when sending data to an HTTP Source. The settings will apply to all messages in the request. For Source Name, Host, and Category, the header value will override any default value already specified for the source and/or collector.

Setting Header Name Header Value
Compressed data Content-Encoding gzip or deflate

Required if you are uploading compressed data.
Content Type (for Metrics) Content-Type application/vnd.sumologic.graphite
or
application/vnd.sumologic.carbon2

Required if you are uploading metrics.
Custom Source Name X-Sumo-Name Desired source name.

Useful if you want to override the source name configured for the source.
Custom Source Host X-Sumo-Host Desired host name.

Useful if you want to override the source host configured for the source.
Custom Source Category X-Sumo-Category Desired source category.

Useful if you want to override the source category configured for the source.
Custom Metric Dimensions X-Sumo-Dimensions Comma-separated key=value list of dimensions to apply to every metric.

For metrics only. Custom dimensions will allow you to query your metrics at a more granular level.
 
Custom Metric Metadata X-Sumo-Metadata Comma-separated, key=value list of metadata to apply to every metric.

For metrics only. Custom metadata  will allow you to query your metrics at a more granular level

Command Line Examples

cURL

POST upload

curl -v -X POST -T [local_file_name] https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]

When using cURL to POST data from a file, make sure to use the -T parameter to specify the file path, not -d.
The -d parameter causes new lines to be removed from the content, which will interfere with message boundary detection.

POST upload (Graphite-formatted metrics)

curl -v -X POST -H 'Content-Type:application/vnd.sumologic.graphite' -T [local_file_name] https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]

When using cURL to POST metrics data from a file, make sure that each line in the file follows the format specified by the Content-Type header for the HTTP request.

POST upload (Carbon 2.0-formatted metrics)

curl -v -X POST -H 'Content-Type:application/vnd.sumologic.carbon2' -T [local_file_name] https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]

When using cURL to POST metrics data from a file, make sure that each line in the file follows the format specified by the Content-Type header for the HTTP request.

POST upload (gzip compressed data) 

curl -v -X POST -H 'Content-Encoding:gzip' -T [local_file_name.gz] https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]

POST upload (gzip compressed metrics) 

curl -v -X POST -H 'Content-Encoding:gzip' -H 'Content-Type:application/vnd.sumologic.graphite' -T [local_file_name.gz] https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]

POST upload (custom Source Category)

curl -v -X POST -H 'X-Sumo-Category:myNewCategory' -T [local_file_name] https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]

GET upload

curl -v https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]?[message_data]

GET upload (metrics)

curl -v -H 'Content-Type:application/vnd.sumologic.graphite' https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]?my.graphite.metric%2087.2%201501759793
PowerShell

POST upload

Invoke-WebRequest -Method POST -InFile [local_file_name] 'https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]'

POST upload (gzip compressed data) 

Invoke-WebRequest -Method POST -Headers @{'Content-Encoding' = 'gzip'} -InFile [local_file_name.gz] 'https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]'

POST upload (custom Source Category)

Invoke-WebRequest -Method POST -Headers @{'X-Sumo-Category' = 'myCustomCategory'} -InFile [local_file_name] 'https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]'

GET upload

Invoke-WebRequest 'https://collectors.sumologic.com/receiver/v1/http/[UniqueHTTPCollectorCode]?[message_data]'