Skip to content

Commit b788ec7

Browse files
lcawllcawl
committed
[DOCS] Adds cat datafeeds API (#52738)
1 parent be8d704 commit b788ec7

File tree

6 files changed

+222
-21
lines changed

6 files changed

+222
-21
lines changed

‎docs/reference/cat.asciidoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -231,6 +231,8 @@ include::cat/count.asciidoc[]
231231

232232
include::cat/dataframeanalytics.asciidoc[]
233233

234+
include::cat/datafeeds.asciidoc[]
235+
234236
include::cat/fielddata.asciidoc[]
235237

236238
include::cat/health.asciidoc[]

‎docs/reference/cat/datafeeds.asciidoc‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
[role="xpack"]
2+
[testenv="platinum"]
3+
[[cat-datafeeds]]
4+
=== cat {dfeeds} API
5+
++++
6+
<titleabbrev>cat {dfeeds}</titleabbrev>
7+
++++
8+
9+
Returns configuration and usage information about {dfeeds}.
10+
11+
[[cat-datafeeds-request]]
12+
==== {api-request-title}
13+
14+
`GET /_cat/ml/datafeeds/<feed_id>` +
15+
16+
`GET /_cat/ml/datafeeds`
17+
18+
[[cat-datafeeds-prereqs]]
19+
==== {api-prereq-title}
20+
21+
* If the {es} {security-features} are enabled, you must have `monitor_ml`,
22+
`monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
23+
<<security-privileges>> and {ml-docs}/setup.html[Set up {ml-features}].
24+
25+
////
26+
[[cat-datafeeds-desc]]
27+
==== {api-description-title}
28+
29+
TBD: This API returns a maximum of 10,000 {dfeeds}.
30+
////
31+
32+
[[cat-datafeeds-path-params]]
33+
==== {api-path-parms-title}
34+
35+
`<feed_id>`::
36+
(Optional, string)
37+
include::{docdir}/ml/ml-shared.asciidoc[tag=datafeed-id]
38+
39+
[[cat-datafeeds-query-params]]
40+
==== {api-query-parms-title}
41+
42+
`allow_no_datafeeds`::
43+
(Optional, boolean)
44+
include::{docdir}/ml/ml-shared.asciidoc[tag=allow-no-datafeeds]
45+
46+
include::{docdir}/rest-api/common-parms.asciidoc[tag=http-format]
47+
48+
include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-h]
49+
50+
include::{docdir}/rest-api/common-parms.asciidoc[tag=help]
51+
52+
include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-s]
53+
54+
include::{docdir}/rest-api/common-parms.asciidoc[tag=time]
55+
56+
include::{docdir}/rest-api/common-parms.asciidoc[tag=cat-v]
57+
58+
[[cat-datafeeds-results]]
59+
==== {api-response-body-title}
60+
61+
`assignment_explanation`::
62+
include::{docdir}/ml/ml-shared.asciidoc[tag=assignment-explanation]
63+
+
64+
To retrieve this information, specify the `ae` column in the `h` query parameter.
65+
66+
`bucket.count`::
67+
include::{docdir}/ml/ml-shared.asciidoc[tag=bucket-count]
68+
+
69+
To retrieve this information, specify the `bc` or `bucketCount` column in the
70+
`h` query parameter.
71+
72+
`id`::
73+
include::{docdir}/ml/ml-shared.asciidoc[tag=datafeed-id]
74+
+
75+
To retrieve this information, specify the `id` column in the `h` query parameter.
76+
77+
`node.address`::
78+
The network address of the node.
79+
+
80+
include::{docdir}/ml/ml-shared.asciidoc[tag=node]
81+
+
82+
To retrieve this information, specify the `na` or `nodeAddress` column in the
83+
`h` query parameter.
84+
85+
`node.ephemeral_id`::
86+
The ephemeral ID of the node.
87+
+
88+
include::{docdir}/ml/ml-shared.asciidoc[tag=node]
89+
+
90+
To retrieve this information, specify the `ne` or `nodeEphemeralId` column in
91+
the `h` query parameter.
92+
93+
`node.id`::
94+
The unique identifier of the node.
95+
+
96+
include::{docdir}/ml/ml-shared.asciidoc[tag=node]
97+
+
98+
To retrieve this information, specify the `ni` or `nodeId` column in the `h`
99+
query parameter.
100+
101+
`node.name`::
102+
The node name.
103+
+
104+
include::{docdir}/ml/ml-shared.asciidoc[tag=node]
105+
+
106+
To retrieve this information, specify the `nn` or `nodeName` column in the `h`
107+
query parameter.
108+
109+
`search.bucket_avg`::
110+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-bucket-avg]
111+
+
112+
To retrieve this information, specify the `sba` or `searchBucketAvg` column in
113+
the `h` query parameter.
114+
115+
`search.count`::
116+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-count]
117+
+
118+
To retrieve this information, specify the `sc` or `searchCount` column in the
119+
`h` query parameter.
120+
121+
`search.exp_avg_hour`::
122+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-exp-avg-hour]
123+
+
124+
To retrieve this information, specify the `seah` or `searchExpAvgHour` column in
125+
the `h` query parameter.
126+
127+
`search.time`::
128+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-time]
129+
+
130+
To retrieve this information, specify the `st` or `searchTime` column in the `h`
131+
query parameter.
132+
133+
`state`::
134+
include::{docdir}/ml/ml-shared.asciidoc[tag=state-datafeed]
135+
+
136+
To retrieve this information, specify the `s` column in the `h` query parameter.
137+
138+
[[cat-datafeeds-example]]
139+
==== {api-examples-title}
140+
141+
[source,console]
142+
--------------------------------------------------
143+
GET _cat/ml/datafeeds?v
144+
--------------------------------------------------
145+
// TEST[skip:kibana sample data]
146+
147+
[source,console-result]
148+
----
149+
id state bucket.count search.count
150+
datafeed-high_sum_total_sales stopped 743 7
151+
datafeed-low_request_rate stopped 1457 3
152+
datafeed-response_code_rates stopped 1460 18
153+
datafeed-url_scanning stopped 1460 18
154+
----
155+
// TESTRESPONSE[skip:kibana sample data]

‎docs/reference/ml/anomaly-detection/apis/get-datafeed-stats.asciidoc‎

Lines changed: 24 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -67,47 +67,52 @@ The API returns an array of {dfeed} count objects. All of these properties are
6767
informational; you cannot update their values.
6868

6969
`assignment_explanation`::
70-
(string) For started {dfeeds} only, contains messages relating to the selection
71-
of a node.
70+
(string)
71+
include::{docdir}/ml/ml-shared.asciidoc[tag=assignment-explanation]
7272

7373
`datafeed_id`::
7474
(string)
7575
include::{docdir}/ml/ml-shared.asciidoc[tag=datafeed-id]
7676

7777
`node`::
78-
(object) The node upon which the {dfeed} is started. The {dfeed} and job will be
79-
on the same node.
80-
`node`.`id`::: The unique identifier of the node. For example,
81-
`0-o0tOoRTwKFZifatTWKNw`.
78+
(object)
79+
include::{docdir}/ml/ml-shared.asciidoc[tag=node]
80+
`node`.`id`::: The unique identifier of the node. For example, "0-o0tOoRTwKFZifatTWKNw".
8281
`node`.`name`::: The node name. For example, `0-o0tOo`.
8382
`node`.`ephemeral_id`::: The node ephemeral ID.
8483
`node`.`transport_address`::: The host and port where transport HTTP connections
8584
are accepted. For example, `127.0.0.1:9300`.
8685
`node`.`attributes`::: For example, `{"ml.machine_memory": "17179869184"}`.
8786

8887
`state`::
89-
(string) The status of the {dfeed}, which can be one of the following values:
90-
+
91-
--
92-
* `started`::: The {dfeed} is actively receiving data.
93-
* `stopped`::: The {dfeed} is stopped and will not receive data until it is
94-
re-started.
95-
--
88+
(string)
89+
include::{docdir}/ml/ml-shared.asciidoc[tag=state-datafeed]
9690

9791
`timing_stats`::
9892
(object) An object that provides statistical information about timing aspect of
9993
this {dfeed}.
94+
10095
`timing_stats`.`average_search_time_per_bucket_ms`:::
101-
(double) Average of the {dfeed} search times in milliseconds.
96+
(double)
97+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-bucket-avg]
98+
10299
`timing_stats`.`bucket_count`:::
103-
(long) The number of buckets processed.
100+
(long)
101+
include::{docdir}/ml/ml-shared.asciidoc[tag=bucket-count]
102+
104103
`timing_stats`.`exponential_average_search_time_per_hour_ms`:::
105-
(double) Exponential moving average of the {dfeed} search times in milliseconds.
104+
(double)
105+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-exp-avg-hour]
106+
106107
`timing_stats`.`job_id`:::
107108
include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
108-
`timing_stats`.`search_count`::: Number of searches performed by this {dfeed}.
109-
`timing_stats`.`total_search_time_ms`::: Total time the {dfeed} spent searching
110-
in milliseconds.
109+
110+
`timing_stats`.`search_count`:::
111+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-count]
112+
113+
`timing_stats`.`total_search_time_ms`:::
114+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-time]
115+
111116

112117
[[ml-get-datafeed-stats-response-codes]]
113118
==== {api-response-codes-title}

‎docs/reference/ml/ml-shared.asciidoc‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -136,6 +136,10 @@ tag::analyzed-fields-includes[]
136136
An array of strings that defines the fields that will be included in the analysis.
137137
end::analyzed-fields-includes[]
138138

139+
tag::assignment-explanation[]
140+
For started {dfeeds} only, contains messages relating to the selection of a node.
141+
end::assignment-explanation[]
142+
139143
tag::assignment-explanation-dfanalytics[]
140144
Contains messages relating to the selection of a node.
141145
end::assignment-explanation-dfanalytics[]
@@ -153,6 +157,10 @@ so do not set the `background_persist_interval` value too low.
153157
--
154158
end::background-persist-interval[]
155159

160+
tag::bucket-count[]
161+
The number of buckets processed.
162+
end::bucket-count[]
163+
156164
tag::bucket-span[]
157165
The size of the interval that the analysis is aggregated into, typically between
158166
`5m` and `1h`. The default value is `5m`. If the {anomaly-job} uses a {dfeed}
@@ -901,6 +909,11 @@ improve diversity in the ensemble. Therefore, only override this if you are
901909
confident that the value you choose is appropriate for the data set.
902910
end::n-neighbors[]
903911

912+
tag::node[]
913+
For started {dfeeds} only, this information pertains to the node upon which the
914+
{dfeed} is started.
915+
end::node[]
916+
904917
tag::num-top-classes[]
905918
Defines the number of categories for which the predicted
906919
probabilities are reported. It must be non-negative. If it is greater than the
@@ -993,6 +1006,22 @@ tag::scroll-size[]
9931006
The `size` parameter that is used in {es} searches. The default value is `1000`.
9941007
end::scroll-size[]
9951008

1009+
tag::search-bucket-avg[]
1010+
The average search time per bucket, in milliseconds.
1011+
end::search-bucket-avg[]
1012+
1013+
tag::search-count[]
1014+
The number of searches run by the {dfeed}.
1015+
end::search-count[]
1016+
1017+
tag::search-exp-avg-hour[]
1018+
The exponential average search time per hour, in milliseconds.
1019+
end::search-exp-avg-hour[]
1020+
1021+
tag::search-time[]
1022+
The total time the {dfeed} spent searching, in milliseconds.
1023+
end::search-time[]
1024+
9961025
tag::size[]
9971026
Specifies the maximum number of {dfanalytics-jobs} to obtain. The default value
9981027
is `100`.
@@ -1039,6 +1068,16 @@ more information, see
10391068
https://en.wikipedia.org/wiki/Feature_scaling#Standardization_(Z-score_Normalization)[this wiki page about standardization].
10401069
end::standardization-enabled[]
10411070

1071+
tag::state-datafeed[]
1072+
The status of the {dfeed}, which can be one of the following values:
1073+
+
1074+
--
1075+
* `started`: The {dfeed} is actively receiving data.
1076+
* `stopped`: The {dfeed} is stopped and will not receive data until it is
1077+
re-started.
1078+
--
1079+
end::state-datafeed[]
1080+
10421081
tag::summary-count-field-name[]
10431082
If this property is specified, the data that is fed to the job is expected to be
10441083
pre-summarized. This property value is the name of the field that contains the

‎x-pack/plugin/ml/src/main/java/org/elasticsearch/xpack/ml/rest/cat/RestCatDatafeedsAction.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ protected Table getTableWithHeader(RestRequest request) {
9696
.build());
9797
table.addCell("search.bucket_avg",
9898
TableColumnAttributeBuilder.builder("the average search time per bucket (millisecond)", false)
99-
.setAliases("sba", "bucketTimeMin")
99+
.setAliases("sba", "searchBucketAvg")
100100
.build());
101101
table.addCell("search.exp_avg_hour",
102102
TableColumnAttributeBuilder.builder("the exponential average search time per hour (millisecond)", false)

‎x-pack/plugin/src/test/resources/rest-api-spec/api/cat.ml_datafeeds.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"cat.ml_datafeeds":{
33
"documentation":{
4-
"url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/ml-get-datafeed-stats.html"
4+
"url":"http://www.elastic.co/guide/en/elasticsearch/reference/current/cat-datafeeds.html"
55
},
66
"stability":"stable",
77
"url":{

0 commit comments

Comments
 (0)