Author: tbeerbower
Date: Mon Jun 3 17:52:56 2013
New Revision: 1489079
URL: http://svn.apache.org/r1489079
Log:
AMBARI-2260 - Bad hosts query example in API docs
Modified:
incubator/ambari/branches/branch-1.4.0/ambari-server/docs/api/v1/clusters-cluster.md
incubator/ambari/branches/branch-1.4.0/ambari-server/docs/api/v1/index.md
Modified:
incubator/ambari/branches/branch-1.4.0/ambari-server/docs/api/v1/clusters-cluster.md
URL:
http://svn.apache.org/viewvc/incubator/ambari/branches/branch-1.4.0/ambari-server/docs/api/v1/clusters-cluster.md?rev=1489079&r1=1489078&r2=1489079&view=diff
==============================================================================
---
incubator/ambari/branches/branch-1.4.0/ambari-server/docs/api/v1/clusters-cluster.md
(original)
+++
incubator/ambari/branches/branch-1.4.0/ambari-server/docs/api/v1/clusters-cluster.md
Mon Jun 3 17:52:56 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/branches/branch-1.4.0/ambari-server/docs/api/v1/index.md
URL:
http://svn.apache.org/viewvc/incubator/ambari/branches/branch-1.4.0/ambari-server/docs/api/v1/index.md?rev=1489079&r1=1489078&r2=1489079&view=diff
==============================================================================
--- incubator/ambari/branches/branch-1.4.0/ambari-server/docs/api/v1/index.md
(original)
+++ incubator/ambari/branches/branch-1.4.0/ambari-server/docs/api/v1/index.md
Mon Jun 3 17:52:56 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."
+ }
+
