You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ambari.apache.org by tb...@apache.org on 2013/06/03 20:13:31 UTC
svn commit: r1489086 - in /incubator/ambari/trunk/ambari-server/docs/api/v1:
clusters-cluster.md index.md
Author: tbeerbower
Date: Mon Jun 3 18:13:30 2013
New Revision: 1489086
URL: http://svn.apache.org/r1489086
Log:
AMBARI-2260 - Bad hosts query example in API docs
Modified:
incubator/ambari/trunk/ambari-server/docs/api/v1/clusters-cluster.md
incubator/ambari/trunk/ambari-server/docs/api/v1/index.md
Modified: incubator/ambari/trunk/ambari-server/docs/api/v1/clusters-cluster.md
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/ambari-server/docs/api/v1/clusters-cluster.md?rev=1489086&r1=1489085&r2=1489086&view=diff
==============================================================================
--- incubator/ambari/trunk/ambari-server/docs/api/v1/clusters-cluster.md (original)
+++ incubator/ambari/trunk/ambari-server/docs/api/v1/clusters-cluster.md Mon Jun 3 18:13:30 2013
@@ -144,20 +144,21 @@ Get information for the cluster "c1".
}
}
],
- "hosts" : [
- {
- "href" : "http://your.ambari.server/api/v1/clusters/c1/hosts/host1",
- "Hosts" : {
- "cluster_name" : "c1",
- "host_name" : "some.cluster.host"
- }
- },
- {
- "href" : "http://your.ambari.server/api/v1/clusters/c1/hosts/host2",
- "Hosts" : {
- "cluster_name" : "c1",
- "host_name" : "another.cluster.host"
- }
- ]
+ "hosts" : [
+ {
+ "href" : "http://your.ambari.server/api/v1/clusters/c1/hosts/some.host",
+ "Hosts" : {
+ "cluster_name" : "c1",
+ "host_name" : "some.host"
+ }
+ },
+ {
+ "href" : "http://your.ambari.server/api/v1/clusters/c1/hosts/another.host",
+ "Hosts" : {
+ "cluster_name" : "c1",
+ "host_name" : "another.host"
+ }
+ }
+ ]
}
Modified: incubator/ambari/trunk/ambari-server/docs/api/v1/index.md
URL: http://svn.apache.org/viewvc/incubator/ambari/trunk/ambari-server/docs/api/v1/index.md?rev=1489086&r1=1489085&r2=1489086&view=diff
==============================================================================
--- incubator/ambari/trunk/ambari-server/docs/api/v1/index.md (original)
+++ incubator/ambari/trunk/ambari-server/docs/api/v1/index.md Mon Jun 3 18:13:30 2013
@@ -34,7 +34,8 @@ The Ambari API facilitates the managemen
Release Version
----
-_Last Updated April 25, 2013_
+_Last Updated June 3, 2013; Note that this is the official release of Ambari V1 API_
+
Authentication
----
@@ -318,42 +319,312 @@ Used to control which fields are returne
GET /api/v1/clusters/c1/services/HDFS/components/NAMENODE?fields=metrics/disk/disk_total
- 200 OK
{
âhrefâ: â.../api/v1/clusters/c1/services/HDFS/components/NAMENODE?fields=metrics/disk/disk_totalâ,
âServiceComponentInfoâ : {
âcluster_nameâ : âc1â,
âcomponent_nameâ : NAMENODEâ,
âservice_nameâ : âHDFSâ
},
âmetricsâ : {
"disk" : {
"disk_total" : 100000
}
}
}
-
**Example: Using Partial Response to restrict response to specified category**
+ 200 OK
+ {
+ âhrefâ: â.../api/v1/clusters/c1/services/HDFS/components/NAMENODE?fields=metrics/disk/disk_totalâ,
+ âServiceComponentInfoâ : {
+ âcluster_nameâ : âc1â,
+ âcomponent_nameâ : NAMENODEâ,
+ âservice_nameâ : âHDFSâ
+ },
+ âmetricsâ : {
+ "disk" : {
+ "disk_total" : 100000
+ }
+ }
+ }
+
+**Example: Using Partial Response to restrict response to specified category**
GET /api/v1/clusters/c1/services/HDFS/components/NAMENODE?fields=metrics/disk
- 200 OK
{
âhrefâ: â.../api/v1/clusters/c1/services/HDFS/components/NAMENODE?fields=metrics/diskâ,
âServiceComponentInfoâ : {
âcluster_nameâ : âc1â,
âcomponent_nameâ : NAMENODEâ,
âservice_nameâ : âHDFSâ
},
âmetricsâ : {
"disk" : {
"disk_total" : 100000,
âdisk_freeâ : 50000,
âpart_max_usedâ : 1010
}
}
}
+ 200 OK
+ {
+ âhrefâ: â.../api/v1/clusters/c1/services/HDFS/components/NAMENODE?fields=metrics/diskâ,
+ âServiceComponentInfoâ : {
+ âcluster_nameâ : âc1â,
+ âcomponent_nameâ : NAMENODEâ,
+ âservice_nameâ : âHDFSâ
+ },
+ âmetricsâ : {
+ "disk" : {
+ "disk_total" : 100000,
+ âdisk_freeâ : 50000,
+ âpart_max_usedâ : 1010
+ }
+ }
+ }
**Example â Using Partial Response to restrict response to multiple fields/categories**
GET /api/v1/clusters/c1/services/HDFS/components/NAMENODE?fields=metrics/disk/disk_total,metrics/cpu
- 200 OK
{
âhrefâ: â.../api/v1/clusters/c1/services/HDFS/components/NAMENODE?fields=metrics/disk/disk_total,metrics/cpuâ,
âServiceComponentInfoâ : {
âcluster_nameâ : âc1â,
âcomponent_nameâ : NAMENODEâ,
âservice_nameâ : âHDFSâ
},
âmetricsâ : {
"disk" : {
"disk_total" : 100000
},
âcpuâ : {
âcpu_speedâ : 10000000,
âcpu_numâ : 4,
âcpu_idleâ : 999999,
...
}
}
}
**Example â Using Partial Response to restrict response to a sub-resource**
-
GET /api/v1/clusters/c1/hosts/host1?fields=host_components
-
200 OK
{
âhrefâ: â.../api/v1/clusters/c1/hosts/host1?fields=host_componentsâ,
âHostsâ : {
âcluster_nameâ : âc1â,
âhost_nameâ : âhost1â
},
âhost_componentsâ: [
{
âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/NAMENODEâ
âHostRolesâ : {
âcluster_nameâ : âc1â,
âcomponent_nameâ : âNAMENODEâ,
âhost_nameâ : âhost1â
}
},
{
âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/DATANODEâ
âHostRolesâ : {
âcluster_nameâ : âc1â,
âcomponent_nameâ : DATANODEâ,
âhost_nameâ : âhost1â
}
},
- ...
]
}
**Example â Using Partial Response to expand a sub-resource one level deep**
-
GET /api/v1/clusters/c1/hosts/host1?fields=host_components/*
-
200 OK
{
âhrefâ: â.../api/v1/clusters/c1/hosts/host1?fields=host_components/*â,
âHostsâ : {
âcluster_nameâ : âc1â,
âhost_nameâ : âhost1â
},
- âhost_componentsâ: [
{
âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/DATANODEâ
âHostRolesâ : {
âcluster_nameâ : âc1â,
âcomponent_nameâ : DATANODEâ,
âhost_nameâ : âhost1â,
âstateâ : âRUNNINGâ,
...
},
"host" : {
"href" : ".../api/v1/clusters/c1/hosts/host1"
},
âmetricsâ : {
"disk" : {
"disk_total" : 100000000,
"disk_free" : 5000000,
"part_max_used" : 10101
},
...
},
"component" : {
"href" : "http://ambari.server/api/v1/clusters/c1/services/HDFS/components/NAMENODE",
âServiceComponentInfoâ : {
"cluster_name" : "c1",
"component_name" : "NAMENODE",
"service_name" : "HDFS"
}
}
},
...
]
}
+ 200 OK
+ {
+ âhrefâ: â.../api/v1/clusters/c1/services/HDFS/components/NAMENODE?fields=metrics/disk/disk_total,metrics/cpuâ,
+ âServiceComponentInfoâ : {
+ âcluster_nameâ : âc1â,
+ âcomponent_nameâ : NAMENODEâ,
+ âservice_nameâ : âHDFSâ
+ },
+ âmetricsâ : {
+ "disk" : {
+ "disk_total" : 100000
+ },
+ âcpuâ : {
+ âcpu_speedâ : 10000000,
+ âcpu_numâ : 4,
+ âcpu_idleâ : 999999,
+ ...
+ }
+ }
+ }
+
+**Example â Using Partial Response to restrict response to a sub-resource**
+
+ GET /api/v1/clusters/c1/hosts/host1?fields=host_components
+
+ 200 OK
+ {
+ âhrefâ: â.../api/v1/clusters/c1/hosts/host1?fields=host_componentsâ,
+ âHostsâ : {
+ âcluster_nameâ : âc1â,
+ âhost_nameâ : âhost1â
+ },
+ âhost_componentsâ: [
+ {
+ âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/NAMENODEâ
+ âHostRolesâ : {
+ âcluster_nameâ : âc1â,
+ âcomponent_nameâ : âNAMENODEâ,
+ âhost_nameâ : âhost1â
+ }
+ },
+ {
+ âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/DATANODEâ
+ âHostRolesâ : {
+ âcluster_nameâ : âc1â,
+ âcomponent_nameâ : DATANODEâ,
+ âhost_nameâ : âhost1â
+ }
+ },
+ ...
+ ]
+ }
+
+**Example â Using Partial Response to expand a sub-resource one level deep**
+
+ GET /api/v1/clusters/c1/hosts/host1?fields=host_components/*
+
+ 200 OK
+ {
+ âhrefâ: â.../api/v1/clusters/c1/hosts/host1?fields=host_components/*â,
+ âHostsâ : {
+ âcluster_nameâ : âc1â,
+ âhost_nameâ : âhost1â
+ },
+ âhost_componentsâ: [
+ {
+ âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/DATANODEâ
+ âHostRolesâ : {
+ âcluster_nameâ : âc1â,
+ âcomponent_nameâ : DATANODEâ,
+ âhost_nameâ : âhost1â,
+ âstateâ : âRUNNINGâ,
+ ...
+ },
+ "host" : {
+ "href" : ".../api/v1/clusters/c1/hosts/host1"
+ },
+ âmetricsâ : {
+ "disk" : {
+ "disk_total" : 100000000,
+ "disk_free" : 5000000,
+ "part_max_used" : 10101
+ },
+ ...
+ },
+ "component" : {
+ "href" : "http://ambari.server/api/v1/clusters/c1/services/HDFS/components/NAMENODE",
+ âServiceComponentInfoâ : {
+ "cluster_name" : "c1",
+ "component_name" : "NAMENODE",
+ "service_name" : "HDFS"
+ }
+ }
+ },
+ ...
+ ]
+ }
+
**Example â Using Partial Response for multi-level expansion of sub-resources**
GET /api/v1/clusters/c1/hosts/host1?fields=host_components/component/*
- 200 OK
{
âhrefâ: âhttp://ambari.server/api/v1/clusters/c1/hosts/host1?fields=host_components/*â,
âHostsâ : {
âcluster_nameâ : âc1â,
âhost_nameâ : âhost1â
...
},
+ 200 OK
+ {
+ âhrefâ: âhttp://ambari.server/api/v1/clusters/c1/hosts/host1?fields=host_components/*â,
+ âHostsâ : {
+ âcluster_nameâ : âc1â,
+ âhost_nameâ : âhost1â
+ ...
+ },
âhost_componentsâ: [
- {
âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/DATANODEâ,
âHostRolesâ : {
âcluster_nameâ : âc1â,
âcomponent_nameâ : DATANODEâ,
âhost_nameâ : âhost1â
},
"component" : {
"href" : "http://ambari.server/api/v1/clusters/c1/services/HDFS/components/DATANODE",
âServiceComponentInfoâ : {
"cluster_name" : "c1",
"component_name" : "DATANODE",
"service_name" : "HDFS"
...
},
âmetricsâ: {
âdfsâ: {
âdatanodeâ : {
âblocks_written " : 10000,
âblocks_read" : 5000,
...
}
},
âdiskâ: {
"disk_total " : 1000000,
âdisk_free" : 50000,
...
},
...
- }
}
},
{
âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/NAMENODEâ,
âHostRolesâ : {
âcluster_nameâ : âc1â,
âcomponent_nameâ : NAMENODEâ,
âhost_nameâ : âhost1â
},
"component" : {
"href" : "http://ambari.server/api/v1/clusters/c1/services/HDFS/components/NAMENODE",
âServiceComponentInfoâ : {
"cluster_name" : "c1",
"component_name" : "NAMENODE",
"service_name" : "HDFS"
},
âmetricsâ: {
âdfsâ: {
ânamenodeâ : {
âFilesRenamed " : 10,
âFilesDeleted" : 5
â¦
}
- },
âdiskâ: {
"disk_total " : 1000000,
âdisk_free" : 50000,
...
}
},
...
}
},
...
]
}
**Example: Using Partial Response to expand collection resource instances one level deep**
-
GET /api/v1/clusters/c1/hosts?fields=*
-
200 OK
{
âhrefâ : âhttp://ambari.server/api/v1/clusters/c1/hosts/?fields=*â,
âitemsâ: [
{
âhrefâ : âhttp://ambari.server/api/v1/clusters/c1/hosts/host1â,
âHostsâ : {
âcluster_nameâ : âc1â,
âhost_nameâ : âhost1â
},
âmetricsâ: {
âprocessâ: {
"proc_total" : 1000,
"proc_run" : 1000
},
...
},
âhost_componentsâ: [
{
âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/NAMENODEâ
âHostRolesâ : {
âcluster_nameâ : âc1â,
âcomponent_nameâ : âNAMENODEâ,
âhost_nameâ : âhost1â
}
},
{
âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/DATANODEâ
âHostRolesâ : {
âcluster_nameâ : âc1â,
âcomponent_nameâ : DATANODEâ,
âhost_nameâ : âhost1â
}
},
...
},
...
},
{
âhrefâ : âhttp://ambari.server/api/v1/clusters/c1/hosts/host2â,
âHostsâ : {
âcluster_nameâ : âc1â,
âhost_nameâ : âhost2â
},
âmetricsâ: {
âprocessâ: {
"proc_total" : 555,
"proc_run" : 55
},
...
},
âhost_componentsâ: [
{
âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/DATANODEâ
âHostRolesâ : {
âcluster_nameâ : âc1â,
âcomponent_nameâ : âDATANODEâ,
âhost_nameâ : âhost2â
}
},
...
],
...
},
...
]
}
### Additional Partial Response Examples
-
**Example â For each cluster, get cluster name, all hostnameâs and all service names**
-
GET /api/v1/clusters?fields=Clusters/cluster_name,hosts/Hosts/host_name,services/ServiceInfo/service_name
-
**Example - Get all hostnameâs for a given component**
-
GET /api/v1/clusters/c1/services/HDFS/components/DATANODE?fields=host_components/HostRoles/host_name
-
**Example - Get all hostnameâs and component names for a given service**
-
GET /api/v1/clusters/c1/services/HDFS?fields=components/host_components/HostRoles/host_name,
- components/host_components/HostRoles/component_name
+ {
+ âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/DATANODEâ,
+ âHostRolesâ : {
+ âcluster_nameâ : âc1â,
+ âcomponent_nameâ : DATANODEâ,
+ âhost_nameâ : âhost1â
+ },
+ "component" : {
+ "href" : "http://ambari.server/api/v1/clusters/c1/services/HDFS/components/DATANODE",
+ âServiceComponentInfoâ : {
+ "cluster_name" : "c1",
+ "component_name" : "DATANODE",
+ "service_name" : "HDFS"
+ ...
+ },
+ âmetricsâ: {
+ âdfsâ: {
+ âdatanodeâ : {
+ âblocks_written " : 10000,
+ âblocks_read" : 5000,
+ ...
+ }
+ },
+ âdiskâ: {
+ "disk_total " : 1000000,
+ âdisk_free" : 50000,
+ ...
+ },
+ ...
+ }
+ }
+ },
+ {
+ âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/NAMENODEâ,
+ âHostRolesâ : {
+ âcluster_nameâ : âc1â,
+ âcomponent_nameâ : NAMENODEâ,
+ âhost_nameâ : âhost1â
+ },
+ "component" : {
+ "href" : "http://ambari.server/api/v1/clusters/c1/services/HDFS/components/NAMENODE",
+ âServiceComponentInfoâ : {
+ "cluster_name" : "c1",
+ "component_name" : "NAMENODE",
+ "service_name" : "HDFS"
+ },
+ âmetricsâ: {
+ âdfsâ: {
+ ânamenodeâ : {
+ âFilesRenamed " : 10,
+ âFilesDeleted" : 5
+ â¦
+ }
+ },
+ âdiskâ: {
+ "disk_total " : 1000000,
+ âdisk_free" : 50000,
+ ...
+ }
+ },
+ ...
+ }
+ },
+ ...
+ ]
+ }
+
+**Example: Using Partial Response to expand collection resource instances one level deep**
+
+ GET /api/v1/clusters/c1/hosts?fields=*
+
+ 200 OK
+ {
+ âhrefâ : âhttp://ambari.server/api/v1/clusters/c1/hosts/?fields=*â,
+ âitemsâ: [
+ {
+ âhrefâ : âhttp://ambari.server/api/v1/clusters/c1/hosts/host1â,
+ âHostsâ : {
+ âcluster_nameâ : âc1â,
+ âhost_nameâ : âhost1â
+ },
+ âmetricsâ: {
+ âprocessâ: {
+ "proc_total" : 1000,
+ "proc_run" : 1000
+ },
+ ...
+ },
+ âhost_componentsâ: [
+ {
+ âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/NAMENODEâ
+ âHostRolesâ : {
+ âcluster_nameâ : âc1â,
+ âcomponent_nameâ : âNAMENODEâ,
+ âhost_nameâ : âhost1â
+ }
+ },
+ {
+ âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/DATANODEâ
+ âHostRolesâ : {
+ âcluster_nameâ : âc1â,
+ âcomponent_nameâ : DATANODEâ,
+ âhost_nameâ : âhost1â
+ }
+ },
+ ...
+ },
+ ...
+ },
+ {
+ âhrefâ : âhttp://ambari.server/api/v1/clusters/c1/hosts/host2â,
+ âHostsâ : {
+ âcluster_nameâ : âc1â,
+ âhost_nameâ : âhost2â
+ },
+ âmetricsâ: {
+ âprocessâ: {
+ "proc_total" : 555,
+ "proc_run" : 55
+ },
+ ...
+ },
+ âhost_componentsâ: [
+ {
+ âhrefâ: ââ¦/api/v1/clusters/c1/hosts/host1/host_components/DATANODEâ
+ âHostRolesâ : {
+ âcluster_nameâ : âc1â,
+ âcomponent_nameâ : âDATANODEâ,
+ âhost_nameâ : âhost2â
+ }
+ },
+ ...
+ ],
+ ...
+ },
+ ...
+ ]
+ }
+
+### Additional Partial Response Examples
+
+**Example â For each cluster, get cluster name, all hostnameâs and all service names**
+
+ GET /api/v1/clusters?fields=Clusters/cluster_name,hosts/Hosts/host_name,services/ServiceInfo/service_name
+
+**Example - Get all hostnameâs for a given component**
+
+ GET /api/v1/clusters/c1/services/HDFS/components/DATANODE?fields=host_components/HostRoles/host_name
+
+**Example - Get all hostnameâs and component names for a given service**
+
+ GET /api/v1/clusters/c1/services/HDFS?fields=components/host_components/HostRoles/host_name,
+ components/host_components/HostRoles/component_name
+
+
Query Predicates
----
@@ -476,20 +747,43 @@ Operator functions behave like relationa
GET /api/v1/clusters/c1/hosts?Hosts/host_status=HEALTHY&Hosts/cpu_count>=2
-**Example â Get all hosts with less than 2 cpu or host status != HEALTHY**
-
GET /api/v1/clusters/c1/hosts?Hosts/cpu_count<2|Hosts/host_status!=HEALTHY
**Example â Get all ârhel6â hosts with less than 2 cpu or âcentos6â hosts with 3 or more cpu**
-
GET /api/v1/clusters/c1/hosts?Hosts/os_type=rhel6&Hosts/cpu_count<2|Hosts/os_type=centos6&Hosts/cpu_count>=3
**Example â Get all hosts where either state != âHEALTHYâ or last_heartbeat_time < 1360600135905 and rack_info=âdefault_rackâ**
GET /api/v1/clusters/c1/hosts?(Hosts/host_status!=HEALTHY|Hosts/last_heartbeat_time<1360600135905)
- &Hosts/rack_info=default_rack
**Example â Get hosts with host name of host1 or host2 or host3 using IN operator**
- GET /api/v1/clusters/c1/hosts?Hosts/host_name.in(host1,host2,host3)
**Example â Get and expand all HDFS components, which have at least 1 property in the âmetrics/jvmâ category (combines query and partial response syntax)**
GET /api/v1/clusters/c1/services/HDFS/components?!metrics/jvm.isEmpty()&fields=*
**Example â Update the state of all âINSTALLEDâ services to be âSTARTEDâ**
PUT /api/v1/clusters/c1/services?ServiceInfo/state=INSTALLED
+**Example â Get all hosts with less than 2 cpu or host status != HEALTHY**
+
+
+ GET /api/v1/clusters/c1/hosts?Hosts/cpu_count<2|Hosts/host_status!=HEALTHY
+
+**Example â Get all ârhel6â hosts with less than 2 cpu or âcentos6â hosts with 3 or more cpu**
+
+ GET /api/v1/clusters/c1/hosts?Hosts/os_type=rhel6&Hosts/cpu_count<2|Hosts/os_type=centos6&Hosts/cpu_count>=3
+
+**Example â Get all hosts where either state != âHEALTHYâ or last_heartbeat_time < 1360600135905 and rack_info=âdefault_rackâ**
+
+ GET /api/v1/clusters/c1/hosts?(Hosts/host_status!=HEALTHY|Hosts/last_heartbeat_time<1360600135905)
+ &Hosts/rack_info=default_rack
+
+**Example â Get hosts with host name of host1 or host2 or host3 using IN operator**
+
+ GET /api/v1/clusters/c1/hosts?Hosts/host_name.in(host1,host2,host3)
+
+**Example â Get and expand all HDFS components, which have at least 1 property in the âmetrics/jvmâ category (combines query and partial response syntax)**
+
+ GET /api/v1/clusters/c1/services/HDFS/components?!metrics/jvm.isEmpty()&fields=*
+
+**Example â Update the state of all âINSTALLEDâ services to be âSTARTEDâ**
+
+ PUT /api/v1/clusters/c1/services?ServiceInfo/state=INSTALLED
{
"ServiceInfo": {
"state" : "STARTEDâ
}
- }
-
Batch Requests
----
+ }
+
+Batch Requests
+----
Requests can be batched. This allows for multiple bodies to be specified as an array in a single request.
-**Example â Creating multiple hosts in a single request**
+**Example â Creating multiple hosts in a single request**
+
POST /api/v1/clusters/c1/hosts/
[
@@ -511,7 +805,11 @@ Requests can be batched. This allows fo
"host_name" : "host3"
}
}
- ]
RequestInfo
----
+ ]
+
+
+RequestInfo
+----
RequestInfo allows the user to specify additional properties in the body of a request.
<table>
@@ -643,16 +941,82 @@ When the request resource returned in th
â¦
]
}
-
Temporal Metrics
+
+
+Temporal Metrics
----
-Some metrics have values that are available across a range in time. To query a metric for a range of values, the following partial response syntax is used.
To get temporal data for a single property:
?fields=category/property[start-time,end-time,step]
To get temporal data for all properties in a category:
?fields=category[start-time,end-time,step]
start-time: Required field. The start time for the query in Unix epoch time format.
end-time: Optional field, defaults to now. The end time for the query in Unix epoch time format.
step: Optional field, defaults to the corresponding metrics systemâs default value. If provided, end-time must also be provided. The interval of time between returned data points specified in seconds. The larger the value provided, the fewer data points returned so this can be used to limit how much data is returned for the given time range. This is only used as a suggestion so the result interval may differ from the one specified.
The returned result is a list of data points over the specified time range. Each data point is a value / timestamp pair.
**Note**: It is important to understand that requesting large amounts of temporal data may result in severe performance degradation. **Always** request the minimal amount of information necessary. If large amounts of data are required, consider splitting the request up into multiple smaller requests.
-
**Example â Temporal Query for a single property using only start-time**
-
GET /api/v1/clusters/c1/hosts/host1?fields=metrics/jvm/gcCount[1360610225]
-
- 200 OK
{
âhrefâ : â¦/api/v1/clusters/c1/hosts/host1?fields=metrics/jvm/gcCount[1360610225]â,
...
âmetricsâ: [
{
âjvmâ: {
"gcCount" : [
[10, 1360610165],
[12, 1360610180],
[13, 1360610195],
[14, 1360610210],
[15, 1360610225]
]
}
}
]
}
**Example â Temporal Query for a category using start-time, end-time and step**
-
GET /api/v1/clusters/c1/hosts/host1?fields=metrics/jvm[1360610200,1360610500,100]
-
200 OK
{
âhrefâ : â¦/clusters/c1/hosts/host1?fields=metrics/jvm[1360610200,1360610500,100]â,
...
âmetricsâ: [
{
âjvmâ: {
"gcCount" : [
[10, 1360610200],
[12, 1360610300],
[13, 1360610400],
[14, 1360610500]
],
"gcTimeMillis" : [
[1000, 1360610200],
[2000, 1360610300],
[5000, 1360610400],
[9500, 1360610500]
],
...
}
}
]
}
+Some metrics have values that are available across a range in time. To query a metric for a range of values, the following partial response syntax is used.
+
+To get temporal data for a single property:
+?fields=category/property[start-time,end-time,step]
+
+To get temporal data for all properties in a category:
+?fields=category[start-time,end-time,step]
+
+start-time: Required field. The start time for the query in Unix epoch time format.
+end-time: Optional field, defaults to now. The end time for the query in Unix epoch time format.
+step: Optional field, defaults to the corresponding metrics systemâs default value. If provided, end-time must also be provided. The interval of time between returned data points specified in seconds. The larger the value provided, the fewer data points returned so this can be used to limit how much data is returned for the given time range. This is only used as a suggestion so the result interval may differ from the one specified.
+
+The returned result is a list of data points over the specified time range. Each data point is a value / timestamp pair.
+
+**Note**: It is important to understand that requesting large amounts of temporal data may result in severe performance degradation. **Always** request the minimal amount of information necessary. If large amounts of data are required, consider splitting the request up into multiple smaller requests.
+
+**Example â Temporal Query for a single property using only start-time**
+
+ GET /api/v1/clusters/c1/hosts/host1?fields=metrics/jvm/gcCount[1360610225]
+
+
+ 200 OK
+ {
+ âhrefâ : â¦/api/v1/clusters/c1/hosts/host1?fields=metrics/jvm/gcCount[1360610225]â,
+ ...
+ âmetricsâ: [
+ {
+ âjvmâ: {
+ "gcCount" : [
+ [10, 1360610165],
+ [12, 1360610180],
+ [13, 1360610195],
+ [14, 1360610210],
+ [15, 1360610225]
+ ]
+ }
+ }
+ ]
+ }
+
+**Example â Temporal Query for a category using start-time, end-time and step**
+
+ GET /api/v1/clusters/c1/hosts/host1?fields=metrics/jvm[1360610200,1360610500,100]
+
+ 200 OK
+ {
+ âhrefâ : â¦/clusters/c1/hosts/host1?fields=metrics/jvm[1360610200,1360610500,100]â,
+ ...
+ âmetricsâ: [
+ {
+ âjvmâ: {
+ "gcCount" : [
+ [10, 1360610200],
+ [12, 1360610300],
+ [13, 1360610400],
+ [14, 1360610500]
+ ],
+ "gcTimeMillis" : [
+ [1000, 1360610200],
+ [2000, 1360610300],
+ [5000, 1360610400],
+ [9500, 1360610500]
+ ],
+ ...
+ }
+ }
+ ]
+ }
+
+
+
HTTP Return Codes
----
@@ -695,7 +1059,19 @@ Errors
**Example errors responses**
- 404 Not Found
{
"status" : 404,
"message" : "The requested resource doesn't exist: Cluster not found, clusterName=someInvalidCluster"
}
-
400 Bad Request
{
"status" : 400,
"message" : "The properties [foo] specified in the request or predicate are not supported for the
- resource type Cluster."
}
+ 404 Not Found
+ {
+ "status" : 404,
+ "message" : "The requested resource doesn't exist: Cluster not found, clusterName=someInvalidCluster"
+ }
+
+
+
+ 400 Bad Request
+ {
+ "status" : 400,
+ "message" : "The properties [foo] specified in the request or predicate are not supported for the
+ resource type Cluster."
+ }
+