SignalFx Developers Guide

Sending Metrics and Events

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 format.

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

Criteria for metric and dimension names and values

The following criteria apply to metrics and dimensions that you send with these operations:

  • POST https://ingest.{REALM}.signalfx.com/v2/datapoint

  • POST https://backfill.{REALM}.signalfx.com/v1/backfill

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

Metric names and values

  • Metric name: UTF-8 string, maximum length of 256 characters (1024 bytes)

  • Metric value: 64-bit signed integer or float

Dimension names and values

  • Dimension names:

    • UTF-8 string, maximum length 128 characters (512 bytes)

    • 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 for dimensions defined by SignalFx such as sf_hires

    • Must not start with any of these prefixes: aws_, gcp_, or azure_

Dimension values are always UTF-8 strings with a maximum length of 256 UTF-8 characters (1024 bytes). Numbers are represented as numeric strings.

Dimensions per MTS

You can have up to 36 dimensions per MTS.

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

The POST https://ingest.{REALM}.signalfx.com/v2/datapoint operation 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 Unix time.

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.

Considerations for metrics and metadata

The optional description property lets you provide a detailed description of a metric, dimension, or tag. You can use up to 1024 UTF-8 characters for description.

These considerations also apply:

Metrics

You can have up to 36 dimensions per metric

Dimensions

You can have up to 50 tags per dimension

Custom properties

You can have up to 50 tags per custom property

Tags

You can assign tags to charts, and you can have up to 50 tags per chart.

Example

The following example demonstrates how to update the tags and custom properties for a dimension.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
$ curl \
    --request PUT \
    --header "X-SF-TOKEN: <YOUR_ORG_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 is similar to the following JSON:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "creator" : "<CREATOR_ID>",
    "lastUpdatedBy" : "<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.

Sending events

The POST ingest.signalfx.com/v2/event operation 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