Splunk® Enterprise

REST API Reference Manual

Splunk Enterprise version 9.0 will no longer be supported as of June 14, 2024. See the Splunk Software Support Policy for details. For information about upgrading to a supported version, see How to upgrade Splunk Enterprise.

Metrics Catalog endpoint descriptions

Use the Metrics Catalog REST API to enumerate metrics and the dimensions and dimension values associated with metrics.

Usage details

Review ACL information for an endpoint

To check Access Control List (ACL) properties for an endpoint, append /acl to the path. For more information see Access Control List in the REST API User Manual.

Authentication and Authorization

Username and password authentication are required for access to endpoints and REST operations.

Splunk users must have role and/or capability-based authorization to use REST endpoints, and must have the list_metrics_catalog capability to use the Metrics Catalog endpoint. Users with an administrative role, such as admin, can access authorization information in Splunk Web. To view the roles assigned to a user, select Settings > Access controls > Users. To determine the capabilities assigned to a role, select Settings > Access controls > Roles.

App and user context

Typically, knowledge objects, such as saved searches or event types, have an app/user context that is the namespace. For more information about specifying a namespace, see Namespace in the REST API User Manual.

Default indexes for Metrics Catalog endpoints

If no metric indexes are defined with the filter parameter, Metrics Catalog endpoints use the default indexes specified for the role of the user. To review or update the default indexes for specific roles, select Settings > Access controls > Roles, select a role, and review or update the Indexes searched by default field.

If the set of default indexes for a role includes a mix of metrics indexes and event indexes, the Metrics Catalog endpoints only use the metrics indexes.

If there are no metrics indexes, the Metrics Catalog endpoints display an empty list.

Splunk Cloud Platform URL for REST API access

Splunk Cloud Platform has a different host and management port syntax than Splunk Enterprise. Use the following URL for Splunk Cloud Platform deployments. If necessary, submit a support case using the Splunk Support Portal to open port 8089 on your deployment. 

https://<deployment-name>.splunkcloud.com:8089

Free trial Splunk Cloud Platform accounts cannot access the REST API.

See Access requirements and limitations for the Splunk Cloud Platform REST API in the the REST API Tutorials manual for more information.


catalog/metricstore/metrics

https://<host>:<mPort>/services/catalog/metricstore/metrics

Use this endpoint to list metric names.

GET

Returns metric names.

Request parameters
Pagination and filtering parameters can be used with this method.

Name Type Description
earliest String Optional. A time string that specifies the earliest time for this search. Can be a relative or absolute time. The default value is -1d.
filter String Optional. A URL-encoded set of one or more key-value pairs, where keys correspond to metric fields such as index or dimension. For example, to specify a dimension named app, use filter=app. To specify two index names and values such as index=index1 and index=index2, use index%3dindex1%26index%3dindex2.
latest String Optional. A time string that specifies the latest time for this search. Can be a relative or absolute time. The default value is now.
list_indexes Boolean Optional. When set to true, the endpoint returns the index or indexes associated with each metric. The default value is false.

Returned values
There are no returned values other than the metric names.

Example request and response

XML Request
List all metric names: 

curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/metrics

XML Response

...
  <title>metricstore-metrics</title>
  <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/metrics</id>
  <updated>2017-12-19T19:11:49+00:00</updated>
  <generator build="31fcdba9ddc1" version="7.0.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/catalog/metricstore/metrics/_acl" rel="_acl"/>
  <opensearch:totalResults>16</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>aws.ec2.CPUUtilization</title>
    <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/metrics/aws.ec2.CPUUtilization</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/services/catalog/metricstore/metrics/aws.ec2.CPUUtilization" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/catalog/metricstore/metrics/aws.ec2.CPUUtilization" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">0</s:key>
            <s:key name="can_write">0</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>bbuser</s:item>
                    <s:item>cat_read</s:item>
                    <s:item>power</s:item>
                    <s:item>splunk-system-role</s:item>
                    <s:item>statsd</s:item>
                    <s:item>user</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list/>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
      </s:dict>
    </content>
  </entry>
  <entry>

Example requests

  • List all metric names that include the dimension field dc:
curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/metrics?filter=dc
  • List all metric names that include either dc=east or dc=west dimension fields:
curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/metrics?filter=dc%3deast&filter=dc%3dwest
  • List all metric names that are in index1 or index2 by their index:
curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/metrics?filter=index%3dindex1%26index%3dindex2&list_indexes=t

catalog/metricstore/dimensions

https://<host>:<mPort>/services/catalog/metricstore/dimensions

Use this endpoint to list dimension names.

GET

Returns dimension names for a given metric.

Request parameters
Pagination and filtering parameters can be used with this method.

Name Type Description
earliest String Optional. A time string that specifies the earliest time for this search. Can be a relative or absolute time. The default value is -1d.
filter String Optional. A URL-encoded set of one or more key-value pairs, where keys correspond to metric fields such as index or dimension. For example, to specify a dimension named os, use filter=os. To specify two index names and values such asindex=index1 and index=index2, use index%3dindex1%26index%3dindex2.
latest String Optional. A time string that specifies the latest time for this search. Can be a relative or absolute time. The default value is now.
metric_name String Required. The name of a metric.

Returned values
There are no returned values other than the dimension names.

Example request and response

XML Request

curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/dimensions?metric_name=*

XML Response

...
  <title>metricstore-dimensions</title>
  <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/dimensions</id>
  <updated>2017-12-19T00:02:27+00:00</updated>
  <generator build="31fcdba9ddc1" version="7.0.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/catalog/metricstore/dimensions/_acl" rel="_acl"/>
  <opensearch:totalResults>7</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>App</title>
    <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/dimensions/App</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/services/catalog/metricstore/dimensions/App" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/catalog/metricstore/dimensions/App" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">0</s:key>
            <s:key name="can_write">0</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>bbuser</s:item>
                    <s:item>cat_read</s:item>
                    <s:item>power</s:item>
                    <s:item>splunk-system-role</s:item>
                    <s:item>statsd</s:item>
                    <s:item>user</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list/>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
      </s:dict>
    </content>
  </entry>

Another example request'

List all the dimension fields for the os.mem.free metric when the dc dimension field is limited to a value of east: 

curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/dimensions?metric_name=os.mem.free&filter=dc%3deast

catalog/metricstore/dimensions/{dimension-name}/values

https://<host>:<mPort>/services/catalog/metricstore/dimensions/{dimension-name}/values

Use this endpoint to list values for a given {dimension-name}.

GET

Returns values of a {dimension-name} for a given metric.

Request parameters
Pagination and filtering parameters can be used with this method.

Name Type Description
earliest String Optional. A time string that specifies the earliest time for this search. Can be a relative or absolute time. The default value is -1d.
filter String Optional. A URL-encoded set of one or more key-value pairs, where keys correspond to metric fields such as index or dimension. For example, to specify a dimension named os, use filter=os. To specify two index names and values such asindex=index1 and index=index2, use index%3dindex1%26index%3dindex2.
latest String Optional. A time string that specifies the latest time for this search. Can be a relative or absolute time. The default value is now.
metric_name String Required. The name of a metric.

Returned values
There are no returned values other than those of the selected {dimension-name}.

Example request and response

XML Request

List all values for the app dimension of the os.mem.free metric: 

curl -k -u statsd:statsd https://localhost:8089/services/catalog/metricstore/dimensions/app/values?metric_name=os.mem.free

XML Response 

...
  <title>metricstore-dimensions</title>
  <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/dimensions</id>
  <updated>2017-12-19T02:05:19+00:00</updated>
  <generator build="31fcdba9ddc1" version="7.0.0"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/catalog/metricstore/dimensions/_acl" rel="_acl"/>
  <opensearch:totalResults>7</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
  <entry>
    <title>accountmanagement</title>
    <id>https://epic-metriks-splk.sv.splunk.com:8089/services/catalog/metricstore/dimensions/accountmanagement</id>
    <updated>1970-01-01T00:00:00+00:00</updated>
    <link href="/services/catalog/metricstore/dimensions/accountmanagement" rel="alternate"/>
    <author>
      <name>system</name>
    </author>
    <link href="/services/catalog/metricstore/dimensions/accountmanagement" rel="list"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app"></s:key>
            <s:key name="can_list">0</s:key>
            <s:key name="can_write">0</s:key>
            <s:key name="modifiable">0</s:key>
            <s:key name="owner">system</s:key>
            <s:key name="perms">
              <s:dict>
                <s:key name="read">
                  <s:list>
                    <s:item>admin</s:item>
                    <s:item>bbuser</s:item>
                    <s:item>cat_read</s:item>
                    <s:item>power</s:item>
                    <s:item>splunk-system-role</s:item>
                    <s:item>statsd</s:item>
                    <s:item>user</s:item>
                  </s:list>
                </s:key>
                <s:key name="write">
                  <s:list/>
                </s:key>
              </s:dict>
            </s:key>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
      </s:dict>
    </content>
  </entry>

