Display data using charts

Charts display the metrics you’re sending to Splunk Observability Cloud. They can contain a single plot of metrics over time, or multiple related plots. The different chart types that Splunk Observability Cloud provides help you get the best visualization for different types of data and different scenarios.

When you send an API request, you need to use the endpoint specific to your organization's realm. To learn more, see Realms in endpoints.

To learn more about chart features, see the Charts in Splunk Observability Cloud topic in the Splunk Observability Cloud user documentation.

 Chart-dashboard relationships in the API

In the user interface, you create charts within an existing dashboard. In the API, you have to create the chart first and then assign it to a dashboard. If you don’t, the chart won’t appear in the UI; instead, it becomes an "orphan".

To navigate to any chart, enter the URL pattern as follows:

https://app.<REALM>.signalfx.com/#/chart/v2/<CHART_ID>

The API returns <CHART_ID> in the response body when you create a chart. You can also use the Chart API to search for a chart using the name you assigned it when you created it or tags you assigned it. To do this, use the REST operation Retrieve charts using query.

You can also view orphan charts in the user interface catalog.

 Charts and SignalFlow

A chart’s SignalFlow program controls its metrics and time frame. When you create a chart using the API, you specify the SignalFlow program in the programText property of the Create Chart request object. To learn more about SignalFlow, see the topic Analyze data using SignalFlow.

The SignalFlow program for a chart can also link the chart to a detector. To learn more, see the section Link charts and detectors.

 SignalFlow calendar window transformations for charts

SignalFlow programs for charts let you use calendar window transformations, which perform a computation over calendar intervals or windows, such as days, weeks, and months.

SignalFlow provides calendar window transformations for the following methods:

• max()
• mean()
• min()
• sum()

To learn more about SignalFlow calendar window transformations, see Calendar window transformations.

 Timezones and SignalFlow calendar window transformations

By default, SignalFlow interprets calendar window transformations relative to the Coordinated Universal Time (UTC) time zone. To change this, use the options.programOptions.timezone property when you create or update a chart. The property value is a string that denotes the geographic region associated with the time zone. For example, the following JSON is part of a chart request body:

{
  "options": {
    
    "programOptions": {
      
      "timezone": "Europe/London"
    }
  }
}

The section Supported SignalFlow time zones lists the supported time zones.

 Chart types in detail

To learn about different chart types and how to select the type that best matches your needs, see the Chart types topic in the Splunk Observability Cloud user documentation.

 Display units and other labels in graph charts

A graph chart is any chart that displays data points over a period of time. To learn more about graph charts, see the Graph charts section in the Splunk Observability Cloud user documentation.

You can specify units for each plot in a graph chart, so that values are scaled up or down in order to improve readability. Units fall into three groups:

 Bits

 Bytes

Table 3. Byte scale factors

 Time

In addition, you can add prefix and suffix values to help describe the values on the chart if no units are specified.

 Chart color palettes

In the API, you specify chart colors using a palette index value. In most cases, the API accepts one of 22 values in the range 0-21. The following table shows the values and their corresponding colors expressed as hexadecimal values:

Table 5. Color palette

Users with color vision deficiencies can change the standard palette to one of the alternate palettes shown in the following table, using the Color accessibility option in Settings > My Profile in the user interface. You can’t control this setting using the API.

Table 6. Color vision deficiency alternatives

 Considerations for chart properties

Tags: You can have no more than 50 tags per chart.

 Link charts and detectors

To link a chart and a detector using the API, add an alerts() block to the chart’s SignalFlow program specified in the programText property.

To learn more about linking charts and detectors, see the Link detectors to charts topic in the Splunk Observability Cloud user documentation.

Use the Charts API to link charts and detectors. The Detectors API doesn’t provide a way to create these links.

 Considerations for linking charts and detectors

• The alerts() block isn’t general-purpose SignalFlow. You can only use it in the SignalFlow program that links a chart to a detector.
• To link a chart and a detector, the detector must exist, but the chart can be new or existing.
• To learn how to create a detector using the API, see the section Create a detector.

 Link an existing chart to a detector

For example, suppose you have a chart object with the SignalFlow program:

"blkioRead = data("blkio.io_service_bytes_recursive.read", filter=filter("plugin", "docker")).sum().publish("blkioRead");"

To link the chart to an existing detector object with the ID <DETECTOR_ID>, add the following line to the end of the program:

"alertSignal = alerts(detector_id="<DETECTOR_ID>").publish("alertSignal")"

The resulting SignalFlow program is this:

"blkioRead = data("blkio.io_service_bytes_recursive.read", filter=filter("plugin", "docker")).sum().publish("blkioRead");
alertSignal = alerts(detector_id="<DETECTOR_ID>").publish("alertSignal")"

After you have modified the SignalFlow program, update the programText property for the chart using the following operation:

PUT https://api.<REALM>.signalfx.com/v2/chart/<id>

For an example of updating a chart, see the section Update a chart.

 Link a new chart to a detector

