fix: adding documentation on the history retrieval for individual EC2 instances.

Author: kirillsc

.gitignore

@@ -12,7 +12,7 @@ requirements-dev.txt
 work/
 
 # Test autogenerated files
-tests/onaws/run_templates
+tests/onaws/run_templates*
 
 # Security and analysis reports
 *.sarif

tests/onaws/resource-history-capture.md

@@ -0,0 +1,59 @@
+# Resource History Capture
+
+
+## Why it exists
+
+The REST API tests capture AWS-side history for the backing resource (EC2Fleet, SpotFleet, or ASG) to:
+- Provide a exact event timeline for post-test analysis that preserve timestamp for every single EC2 provided.
+- Support consistent request time calculations in metrics tooling.
+
+## When it runs
+
+History capture is triggered by `_capture_history_if_enabled` in `tests/onaws/test_rest_api_onaws.py` when:
+- `CAPTURE_RESOURCE_HISTORY` is `True`.
+- The backing resource is not `RunInstances` (there is no fleet/ASG history for that path).
+
+## Provider-specific behavior
+
+### EC2Fleet Request and Spot Fleet Request
+
+There’s no special handling beyond the generic flow: it calls describe_fleet_history with StartTime = now - 1h, paginates by NextToken, then runs the general completeness check and (if needed) synthesizes missing instance “launched” records.
+
+### EC2Fleet Instant
+
+  Instant fleet does not provide history for individual instances. So history file is generated by manually by looking at the timestamps of individual EC2 instnces that were provisioned as part of the fleet request.
+
+  - Create a synthetic `fleetRequestChange` "submitted" event at `CreateTime`.
+  - Add `instanceChange` "launched" events using instance `LaunchTime`.
+
+### ASG
+
+  ASG does not have an equivalent of the fleet submition time, so we check the time when ASG was created by itself.
+
+```python
+response = asg_client.describe_auto_scaling_groups(
+    AutoScalingGroupNames=[resource_id]
+)
+groups = response.get("AutoScalingGroups", [])
+created_at: datetime | None = groups[0].get("CreatedTime") if groups else None
+```
+
+then we generate a synthetic event in the history file
+
+```json
+"history": [
+    {
+      "EventInformation": {
+        "EventSubType": "submitted"
+      },
+      "EventType": "fleetRequestChange",
+      "Timestamp": "2026-01-15 11:16:02.087000+00:00"
+    },
+```
+
+
+
+## Output
+
+- File: `{METRICS_DIR}/{test_name}_history.json`
+