SignalFx Developers Guide

Developer Home

Product Docs

SignalFx

Send Metrics and Events API

API for ingesting datapoints and event data.

Send Metrics

Sends metrics to SignalFx

post /datapoint

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://ingest.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://ingest.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://ingest.{realm}.signalfx.com/v2/datapoint

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 product documentation.
header Parameters
Content-Type
required
string

The media type ("MIME type") of the request body. Must be set to `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 properties for which the values are arrays of datapoints that you want to send to SignalFx. Each property specifies the datapoints for a specific metric type:

  • "gauge": Contains datapoints for gauge metrics.
  • "counter": Contains datapoints for counter metrics
  • "cumulative counter": Contains datapoints for cumulative counter metrics. When you send datapoints to SignalFx, the metric type array you use indicates to SignalFx how it should do rollups for the data. You can send datapoints for all three metric types in the same request.
    Each datapoint you send 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 any dimensions associated with it define a metric timeseries (MTS).
Any of
  • Gauge metrics
  • Counter metrics
  • Cumulative counter metrics
gauge
Array of objects (Individual datapoint)

Responses

200

Successful data ingest

400

Bad request. This can happen if:

  • The JSON was not well-formed. For example, a curly brace was missing.
  • The request was invalid. The JSON was well-formed, but you specified a datapoint outside of one of the metric type arrays or you forgot to specify a metric name for a datapoint.
401

Unauthorized. The org token specified in the X-SF-TOKEN header in the request doesn't have authorization to send datapoints to the organization.

Request samples

application/json
Copy
Expand all Collapse all
{
  • "gauge":
    [
    ]
}

Send Custom Events

Sends custom events to SignalFx

post /event

SignalFx API endpoint.
Replace {REALM} with the name of your realm. For example, if your realm is eu0, use https://ingest.eu0.signalfx.com/v2.
To find your realm, go to your profile page in the SignalFx web UI.
If you don't include a realm and use https://ingest.signalfx.com/v2, SignalFx interprets the endpoint as pointing to the us0 realm.

https://ingest.{realm}.signalfx.com/v2/event

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

The media type ("MIME type") of the request body. Must be set to `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>

The date and time of the event in Unix time UTC-relative

Responses

200

Successful custom event creation. The API doesn't return headers or a response body.

Request samples

application/json
Copy
Expand all Collapse all
[
  • {
    }
]

© Copyright 2019 SignalFx.

Third-party license information