revert-snapshot.asciidoc 4.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127
  1. [role="xpack"]
  2. [[ml-revert-snapshot]]
  3. === Revert Model Snapshots API
  4. ++++
  5. <titleabbrev>Revert Model Snapshots</titleabbrev>
  6. ++++
  7. Reverts to a specific snapshot.
  8. ==== Request
  9. `POST _xpack/ml/anomaly_detectors/<job_id>/model_snapshots/<snapshot_id>/_revert`
  10. ==== Description
  11. The {ml} feature in {xpack} reacts quickly to anomalous input, learning new
  12. behaviors in data. Highly anomalous input increases the variance in the models
  13. whilst the system learns whether this is a new step-change in behavior or a
  14. one-off event. In the case where this anomalous input is known to be a one-off,
  15. then it might be appropriate to reset the model state to a time before this
  16. event. For example, you might consider reverting to a saved snapshot after Black
  17. Friday or a critical system failure.
  18. ////
  19. To revert to a saved snapshot, you must follow this sequence:
  20. . Close the job
  21. . Revert to a snapshot
  22. . Open the job
  23. . Send new data to the job
  24. When reverting to a snapshot, there is a choice to make about whether or not
  25. you want to keep the results that were created between the time of the snapshot
  26. and the current time. In the case of Black Friday for instance, you might want
  27. to keep the results and carry on processing data from the current time,
  28. though without the models learning the one-off behavior and compensating for it.
  29. However, say in the event of a critical system failure and you decide to reset
  30. and models to a previous known good state and process data from that time,
  31. it makes sense to delete the intervening results for the known bad period and
  32. resend data from that earlier time.
  33. Any gaps in data since the snapshot time will be treated as nulls and not modeled.
  34. If there is a partial bucket at the end of the snapshot and/or at the beginning
  35. of the new input data, then this will be ignored and treated as a gap.
  36. For jobs with many entities, the model state may be very large.
  37. If a model state is several GB, this could take 10-20 mins to revert depending
  38. upon machine spec and resources. If this is the case, please ensure this time
  39. is planned for.
  40. Model size (in bytes) is available as part of the Job Resource Model Size Stats.
  41. ////
  42. IMPORTANT: Before you revert to a saved snapshot, you must close the job.
  43. ==== Path Parameters
  44. `job_id` (required)::
  45. (string) Identifier for the job
  46. `snapshot_id` (required)::
  47. (string) Identifier for the model snapshot
  48. ==== Request Body
  49. `delete_intervening_results`::
  50. (boolean) If true, deletes the results in the time period between the
  51. latest results and the time of the reverted snapshot. It also resets the
  52. model to accept records for this time period. The default value is false.
  53. NOTE: If you choose not to delete intervening results when reverting a snapshot,
  54. the job will not accept input data that is older than the current time.
  55. If you want to resend data, then delete the intervening results.
  56. ==== Authorization
  57. You must have `manage_ml`, or `manage` cluster privileges to use this API.
  58. For more information, see
  59. {xpack-ref}/security-privileges.html[Security Privileges].
  60. //<<privileges-list-cluster>>.
  61. ==== Examples
  62. The following example reverts to the `1491856080` snapshot for the
  63. `it_ops_new_kpi` job:
  64. [source,js]
  65. --------------------------------------------------
  66. POST
  67. _xpack/ml/anomaly_detectors/it_ops_new_kpi/model_snapshots/1491856080/_revert
  68. {
  69. "delete_intervening_results": true
  70. }
  71. --------------------------------------------------
  72. // CONSOLE
  73. // TEST[skip:todo]
  74. When the operation is complete, you receive the following results:
  75. [source,js]
  76. ----
  77. {
  78. "model": {
  79. "job_id": "it_ops_new_kpi",
  80. "min_version": "6.3.0",
  81. "timestamp": 1491856080000,
  82. "description": "State persisted due to job close at 2017-04-10T13:28:00-0700",
  83. "snapshot_id": "1491856080",
  84. "snapshot_doc_count": 1,
  85. "model_size_stats": {
  86. "job_id": "it_ops_new_kpi",
  87. "result_type": "model_size_stats",
  88. "model_bytes": 29518,
  89. "total_by_field_count": 3,
  90. "total_over_field_count": 0,
  91. "total_partition_field_count": 2,
  92. "bucket_allocation_failures_count": 0,
  93. "memory_status": "ok",
  94. "log_time": 1491856080000,
  95. "timestamp": 1455318000000
  96. },
  97. "latest_record_time_stamp": 1455318669000,
  98. "latest_result_time_stamp": 1455318000000,
  99. "retain": false
  100. }
  101. }
  102. ----