To link a new chart to a detector, follow the instructions in the previous section Linking an existing chart to a detector, with these exceptions:

• Write a SignalFlow program for the chart itself.
• Use POST https://api.<REALM>.signalfx.com/v2/chart to create the chart.

 Examples

 Create a chart

The following curl command creates a simple chart.

$ curl \
    --request POST \
    --header "X-SF-TOKEN: <SESSION_TOKEN>" \
    --header "Content-Type: application/json" \
    --data \
    '{
        "name": "CPU load",
        "programText": "data(cpu.utilization).publish()"
     }' \
    https://api.<REALM>.signalfx.com/v2/chart

The response body contains the chart ID that Splunk Observability Cloud assigns to the new chart, along with default and auto-generated values. For example:

{
    "created": <CREATED_TIMESTAMP>,
    "creator": "<CREATOR_ID>",
    "customProperties": {},
    "description": "",
    "id": "<CHART_ID>",
    "lastUpdated": <UPDATED_TIMESTAMP>,
    "lastUpdatedBy": "<UPDATER_ID>",
...
Show More

You can view a chart in the user interface using the following URL:

https://app.<REALM>.signalfx.com/#/chart/<CHART_ID>

By default, Splunk Observability Cloud creates a line chart from the specified SignalFlow program. The API provides all the request properties you need to fully customize charts when you create or update them. To see all the properties, read the Charts API reference.

 Update a chart

This example updates a chart to link it with a detector.

 Considerations for updating charts

• The API uses overwrite semantics for updates.

• When you do an update using a PUT operation, the API deletes or sets to null the writable properties you don’t specify in the request body. This happens even if the properties had existing values.

• Read-only properties aren’t affected. If you want, you can delete them from a PUT request. If you leave them in, the API ignores them.

• To avoid wiping out the properties you want to keep, follow these steps to update a chart:

  1. Find the ID for the chart:
     1. Using the user interface, open the chart. The browser address bar displays a URL similar to the following: https://app.signalfx.com/#/chart/v2/<CHART_ID>?groupId=<DASHBOARD_GROUP_ID>&configId=<CONFIG_ID>
     2. Using the API, use the operation GET https://api.<REALM>.signalfx.com/v2/chart to search for charts, then get the chart ID from the appropriate chart.
  2. Use the operation GET https://api.<REALM>.signalfx.com/v2/chart/<CHART_ID>} to get the properties for the chart. The response body is a JSON object.
  3. Modify the properties you want to update.
  4. Use the operation PUT https://api.<REALM>.signalfx.com/v2/chart/<CHART_ID> to update the chart, using the response body from the previous GET as the request body for the PUT. This ensures that the update doesn’t delete or null out existing properties.

 Example of updating a chart

The following curl command updates an existing chart:

$ curl \
--request PUT \
--header "X-SF-TOKEN: <SESSION_TOKEN>" \
--header "Content-Type: application/json" \
--data \
'{
  "customProperties": {},
  "description": "Chart linked to detector",
...
Show More

 Create a dashboard

The following example creates a new dashboard for the newly-created chart, and adds the dashboard to an existing dashboard group.

$ curl \
    --request POST \
    --header "X-SF-TOKEN: <SESSION_TOKEN>" \
    --header "Content-Type: application/json" \
    --data \
    '{
        "name": "My new dashboard",
        "groupId": "<DASHBOARD_GROUP_ID>"
...
Show More

The API responds with the properties of the new dashboard object:

{
    "charts": [
        {
            "chartId": "<CHART_ID>",
            "column": 0,
            "height": 1,
            "row": 0,
            "width": 6
...
Show More

Since you didn’t provide the ID of an existing dashboard group, Splunk Observability Cloud created a new one.

 Sort a list chart

The API lets you sort values in a list chart by specifying the options.sortBy property in the request to create or update a chart. You can sort on one of the MTS dimensions, a data point, the metric name, or the publish() method label argument of the SignalFlow statement that generates the data. To choose one of these options, specify one of the keyword values shown in the following table:

In addition, you can sort by any dimension of an MTS displayed in the chart.

To see a list of entities on which you can sort:

1. In the user interface, open the list chart you want to sort.
2. Select the Chart options tab.
3. Open the Sort list. In the list, Value is the alias for value, Plot name is the alias for sf_metric, and Metric is the alias for sf_originatingMetric. All other list items are dimension names.

To sort a list chart by value, specify the following in the request body:

{
    options: {
        "sortBy": "value",
    ...
    }
}

To sort by plot name, specify the following:

{
    options: {
        "sortBy": "sf_metric",
        ...
    }
}

To sort by the dimension demo_datacenter, specify the following:

{
    options: {
        "sortBy": "demo_datacenter",
        ...
    }
}

Splunk Observability Cloud doesn't guarantee the sort order of identical values in the input stream.

 See also

Dashboards in Splunk Observability Cloud in the Splunk Observability Cloud user documentation.