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 is 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 URL for REST API access
Splunk Cloud has a different host and management port syntax than Splunk Enterprise. Use the following URL for Splunk Cloud 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 accounts cannot access the REST API.
See Using the REST API in Splunk Cloud in the the Splunk REST API Tutorials 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
ordc=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
orindex2
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 given dimensions.
GET
Returns values of a dimension 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.
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 theos.mem.free
metric, wheredc
is limited to a value ofeast
:
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 themem.free
metric, where the recorded measurements also have anos
dimension field:
curl -k -u admin:passwd https://localhost:8089/services/catalog/metricstore/dimensions/dc/values?metric_name=mem.free&filter=os
License endpoint descriptions | Output endpoint descriptions |
This documentation applies to the following versions of Splunk® Enterprise: 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.1.10, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.2.9, 7.2.10
Feedback submitted, thanks!