SPM lets users extend standard reports using custom metrics.
A data point has the following attributes:
Custom metrics reports display values aggregated using 'aggregation type'. For example, values 1.0, 2.0, and 3.0 sent during one minute with average ('avg') aggregation type will be represented by a single point on a graph, with value 2.0 for that minute.
Filter1 and filter2 values can be used to organize complex metrics. For example, one can use them to track registered users count by gender and account type. In registered users example data points can be specified as:
{ "name" : "registered-users-count", "value" : 42, "aggregation" : "sum", "filter1" : "user.gender=male", "filter2" : "account.type=free" } { "name" : "registered-users-count", "value" : 24, "aggregation" : "sum", "filter1" : "user.gender=female", "filter2" : "account.type=free" } { "name" : "registered-users-count", "value" : 10, "aggregation" : "sum", "filter1" : "user.gender=female", "filter2" : "account.type=paid" } |
In reports, the selected values in one filter are combined with an 'OR', while selected values in different values are 'ANDed'. For example, to display the number of female users, in filter1 the value 'female' should be selected, to display female paid users in filter1 should be selected 'female' and in filter2 'paid'.
We recomend to use 'parameter.name=value' format to define filter values.
SPM provides REST API for sending data points for custom metrics:
http://spm-receiver.sematext.com/receiver/custom/receive.[format]?token=[spm app token]
The format can be either 'json' or 'raw'.
Applications' tokens are listed at https://apps.sematext.com/users-web/home.do?homeTab=spm
URL: http://spm-receiver.sematext.com/receiver/custom/receive.json?token=[spm app token]
Content-type: application/json
Method: POST
JSON body:
Field name | Field type | Constraints |
---|---|---|
datapoints | array of 'data point' | elements count <= 100 |
Data point:
Field name | Description | Field type | Constraints | Required |
---|---|---|---|---|
timestamp | Time in milliseconds since "Epoch" | Long | No | |
name | Metric name | String | length > 0 and <= 255 | Yes |
value | Data point value | Double | Yes | |
aggregation | Aggregation type | String | "min", "max", "avg", "sum" | Yes |
filter1 | Value for filter1 | String | length > 0 and <= 255 | No |
filter2 | Value for filter2 | String | length > 0 and <= 255 | No |
Example:
{ "datapoints" : [ { "timestamp" : 1369669889927, "name" : "registered-users-count", "value" : 1, "aggregation" : "sum", "filter1" : "user.gender=male", "filter2" : "account.type=free" }, { "name" : "registered-users-count", "value" : 1, "aggregation" : "sum", "filter1" : "user.gender=female", "filter2" : "account.type=paid" } ] } |
To send metrics using curl, save example above to a file named "datapoints.json" and submit it with the following call, using your own token:
curl -v -H 'Content-type: application/json' -d @datapoints.json http://spm-receiver.sematext.com/receiver/custom/receive.json?token=[spm app token] |
URL: http://spm-receiver.sematext.com/receiver/custom/receive.raw?token=[spm app token]
Content-type: text/plain
Method: POST
Each line is tab delimited sequence of fields:
(timestamp)\t(name)\t(value)\t(aggregation type)\t(filter1)\t(filter2)
Lines are separated by new line character ('\n'). Limit is 100 lines per request.
Field name | Description | Field type | Constraints | Required |
---|---|---|---|---|
timestamp | Time in milliseconds since "Epoch" | Long | No | |
name | Metric name | String | length > 0 and <= 255 | Yes |
value | Data point value | Double | Yes | |
aggregation | Aggregation type | String | "min", "max", "avg", "sum" | Yes |
filter1 | Value for filter1 | String | length > 0 and <= 255 | No |
filter2 | Value for filter2 | String | length > 0 and <= 255 | No |
Example:
1369671381221 registered-users-count 1 sum user.gender=male account.type=free 1369671381221 registered-users-count 1 sum user.gender=female account.type=paid |
To post these data using curl, save the example above (ensure tabs are preserved) to a file named datapoints.raw and use the following with your own token:
curl -v -H 'Content-type: text/plain' -d @datapoints.raw http://spm-receiver.sematext.com/receiver/custom/receive.raw?token=[spm app token] |
Sematext-metrics is open source library for sending custom metrics from java application. Please refer to README for quick start.
Each SPM plan allows for a different number of metrics and a different number of datapoints per calendar month. Please see SPM Plans page.