More example requests

  • List all values for the dc dimension of the os.mem.free metric, where dc is limited to a value of east:
curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/dimensions/dc/values?metric_name=os.mem.free&filter=dc%3deast
  • List all values for the dc dimension of the mem.free metric, where the recorded measurements also have an os dimension field:
curl -k -u admin:changeme  https://localhost:8089/services/catalog/metricstore/rollup

catalog/metricstore/rollup

https://<host>:<mPort>/services/catalog/metricstore/rollup

Use this endpoint to retrieve lists of metric indexes and their rollup summaries and to create new rollup policies for a given metric index.

Authentication and authorization
Use of the GET operation for this endpoint is restricted to roles that have the list_metrics_catalog capability. Use of the POST operation for this endpoint is restricted to roles that have the edit_metrics_rollup capability.

GET

Returns rollup summaries and the metric indexes with which they are associated.

Request parameters
None specific to this method. This method can use pagination and filtering parameters.

Returned values

Name Description
name The source index name. Rollup summaries are made up of aggregated metric data points that are derived from the metric data points in a source index.
summaries A comma-separated list of the rollup summaries associated with the source metric index. Each summary configuration consists of a span and a rollup_index. The span is the interval by which the search head generates the aggregated rollup metric data points that make up the summary. The rollup_index is the target index for the rollup summary. The endpoint uses the following format when it lists summaries:

<span_1>|<rollup_index_1>,<span_2>|<rollup_index_2>...<span_n>|<rollup_index_n>

Example request and response

XML Request

curl -k -u admin:changeme  https://localhost:8089/services/catalog/metricstore/rollup

XML response

...
  <entry>
    <title>index_s</title>
    <id>https://127.0.0.1:8101/servicesNS/nobody/search/catalog/metricstore/rollup/index_s</id>
    <updated>1969-12-31T16:00:00-08:00</updated>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="list"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="edit"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="remove"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="aggregation.foo1">min#avg</s:key>
        <s:key name="aggregation.foo2">count#avg</s:key>
        <s:key name="defaultAggregation">avg#max</s:key>
        <s:key name="dimensionList">app,region</s:key>
        <s:key name="dimensionListType">included</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">search</s:key>
            <s:key name="can_change_perms">1</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_share_app">1</s:key>
            <s:key name="can_share_global">1</s:key>
            <s:key name="can_share_user">0</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">1</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms"/>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="metricList">foo3,foo4</s:key>
        <s:key name="metricListType">excluded</s:key>
        <s:key name="minSpanAllowed">300</s:key>
        <s:key name="summaries">
          <s:dict>
            <s:key name="0">
              <s:dict>
                <s:key name="rollupIndex">index_d_1h</s:key>
                <s:key name="span">1h</s:key>
              </s:dict>
            </s:key>
            <s:key name="1">
              <s:dict>
                <s:key name="rollupIndex">index_d_1d</s:key>
                <s:key name="span">1d</s:key>
              </s:dict>
            </s:key>
          </s:dict>
        </s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST

Creates rollup policies for a specified metric index.

Request parameters

Name Type Description
name String Required. Specify the name of the source metric index. This is the index from which the aggregated metric data points in the rollup summaries will be derived.
summaries String Required. Specify one or more rollup summaries, separated by commas. A rollup summary is a combination of a rollup period and a rollup metric index.


The rollup period is the span. This time range string is the interval on which the search head generates the aggregated rollup metric data points that make up the summary.

The rollup span is limited to the following values for minutes, hours, and days. Other time units are not allowed.

Time unit Valid values
m (minutes) 1,2,3,4,5,6,10,12,20,30,60
h (hours) 1,2,3,4,6,8,12,24
d (days) 1

The rollup index is the target index for the rollup summary.

The endpoint uses the following format when it lists summaries:
<span_1>|<rollup_index_1>,<span_2>|<rollup_index_2>...<span_n>|<rollup_index_n>. Defaults to 1hr|<name>.

