Skip to content

Commit 42fbca7

Browse files
lcawllcawl
authored
[DOCS] Adds cat datafeeds API (#52738)
1 parent 587e12a commit 42fbca7

File tree

6 files changed

+220
-17
lines changed

6 files changed

+220
-17
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: 22 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -68,15 +68,16 @@ The API returns an array of {dfeed} count objects. All of these properties are
6868
informational; you cannot update their values.
6969

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

7374
`datafeed_id`::
7475
(string)
7576
include::{docdir}/ml/ml-shared.asciidoc[tag=datafeed-id]
7677

7778
`node`::
78-
(object) For started {dfeeds} only, the node upon which the {dfeed} is started.
79-
The {dfeed} and job will be on the same node.
79+
(object)
80+
include::{docdir}/ml/ml-shared.asciidoc[tag=node]
8081
`node`.`id`::: The unique identifier of the node. For example, "0-o0tOoRTwKFZifatTWKNw".
8182
`node`.`name`::: The node name. For example, `0-o0tOo`.
8283
`node`.`ephemeral_id`::: The node ephemeral ID.
@@ -85,27 +86,33 @@ accepted. For example, `127.0.0.1:9300`.
8586
`node`.`attributes`::: For example, `{"ml.machine_memory": "17179869184"}`.
8687

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

9692
`timing_stats`::
9793
(object) An object that provides statistical information about timing aspect of
9894
this {dfeed}.
95+
9996
`timing_stats`.`average_search_time_per_bucket_ms`:::
100-
(double) Average of the {dfeed} search times in milliseconds.
97+
(double)
98+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-bucket-avg]
99+
101100
`timing_stats`.`bucket_count`:::
102-
(long) The number of buckets processed.
101+
(long)
102+
include::{docdir}/ml/ml-shared.asciidoc[tag=bucket-count]
103+
103104
`timing_stats`.`exponential_average_search_time_per_hour_ms`:::
104-
(double) Exponential moving average of the {dfeed} search times in milliseconds.
105+
(double)
106+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-exp-avg-hour]
107+
105108
`timing_stats`.`job_id`:::
106109
include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
107-
`timing_stats`.`search_count`::: Number of searches performed by this {dfeed}.
108-
`timing_stats`.`total_search_time_ms`::: Total time the {dfeed} spent searching in milliseconds.
110+
111+
`timing_stats`.`search_count`:::
112+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-count]
113+
114+
`timing_stats`.`total_search_time_ms`:::
115+
include::{docdir}/ml/ml-shared.asciidoc[tag=search-time]
109116

110117

111118
[[ml-get-datafeed-stats-response-codes]]

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

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

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

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

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

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

1073+
tag::state-datafeed[]
1074+
The status of the {dfeed}, which can be one of the following values:
1075+
+
1076+
--
1077+
* `started`: The {dfeed} is actively receiving data.
1078+
* `stopped`: The {dfeed} is stopped and will not receive data until it is
1079+
re-started.
1080+
--
1081+
end::state-datafeed[]
1082+
10441083
tag::summary-count-field-name[]
10451084
If this property is specified, the data that is fed to the job is expected to be
10461085
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
@@ -92,7 +92,7 @@ protected Table getTableWithHeader(RestRequest request) {
9292
.build());
9393
table.addCell("search.bucket_avg",
9494
TableColumnAttributeBuilder.builder("the average search time per bucket (millisecond)", false)
95-
.setAliases("sba", "bucketTimeMin")
95+
.setAliases("sba", "searchBucketAvg")
9696
.build());
9797
table.addCell("search.exp_avg_hour",
9898
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)