1
0

get-snapshot.asciidoc 5.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199
  1. [role="xpack"]
  2. [testenv="platinum"]
  3. [[ml-get-snapshot]]
  4. === Get model snapshots API
  5. ++++
  6. <titleabbrev>Get model snapshots</titleabbrev>
  7. ++++
  8. Retrieves information about model snapshots.
  9. [[ml-get-snapshot-request]]
  10. ==== {api-request-title}
  11. `GET _ml/anomaly_detectors/<job_id>/model_snapshots` +
  12. `GET _ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>`
  13. [[ml-get-snapshot-prereqs]]
  14. ==== {api-prereq-title}
  15. * If the {es} {security-features} are enabled, you must have `monitor_ml`,
  16. `monitor`, `manage_ml`, or `manage` cluster privileges to use this API. See
  17. <<security-privileges>>.
  18. [[ml-get-snapshot-path-parms]]
  19. ==== {api-path-parms-title}
  20. `<job_id>`::
  21. (Required, string)
  22. include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
  23. `<snapshot_id>`::
  24. (Optional, string)
  25. include::{docdir}/ml/ml-shared.asciidoc[tag=snapshot-id]
  26. +
  27. --
  28. If you do not specify this optional parameter, the API returns information about
  29. all model snapshots.
  30. --
  31. [[ml-get-snapshot-request-body]]
  32. ==== {api-request-body-title}
  33. `desc`::
  34. (Optional, boolean) If true, the results are sorted in descending order.
  35. `end`::
  36. (Optional, date) Returns snapshots with timestamps earlier than this time.
  37. `from`::
  38. (Optional, integer) Skips the specified number of snapshots.
  39. `size`::
  40. (Optional, integer) Specifies the maximum number of snapshots to obtain.
  41. `sort`::
  42. (Optional, string) Specifies the sort field for the requested snapshots. By
  43. default, the snapshots are sorted by their timestamp.
  44. `start`::
  45. (Optional, string) Returns snapshots with timestamps after this time.
  46. [[ml-get-snapshot-results]]
  47. ==== {api-response-body-title}
  48. The API returns an array of model snapshot objects, which have the following
  49. properties:
  50. `description`::
  51. (string) An optional description of the job.
  52. `job_id`::
  53. (string) A numerical character string that uniquely identifies the job that
  54. the snapshot was created for.
  55. `latest_record_time_stamp`::
  56. (date) The timestamp of the latest processed record.
  57. `latest_result_time_stamp`::
  58. (date) The timestamp of the latest bucket result.
  59. `min_version`::
  60. (string) The minimum version required to be able to restore the model snapshot.
  61. `model_size_stats`::
  62. (object) Summary information describing the model.
  63. `model_size_stats`.`bucket_allocation_failures_count`:::
  64. (long) The number of buckets for which entities were not processed due to memory
  65. limit constraints.
  66. `model_size_stats`.`job_id`:::
  67. (string)
  68. include::{docdir}/ml/ml-shared.asciidoc[tag=job-id-anomaly-detection]
  69. `model_size_stats`.`log_time`:::
  70. (date) The timestamp that the `model_size_stats` were recorded, according to
  71. server-time.
  72. `model_size_stats`.`memory_status`:::
  73. (string) The status of the memory in relation to its `model_memory_limit`.
  74. Contains one of the following values.
  75. +
  76. --
  77. * `hard_limit`: The internal models require more space that the configured
  78. memory limit. Some incoming data could not be processed.
  79. * `ok`: The internal models stayed below the configured value.
  80. * `soft_limit`: The internal models require more than 60% of the configured
  81. memory limit and more aggressive pruning will be performed in order to try to
  82. reclaim space.
  83. --
  84. `model_size_stats`.`model_bytes`:::
  85. (long) An approximation of the memory resources required for this analysis.
  86. `model_size_stats`.`model_bytes_exceeded`:::
  87. (long) The number of bytes over the high limit for memory usage at the last allocation failure.
  88. `model_size_stats`.`model_bytes_memory_limit`:::
  89. (long) The upper limit for memory usage, checked on increasing values.
  90. `model_size_stats`.`result_type`:::
  91. (string) Internal. This value is always `model_size_stats`.
  92. `model_size_stats`.`timestamp`:::
  93. (date) The timestamp that the `model_size_stats` were recorded, according to the
  94. bucket timestamp of the data.
  95. `model_size_stats`.`total_by_field_count`:::
  96. (long) The number of _by_ field values analyzed. Note that these are counted
  97. separately for each detector and partition.
  98. `model_size_stats`.`total_over_field_count`:::
  99. (long) The number of _over_ field values analyzed. Note that these are counted
  100. separately for each detector and partition.
  101. `model_size_stats`.`total_partition_field_count`:::
  102. (long) The number of _partition_ field values analyzed.
  103. `retain`::
  104. (boolean)
  105. include::{docdir}/ml/ml-shared.asciidoc[tag=retain]
  106. `snapshot_id`::
  107. (string) A numerical character string that uniquely identifies the model
  108. snapshot. For example: "1491852978".
  109. `snapshot_doc_count`::
  110. (long) For internal use only.
  111. `timestamp`::
  112. (date) The creation timestamp for the snapshot.
  113. [[ml-get-snapshot-example]]
  114. ==== {api-examples-title}
  115. [source,console]
  116. --------------------------------------------------
  117. GET _ml/anomaly_detectors/high_sum_total_sales/model_snapshots
  118. {
  119. "start": "1575402236000"
  120. }
  121. --------------------------------------------------
  122. // TEST[skip:Kibana sample data]
  123. In this example, the API provides a single result:
  124. [source,js]
  125. ----
  126. {
  127. "count" : 1,
  128. "model_snapshots" : [
  129. {
  130. "job_id" : "high_sum_total_sales",
  131. "min_version" : "6.4.0",
  132. "timestamp" : 1575402237000,
  133. "description" : "State persisted due to job close at 2019-12-03T19:43:57+0000",
  134. "snapshot_id" : "1575402237",
  135. "snapshot_doc_count" : 1,
  136. "model_size_stats" : {
  137. "job_id" : "high_sum_total_sales",
  138. "result_type" : "model_size_stats",
  139. "model_bytes" : 1638816,
  140. "model_bytes_exceeded" : 0,
  141. "model_bytes_memory_limit" : 10485760,
  142. "total_by_field_count" : 3,
  143. "total_over_field_count" : 3320,
  144. "total_partition_field_count" : 2,
  145. "bucket_allocation_failures_count" : 0,
  146. "memory_status" : "ok",
  147. "log_time" : 1575402237000,
  148. "timestamp" : 1576965600000
  149. },
  150. "latest_record_time_stamp" : 1576971072000,
  151. "latest_result_time_stamp" : 1576965600000,
  152. "retain" : false
  153. }
  154. ]
  155. }
  156. ----