SignalFx Developers Guide

Sending Data

Sending metrics

Use the operation POST https://ingest.{REALM}.signalfx.com/v2/datapoint to send metrics to SignalFx. You can send datapoints in either JSON or PROTOBUF formats.

To learn more about datapoints and the SignalFx data model, see The SignalFx Data Model.

Standards for metric and dimension names and values

The following standards apply to metrics and dimensions that you send with the POST https://ingest.{REALM}.signalfx.com/v2/datapoint operation.

Metric names and values

  • Metric name: Non-empty ASCII string, with a maximum length ⇐ 256 characters.

  • Metric value: Integer or float value ±1.79769313486231570E+308

Dimension names and values

  • Dimension name: Non-empty ASCII string, with a maximum length ⇐ 128 characters In addition:

    • Must start with an uppercase or lowercase letter The rest of the name can contain letters, numbers, underscores _ and hyphens.

    • Must not start with the underscore character "_"

    • Must not start with the prefix "sf_", except when the dimension is defined by SignalFx, such as "sf_hires"

  • Dimension value: One of the following:

    • Integer or float value ±1.79769313486231570E+308

    • Non-empty ASCII string, with a maximum length ⇐ 256 characters

SignalFx rejects datapoint requests that don’t meet these criteria.

Streaming in JSON format

To send a datapoint, use the operation POST https://ingest.{REALM}.signalfx.com/v2/datapoint. This operation sends individual datapoints for a metric time series (MTS).

The /datapoint API requires timestamps to increase monotonically in an MTS you send. The API silently rejects any datapoints it receives with a timestamp that’s earlier than previous datapoints for the same MTS.

If you don’t specify a timestamp, the API inserts the time value from the SignalFx server clock at the point that it receives the datapoint.

NOTE : If you want to send data that is earlier than data that has already been sent, use the operation POST https://backfill.<REALM>.signalfx.com/v1/backfill.

Streaming in PROTOBUF format

POST https://ingest.{REALM}.signalfx.com/v2/datapoint also supports ProtocolBuffer encoding, which is more bandwidth-efficient. The signalfx-protoc package contains the ProtocolBuffer definition of the message that the API expects.

To send data encoded as ProtocolBuffer messages, set the Content-Type header in your POST request to application/x-protobuf.

Datapoint timestamps

By default, SignalFx adds a timestamp to each datapoint you send, using the SignalFx server time at the time the datapoint arrives, using the UTC timezone. If you add your own timestamp to the datapoint, SignalFx uses it instead of the server time. Timestamps need to use the Unix time format (the time in milliseconds since the beginning of the Unix Epoch).

When you send timestamps, they need to increase monotonically. The API silently rejects datapoints it receives if they have a timestamp that’s earlier than previous datapoints for the same MTS.

To send data that is earlier than data that has already been sent, use the operation POST https://backfill.<REALM>.signalfx.com/v1/backfill.

Creating or updating metrics and dimensions

You don’t have to explicitly create metrics or dimensions. If they don’t already exist, SignalFx creates them when it receives them in a datapoint or dimension you send. The metrics and dimensions APIs have have "create or update" semantics; if SignalFx receives a PUT request for a metric or dimension that doesn’t exist, it creates the object; otherwise, it updates it.

To learn more about dimensions and other metrics metadata, see the topic Working with Metrics Metadata.

Limitation on dimensions

The datapoint and backfill APIs limit you to 36 dimensions per metric. If you try to send more than 36 dimensions, SignalFx discards the metric.

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
$ curl \
    --request PUT \
    --header "X-SF-TOKEN: <YOUR_ACCESS_TOKEN>" \
    --header "Content-Type: application/json" \
    --data \
        '{ \
            "key" : "<DIMENSION_KEY>", \
            "value": "<DIMENSION_VALUE>", \
            "tags": ["<YOUR_TAG>"], \
            "customProperties": { \
                "<PROPERTY_KEY>" : "<PROPERTY_VALUE>" \
            } \
        }' \
    https://api.<REALM>.signalfx.com/v2/dimension/<DIMENSION_KEY>/<DIMENSION_VALUE>

The response body for this request contains the following JSON:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "creator" : "<CREATOR_ID>",
    "lastUpdatedBy" : "<LAST_UPDATER_ID>",
    "created" : <CREATED_TIMESTAMP>,
    "lastUpdated" : <UPDATED_TIMESTAMP>,
    "customProperties" : \{
        "<PROPERTY_KEY>" : "<PROPERTY_VALUE>"
    \},
    "tags" : [ "YOUR_TAG" ],
    "key" : "<DIMENSION_KEY>",
    "value" : "<DIMENSION_VALUE>"
}

Metrics, dimensions, and metric time series

When you send a datapoint, you must specify its metric, and you can optionally specify dimensions. A metric and one or more dimensions define a metric time series (MTS).

Metric types

Metric types control the default rollup that SignalFx displays for the MTS in the web UI. For example, SignalFx summarizes gauges using averages. However, SignalFx stores the same set of rollups for all metrics, regardless of the declared metric type.

Because the metric type affects its appearance in the web UI, you should ensure that you choose the appropriate metric type for the MTS you send.

SignalFx has three types of metrics:

You can send data for different time series of different metric types in the same request.

If you send a datapoint for a non-existent metric, the API automatically creates the metric using the type you specify. You can change the metric type after the metric has been created, using an API call or web UI.

Sending events

The POST ingest.signalfx.com/v2/event API lets you post your own custom events to SignalFx. For example, you can send your own custom event when you deploy a new version of your software or update other parts of your infrastructure. You can then view these events in the web UI.

© Copyright 2019 SignalFx.

Third-party license information