default_agg String Optional. A list of aggregation functions, separated by # characters. Provides the set of aggregation functions that the rollup search uses when it aggregates the metric data points in the source metric index for a rollup summary. The defaultAggregation can be overruled for specific metrics by the aggregation.<metric_name> setting. This setting supports the following functions: avg, count, max, median, min, perc<int>, and sum. Defaults to avg.
metric_list String Optional. A comma-separated list of metric names. All of the listed metrics must appear in the source metric index identified by the name parameter. This list works in conjunction with the metric_list_type parameter to create a filter at the search head that allows certain metrics to be rolled up but not others. Defaults to empty string.
metric_list_type [included | excluded] Optional. Works in conjunction with the metric_list parameter to create a filter at the search head that allows certain metrics to be rolled up to the rollup summaries but not others. Defaults to excluded.
  • Use included to indicate that the search head should filter out all available metrics from the set of metrics being rolled up to the rollup summaries, except for the metrics listed in metric_list parameter.
  • Use excluded to indicate that the search head should roll up all available metrics to the rollup summaries except the metrics listed in metric_list parameter.
dimension_list String Optional. A comma-separated list of dimensions that appear in the source metric index identified by the name parameter. This list corresponds to the dimension_list_type parameter, which determines whether this set of dimensions is included or excluded from the aggregated rollup metrics that the search head generates for the rollup summary. Defaults to empty string.
dimension_list_type [included | excluded] Optional. Identifies whether the dimensions specified in the dimension_list parameter are included or excluded from the rollup metrics that are generated by the rollup policies for the rollup summaries. Defaults to excluded.
  • Use included to indicate that the rollup metrics produced by the rollup policy filter out all dimensions except the dimensions listed in the dimension_list parameter.
  • Use excluded to indicate that the rollup metrics produced by the rollup policy include all available dimensions except the dimensions in the dimension_list parameter.
metric_overrides String Optional. Provides a comma-separated list of exclusion rules for a set of rollup policies. Use this setting to override the default aggregation for one or more metrics. Each metric override pairs a metric name with one or more aggregation functions separated by # characters. Each metric override uses the following syntax: <metric_name>|<aggregation_function_1>#<aggregation_function_2>#…<aggregation_function_n. Only the following aggregation functions are allowed: avg, count, max, median, min, perc<int>, and sum. Defaults to empty string.

Returned values

Name Description
aggregation.<metric_name> Overrides the default aggregation or set of aggregations for the specified metric_name and gives it a different aggregation or set of aggregations instead. Defined by the metric_overrides argument.
defaultAggregation The default aggregation methods for the rollup policy, separated by # characters.
dimensionList Comma-separated list of dimensions to be included or excluded from the aggregations, depending on the value of dimensionListType.
dimensionListType Indicates whether the dimensionList should be included or excluded from the rollup policy.
metricList Comma-separated list of metrics to be included or excluded from the set of metrics rolled up to the summaries, depending on the value of dimensionListType
metricListType Indicates whether the metricList should be included or excluded from the rollup policy.
rollup.<summary number>.rollupIndex The target rollup index for a specific summary. Summaries are identified by the <summary number>.
rollup.<summary number>.span The rollup span for a specific summary. Summaries are identified by the <summary number>.

Example request and response

Place this stanza in metric_rollups.conf: 

 [index:index_s]
 aggregation.foo1 = min#avg
 aggregation.foo2 = count#avg
 defaultAggregation = avg#max
 dimensionList = app,region
 dimensionListType = included
 metricList = foo3,foo4
 metricListType = excluded
 rollup.0.rollupIndex = index_d_1h
 rollup.0.span = 1h
 rollup.1.rollupIndex = index_d_1d
 rollup.1.span = 1d

XML Request

curl -k -u admin:changeme https://localhost:8089/services/catalog/metricstore/rollup  -d name=index_s -d default_agg=avg#max -d dimension_list="app,region" -d dimension_list_type=included -d metric_overrides="foo2|count#avg,foo1|min#avg" -d summaries="1h|index_d_1h,1d|index_d_1d" -d metric_list="foo3,foo4" -d metric_list_type=excluded

XML response

