Logstash Sumo Logic Output Plugin

This is an output plugin for Logstash. It is fully free and fully open source. The license is Apache 2.0, meaning you are pretty much free to use it however you want in whatever way.

TLS Deprecation Notice
In keeping with industry standard security best practices, as of May 31, 2018, the Sumo Logic service will only support TLS version 1.2 going forward. Verify that all connections to Sumo Logic endpoints are made from software that supports TLS 1.2.

Getting Started

This guide is for the users just want to download the binary and make the plugin work. For the developer, please refer to the Developer Guide

1. Create a Sumo Logic HTTP source

Create a Sumo Logic free account if you currently don't have one.

Create a HTTP source in your account and get the URL for this source. It should be something like:

https://events.sumologic.net/receiver/v1/http/XXXXXXXXXX

2. Install LogStash on your machine

Following this instruction to download and install LogStash. This plugin requires Logstash 2.3 or higher to work.

3. Install latest Logstash Sumo Logic Output plugin from RubyGems

bin/logstash-plugin install logstash-output-sumologic

4. Start Logstash and send log

In the Logstash home, running:

bin/logstash -e "input{stdin{}}output{sumologic{url=>'<URL from step 1>'}}"

This will send any input from console to Sumo Logic cloud service.

5. Try out samples

Open samples/sample-logs.conf, replace #URL# placeholder as real URL got from step 1

Launch sample with:

bin/logstash -f samples/log.conf

The input from console will be sent to Sumo Logic cloud service as log lines.

Open samples/sample-metrics.conf, replace #URL# placeholder as real URL got from step 1 (This sample may require installing the plugins-filters-metrics plugin first)

Launch sample with:

bin/logstash -f samples/metrics.conf

A mocked event will be sent to Sumo Logic cloud service as 1 minute and 15 minutes rate metrics.

6. Get result from Sumo Logic web app

Logon to Sumo Logic web app and run

• Log Search
• Live Tail
• Metrics Search

What's Next

• Try it with different input/filter/codec plugins
• Start LogStash as a service/daemon in your production environment
• Report any issue or idea through Git Hub

Parameters of Plugin

Parameter	Type	Required?	Default value	Decription
url	string	Yes		HTTP Source URL
source_category	string	No		Source category to appear when searching in Sumo Logic by _sourceCategory. If not specified, the source category of the HTTP source will be used. Can dynamically set this per event
source_name	string	No		Source name to appear when searching in Sumo Logic by _sourceName.
source_host	string	No		Source host to appear when searching in Sumo Logic by _sourceHost. If not specified, it will be the machine host name.
extra_headers	hash	No		Extra fields need to be send in HTTP header.
compress	boolean	No	false	Enable or disable compression.
compress_encoding	string	No	"deflate"	Encoding method of comressing, can only be "deflate" or "gzip".
interval	number	No	0	The maximum time for waiting before send in batch, in seconds.
batch_count	number	No	10000	The maximum number of events before send in batch.
format	string	No	"%{@timestamp} %{host} %{message}"	For log only, the formatter of log lines. Use %{@json} as the placeholder for whole event json.
json_mapping	hash	No		Override the structure of {@json} tag with the given key value pairs. For example: json_mapping => { "foo" => "%{@timestamp}" "bar" => "%{message}" } will create messages as: {"foo":"2016-07-27T18:37:59.460Z","bar":"hello world"} {"foo":"2016-07-27T18:38:01.222Z","bar":"bye!"}
metrics	hash	No		If defined, the event will be sent as metrics. Keys will be the metrics name and values will be the metrics value.
metrics_format	string	No	"cabon2"	Metrics format, can only be "graphite" or "carbon2".
metrics_name	string	No	"*"	Define the metric name looking, the placeholder "*" will be replaced with the actual metric name.
intrinsic_tags	hash	No		For carbon2 format only, send extra intrinsic key-value pairs other than metric (which is the metric name).
meta_tags	hash	No		For carbon2 format only, send metadata key-value pairs.
fields_as_metrics	boolean	No	false	If true, all fields in logstash event with number value will be sent as a metrics (with filtering by fields_include and fields_exclude ; the metics parameter is ignored.
fields_include	array	No	all fields	Working with fields_as_metrics parameter, only the fields which full name matching these RegEx pattern(s) will be included in metrics.
fields_exclude	array	No	none	Working with fields_as_metrics parameter, the fields which full name matching these RegEx pattern(s) will be ignored in metrics.

This plugin is based on logstash-mixin-http_client thus we also support all HTTP layer parameters like proxy, authentication, retry, etc.