NOTE: This page is Work In Progress. Custom Metrics functionality is not enabled in SPM yet.
Terminology
- A "metric" is a distinct triple of (metric name, filter1 name, filter2 name). Some examples:
- ("cpuIdle", server="server1", null) vs. ("cpuIdle", null, server="server1") – these are 2 distinct metrics
- ("cpuSteal", server="server1", null) vs. ("cpuIdle", server="server1", null) – these are 2 distinct metrics
- ("diskRead", server="server1", device="/dev/xxx") vs. ("diskRead", server="server1", device="/dev/yyy") – this is the same 1 metric with two different values for filter2 named "device"
- ("diskWrite", server="server1", device="/dev/xxx") vs. ("diskWrite", server="server1", device="/dev/yyy") – this is the same 1 metric with two different values for filter2 named "device"
- ("diskRead", server="server1", device="/dev/xxx") vs. ("diskWrite", server="server1", device="/dev/xxx") – these are 2 distinct metrics
- A "data point" is the value associated with some (metric, filter1, filter2) combination. Some examples:
- ("cpuIdle", server="server1", null) = 90
- ("cpuIdle", server="server1", null) = 90 – this is a distinct data point for the same metric as in the previous line
Pushing Metrics
Request format
Custom metrics can be sent to receiver via HTTP as POST request.
Request parameters:
Name | Description |
---|---|
host | host name |
token | application token |
Request body format:
[timestamp]\tcustom\t[metric_name]\t[filter1_value]\t[filter2_value]\t[metric_value]\t[aggregation_type] ....
Placeholder | Description | Limitations |
---|---|---|
timestamp | Number of milliseconds passed since Epoch (1 Jan 1970) | |
metric_name | Name of metric | Length > 0 and <= 255 |
filter1_value | Value of first filter | Length > 0 and <= 255 |
filter2_value | Value of second filter | Length > 0 and <= 255 |
metric_value | Value of metric (Double) | |
aggregation_type | Type of aggregation | avg,min,max,sum |
Curl example
TIMESTAMP=$(($(date +%s)*1000)) METRIC=`echo -n "$TIMESTAMP\tcustom\tconsumed_coffee\toffice-1\tkitchen-2\t100.0\tsum"` TOKEN=xxxxxxxx-759b-46bf-a9d3-xxxxxxxxxxxx curl -H "Content-Type: text/plain" -X POST -d "$METRIC" "http://apps.sematext.com/spm-receiver/receive?host=`hostname`&token=$TOKEN"
Ruby example
Example using gem "httparty"
require 'httparty' class MetricSerializer def serialize(options) "#{options[:timestamp]}\tcustom\t#{options[:name]}\t#{options[:filter1]}\t#{options[:filter2]}\t#{options[:value]}\t#{options[:agg]}" end end class MetricSender include HTTParty def initialize(options) raise "receiver_url is required" unless options[:receiver_url] raise "host is required" unless options[:host] raise "token is required" unless options[:token] self.class.default_options[:base_uri] = options[:receiver_url] @serializer = MetricSerializer.new @host = options[:host] @token = options[:token] @version = "1.9.0" end def send(options) current_time = (Time.now.to_f * 1000).to_i merged_options = { :timestamp => current_time, :agg => 'avg' }.merge(options) s = @serializer.serialize(merged_options) puts s post_metric(s) end private def post_metric(body) post_options = { :query => {:host => @host, :token => @token, :v => @version}, :headers => {'Content-Type' => 'text/plain; charset=utf-8'}, :body => body } self.class.post('receive', post_options) end end RECEIVER_OPTIONS = { :receiver_url => "http://appssematext.com/spm-receiver/", :host => "katrin", :token => "xxxxxxxx-759b-46bf-a9d3-xxxxxxxxxxxx" } sender = MetricSender.new(RECEIVER_OPTIONS) sender.send :name => "coffee_consumed", :filter1 => "office-1", :filter2 => "kitchen-2", :value => 100.0, :agg => "sum"
Comments
Any frequency limitations depend on AF implementation.
TODO (refer to AF frequency limits)
TODO (add Java example)