...
  <entry>
    <title>index_s</title>
    <id>https://127.0.0.1:8101/servicesNS/nobody/search/catalog/metricstore/rollup/index_s</id>
    <updated>1969-12-31T16:00:00-08:00</updated>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="list"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="edit"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="aggregation.foo1">min#avg</s:key>
        <s:key name="aggregation.foo2">count#avg</s:key>
        <s:key name="defaultAggregation">avg#max</s:key>
        <s:key name="dimensionList">app,region</s:key>
        <s:key name="dimensionListType">included</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">search</s:key>
            <s:key name="can_change_perms">1</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_share_app">1</s:key>
            <s:key name="can_share_global">1</s:key>
            <s:key name="can_share_user">0</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">1</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms"/>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="metricList">foo3,foo4</s:key>
        <s:key name="metricListType">excluded</s:key>
        <s:key name="minSpanAllowed">300</s:key>
        <s:key name="summaries">
          <s:dict>
            <s:key name="0">
              <s:dict>
                <s:key name="rollupIndex">index_d_1h</s:key>
                <s:key name="span">1h</s:key>
              </s:dict>
            </s:key>
            <s:key name="1">
              <s:dict>
                <s:key name="rollupIndex">index_d_1d</s:key>
                <s:key name="span">1d</s:key>
              </s:dict>
            </s:key>
          </s:dict>
        </s:key>
      </s:dict>
    </content>
  </entry>
</feed>


catalog/metricstore/rollup/{index}

https://<host>:<mPort>/services/catalog/metricstore/rollup/{index}

Use this endpoint to:

  • Retrieve a list of the rollup summaries associated with a specific source {index}.
  • Update a rollup policy for a specific specific source {index}.
  • Delete a rollup policy for a specific specific source {index}.

Authentication and Authorization
Use of the GET operation for this endpoint is restricted to roles that have the list_metrics_catalog capability. Usage of the POST and DELETE operations for this endpoint are restricted to roles that have the edit_metrics_rollup capability.

GET

Returns a list of the rollup summaries associated with a specific source {index}.

Request parameters
None specific to this method. This method can use pagination and filtering parameters.

Returned values

Name Description
summaries A comma-separated list of the rollup summaries associated with the source metric {index}. Each summary configuration consists of a span and a rollup_index. The span is the interval by which the search head generates the aggregated rollup metric data points that make up the summary. The rollup_index is the target index for the rollup summary. The endpoint uses the following format when it lists summaries:

<span_1>|<rollup_index_1>,<span_2>|<rollup_index_2>...<span_n>|<rollup_index_n>

Example request and response

XML Request

curl -k -u admin:changeme  https://localhost:8089/services/catalog/metricstore/rollup/index_s

XML response

...
  <entry>
    <title>index_s</title>
    <id>https://localhost:8089/servicesNS/nobody/search/catalog/metricstore/rollup/index_s</id>
    <updated>1969-12-31T16:00:00-08:00</updated>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="list"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="edit"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="remove"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s/disable" rel="disable"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="aggregation.foo1"> min#avg </s:key>
        <s:key name="aggregation.foo2"> count#avg </s:key>
        <s:key name="defaultAggregation"> avg#max </s:key>
        <s:key name="dimensionList">app,region</s:key>
        <s:key name="dimensionListType">included</s:key>
        <s:key name="disabled">0</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">search</s:key>
            <s:key name="can_change_perms">1</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_share_app">1</s:key>
            <s:key name="can_share_global">1</s:key>
            <s:key name="can_share_user">0</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">1</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms"/>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="eai:attributes">
          <s:dict>
            <s:key name="optionalFields">
              <s:list>
                <s:item>default_agg</s:item>
                <s:item>dimension_list</s:item>
                <s:item>dimension_list_type</s:item>
                <s:item>isProxyRequest</s:item>
                <s:item>metric_overrides</s:item>
                <s:item>noProxy</s:item>
                <s:item>summaries</s:item>
              </s:list>
            </s:key>
            <s:key name="requiredFields">
              <s:list/>
            </s:key>
            <s:key name="wildcardFields">
              <s:list/>
            </s:key>
          </s:dict>
        </s:key>
        <s:key name="metricList">foo3,foo4</s:key>
        <s:key name="metricListType">excluded</s:key>
        <s:key name="minSpanAllowed">300</s:key>
        <s:key name="summaries">
          <s:dict>
            <s:key name="0">
              <s:dict>
                <s:key name="rollupIndex">index_d_1h</s:key>
                <s:key name="span">1h</s:key>
              </s:dict>
            </s:key>
            <s:key name="1">
              <s:dict>
                <s:key name="rollupIndex">index_d_1d</s:key>
                <s:key name="span">1d</s:key>
              </s:dict>
            </s:key>
          </s:dict>
        </s:key>
      </s:dict>
    </content>
  </entry>
