SignalFx Developers Guide

Developer Home

Product Docs

SignalFx
Documentation Powered by ReDoc

Send Metrics and Events API

API for ingesting datapoints and event data.

Send Metrics

Sends metrics to SignalFx

Send datapoints to SignalFx. Be aware of the following when you use /datapoint:

  • Send datapoints in a stream, so that each call to /datapoint contains the data that's immediately available. This also means that you should send datapoints as quickly as possible. You can always update an MTS later with additional dimensions and custom properties.
  • If you use the timestamp property in your data, note that its values must monotonically increase with each call.

NOTE: You can use /datapoint to send high-resolution metrics to SignalFx. To do this, you need to add "sf_hires": "1" as a dimension for the datapoint.

To learn more about high-resolution datapoints, see the topic Resolution and Data Retention in the SignalFx user documentation.

header Parameters
Content-Type
required
string

Format of the request body. Always application/json.

X-SF-Token
required
string

Authentication token. Must be an org token (referred to as an access token in the web UI)

Request Body schema: application/json

Contains up to 3 arrays of datapoints. An array's property key sets the metric type for the array's datapoints. SignalFx also sets the default rollup based on the property key:

  • "gauge": Gauge datapoints. The default rollup averages datapoints.
  • "counter": Counter datapoints. The default rollup sums datapoints.
  • "cumulative counter": Cumulative counter datapoints. The default rollup calculates the "delta" (change in value).

You can send all three metric types in the same request.

Each datapoint must have a metric name and a metric value. You can also specify one or more dimensions and a timestamp for the datapoint.

A metric name and the dimensions associated with it define a metric timeseries (MTS).

Any of
Array of objects (Individual datapoint)

Responses

Request samples

Content type
application/json
Example
Gauge metrics
Gauge metrics
Counter metrics
Cumulative counter metrics
{
  • "gauge":
    [
    ]
}

Send Custom Events

Sends custom events to SignalFx

Sends custom events to SignalFx. Use this API to send events that SignalFx itself doesn't detect, such as software deployments or hardware changes. You can then correlate these events with changes detected in your metrics.

header Parameters
Content-Type
required
string

Format of the request body. Always application/json.

X-SF-Token
required
string

Authentication token. Must be an org token (referred to as an access token in the web UI)

Request Body schema: application/json

An array of event specifications. Note the following naming criteria:

  • eventType must be a non-empty ASCII string with a length less than or equal to 256 characters.
  • dimensions and properties names must be non-empty ASCII strings with a length less than or equal to 128 characters.
  • dimensions and properties names can't start with the characters _ (underscore) or sf_. These are reserved for SignalFx internal use.
  • properties names can't start with the characters aws_, which are also reserved for SignalFx internal use.
  • dimensions and properties names must start with an alphabetic character. The rest of the name can be alphanumeric characters, _ (underscore), and - (hyphen).
  • Dimension and property values must be non-empty ASCII strings with a length less than or equal to 256 characters.
Array ()
category
string
Enum: "USER_DEFINED" "ALERT" "AUDIT" "JOB" "COLLECTED" "SERVICE_DISCOVERY" "EXCEPTION"

A category that describes the custom event, in the form of one of the allowed enumerated types:

  • USER_DEFINED: The default for custom events
  • ALERT: Used by SignalFx to mark an event generated by a detector.
  • AUDIT: Used by third-party integrations
  • JOB: Event generated by a SignalFx or third-party background job
  • COLLECTD: Generated by the SignalFx CollectD integration
  • SERVICE_DISCOVERY: Generated by third-party integrations
  • EXCEPTION: A software exception occurred
dimensions
object

A list of key-value pairs that specify dimension names and values to associate with the event. SignalFx assumes that each value of eventType you send is associated with a specific set of dimension names and values.

eventType
required
string

A name for the custom event. Use this name to find the event in other API calls or in the web UI.

properties
object

A list of key-value pairs that specify properties of the specified event.

timestamp
integer <int64> >= 0

The date and time of the event in Unix time

Responses

Request samples

Content type
application/json
[
  • {
    }
]

© Copyright 2020 Splunk, Inc.

Third-party license information