</feed>

POST

Updates a rollup policy for a specific source {index}.

Request parameters

At least one argument is required.

Name Type Description
default_agg String Optional. A list of aggregation functions, separated by # characters. Provides the set of aggregation functions that the rollup search uses when it aggregates the metric data points in the source metric index for a rollup summary. The defaultAggregation can be overruled for specific metrics by the aggregation.<metric_name> setting. This setting supports the following functions: avg, count, max, median, min, perc<int>, and sum. Defaults to avg.
metric_list String Optional. A comma-separated list of metric names. All of the listed metrics must appear in the source metric index identified by the name parameter. This list works in conjunction with the metric_list_type parameter to create a filter at the search head that allows certain metrics to be rolled up but not others. Defaults to empty string.
metric_list_type [included | excluded] Optional. Works in conjunction with the metric_list parameter to create a filter at the search head that allows certain metrics to be rolled up to the rollup summaries but not others. Defaults to excluded.
  • Use included to indicate that the search head should filter out all available metrics from the set of metrics being rolled up to the rollup summaries, except for the metrics listed in metric_list parameter.
  • Use excluded to indicate that the search head should roll up all available metrics to the rollup summaries except the metrics listed in metric_list parameter.
dimension_list string Optional. A comma-separated list of dimensions that appear in the source index. This list corresponds to the dimension_list_type parameter, which determines whether this set of dimensions is included or excluded from the aggregated rollup metrics that the search head generates for the rollup summary. Defaults to empty string.
dimension_list_type [included | excluded] Optional. Identifies whether the dimensions specified in the dimension_list parameter are included or excluded from the rollup metrics that are generated by the rollup policies for the rollup summaries.
  • Use included to indicate that the rollup metrics produced by the rollup policy filter out all dimensions except the dimensions listed in the dimension_list parameter.
  • Use excluded to indicate that the rollup metrics produced by the rollup policy include all available dimensions except the dimensions in the dimension_list parameter.
metric_overrides String Optional. Provides a comma-separated list of exclusion rules for a set of rollup policies. Use this setting to override the default aggregation for one or more metrics. Each metric override pairs a metric name with one or more aggregation functions separated by # characters. Each metric override uses the following syntax: <metric_name>|<aggregation_function_1>#<aggregation_function_2>#…<aggregation_function_n. Only the following aggregation functions are allowed: avg, count, max, median, min, perc<int>, and sum. Defaults to empty string.
summaries string Optional. Specify one or more rollup summaries, separated by commas. A rollup summary is a combination of a rollup period and a rollup metric index.


The rollup period is the span. It is the interval on which the search head generates the aggregated rollup metric data points that make up the summary.

The rollup span is limited to the following values for minutes, hours, and days. Other time units are not allowed.

Time unit Valid values
m (minutes) 1,2,3,4,5,6,10,12,20,30,60
h (hours) 1,2,3,4,6,8,12,24
d (days) 1

The rollup index is the target index for the rollup summary.

The endpoint uses the following format when it lists summaries:
<span_1>|<rollup_index_1>,<span_2>|<rollup_index_2>...<span_n>|<rollup_index_n>

Returned values

Name Description
aggregation.<metric_name> Overrides the default aggregation or set of aggregations for the specified metric_name and gives it a different aggregation or set of aggregations instead. Defined by the metric_overrides argument.
defaultAggregation The default aggregation methods for the rollup policy, separated by # characters.
dimensionList Comma-separated list of dimensions to be included or excluded from the aggregations, depending on the value of dimensionListType.
dimensionListType Indicates whether the dimensionList should be included or excluded from the rollup policy.
metricList Comma-separated list of metrics to be included or excluded from the set of metrics rolled up to the summaries, depending on the value of dimensionListType
metricListType Indicates whether the metricList should be included or excluded from the rollup policy.
rollup.<summary number>.rollupIndex The target rollup index for a specific summary. Summaries are identified by the <summary number>.
rollup.<summary number>.span The rollup span for a specific summary. Summaries are identified by the <summary number>.

Example request and response

Place this stanza in metric_rollups.conf: 

[index:index_s]
aggregation.foo1 = min#avg
aggregation.foo2 = count#avg
defaultAggregation = avg#max
dimensionList = app,region
dimensionListType = included
metricList = foo3,foo4
metricListType = excluded
numRollupPolicy = 1
rollup.0.rollupIndex = index_d_30m
rollup.0.span = 30m

XML Request

curl -k -u admin:changeme  https://localhost:8089/services/catalog/metricstore/rollup/index_s -d summaries="30m|index_d_30m"

XML response

...
  <entry>
    <title>index_s</title>
    <id>https://localhost:8089/servicesNS/nobody/search/catalog/metricstore/rollup/index_s</id>
    <updated>1969-12-31T16:00:00-08:00</updated>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="alternate"/>
    <author>
      <name>nobody</name>
    </author>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="list"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s/_reload" rel="_reload"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="edit"/>
    <link href="/servicesNS/nobody/search/catalog/metricstore/rollup/index_s" rel="remove"/>
    <content type="text/xml">
      <s:dict>
        <s:key name="aggregation.foo1">min#avg</s:key>
        <s:key name="aggregation.foo2">count#avg</s:key>
        <s:key name="defaultAggregation">avg#max</s:key>
        <s:key name="dimensionList">app,region</s:key>
        <s:key name="dimensionListType">included</s:key>
        <s:key name="eai:acl">
          <s:dict>
            <s:key name="app">search</s:key>
            <s:key name="can_change_perms">1</s:key>
            <s:key name="can_list">1</s:key>
            <s:key name="can_share_app">1</s:key>
            <s:key name="can_share_global">1</s:key>
            <s:key name="can_share_user">0</s:key>
            <s:key name="can_write">1</s:key>
            <s:key name="modifiable">1</s:key>
            <s:key name="owner">nobody</s:key>
            <s:key name="perms"/>
            <s:key name="removable">0</s:key>
            <s:key name="sharing">system</s:key>
          </s:dict>
        </s:key>
        <s:key name="metricList">foo3,foo4</s:key>
        <s:key name="metricListType">excluded</s:key>
        <s:key name="minSpanAllowed">300</s:key>
        <s:key name="summaries">
          <s:dict>
            <s:key name="0">
              <s:dict>
                <s:key name="rollupIndex">index_d_30m</s:key>
                <s:key name="span">30m</s:key>
              </s:dict>
            </s:key>
          </s:dict>
        </s:key>
      </s:dict>
    </content>
  </entry>
</feed>

DELETE

Deletes a rollup policy for a specific source {index}.

Request parameters
None specific to this method.

Returned values
None specific to this method.

Example request and response

Remove the [index:metric_x] stanza from metric_rollups.conf.

XML Request

curl -k -u admin:changeme -X DELETE https://localhost:8089/services/catalog/metricstore/rollup/metric_x

XML response

<feed xmlns="http://www.w3.org/2005/Atom" xmlns:s="http://dev.splunk.com/ns/rest" xmlns:opensearch="http://a9.com/-/spec/opensearch/1.1/">
  <title>metricstore_rollup</title>
  <id>https://localhost:8089/services/catalog/metricstore/rollup</id>
  <updated>2019-03-20T16:40:00-07:00</updated>
  <generator build="86a463dcd7353fbb093dddacb657f1314fff6529" version="20190319"/>
  <author>
    <name>Splunk</name>
  </author>
  <link href="/services/catalog/metricstore/rollup/_new" rel="create"/>
  <link href="/services/catalog/metricstore/rollup/_reload" rel="_reload"/>
  <link href="/services/catalog/metricstore/rollup/_acl" rel="_acl"/>
  <opensearch:totalResults>0</opensearch:totalResults>
  <opensearch:itemsPerPage>30</opensearch:itemsPerPage>
  <opensearch:startIndex>0</opensearch:startIndex>
  <s:messages/>
</feed>
Last modified on 19 January, 2023
License endpoint descriptions   Output endpoint descriptions

This documentation applies to the following versions of Splunk® Enterprise: 9.0.0, 9.0.1, 9.0.2, 9.0.3, 9.0.4, 9.0.5, 9.0.6, 9.0.7, 9.0.8, 9.0.9, 9.0.10, 9.1.0, 9.1.1, 9.1.2, 9.1.3, 9.1.4, 9.1.5, 9.1.6, 9.2.0, 9.2.1, 9.2.2, 9.2.3, 9.3.0, 9.3.1

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters