[9.0] Update TTFMP documentation for meta fields. (#221807) (#223317)

# Backport

This will backport the following commits from `main` to `9.0`:
- [Update TTFMP documentation for meta fields.
(#221807)](https://github.com/elastic/kibana/pull/221807)

<!--- Backport version: 9.6.6 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sorenlouv/backport)

<!--BACKPORT [{"author":{"name":"Abdul Wahab
Zahid","email":"awahab07@yahoo.com"},"sourceCommit":{"committedDate":"2025-06-10T22:14:05Z","message":"Update
TTFMP documentation for meta fields. (#221807)\n\nEnhances the
performance metrics documentation by explaining how\nto use the
`meta.description` field for contextualizing render time\nevents and how
to track subsequent page or section loads
using\n`onPageRefreshStart`.\n\n\n- Added a section describing the
default meaning of render time and how\nto provide a custom
`description` in the `meta` field of `onPageReady`\nfor more precise
event context.\n- Documented the use of `onPageRefreshStart` to
distinguish between\ninitial loads and subsequent refreshes, clarifying
that\n`meta.isInitialLoad` is set to `false` for refreshes and `true`
by\ndefault.\n- Included code examples and sample indexed event
structures for
both\nfeatures.","sha":"ca05a06f00e013a18198cb46ce051d64f0d3f4b1","branchLabelMapping":{"^v9.1.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["release_note:skip","v9.0.0","backport:prev-minor","v8.18.0","v9.1.0","v8.19.0"],"title":"Update
TTFMP documentation for meta
fields.","number":221807,"url":"https://github.com/elastic/kibana/pull/221807","mergeCommit":{"message":"Update
TTFMP documentation for meta fields. (#221807)\n\nEnhances the
performance metrics documentation by explaining how\nto use the
`meta.description` field for contextualizing render time\nevents and how
to track subsequent page or section loads
using\n`onPageRefreshStart`.\n\n\n- Added a section describing the
default meaning of render time and how\nto provide a custom
`description` in the `meta` field of `onPageReady`\nfor more precise
event context.\n- Documented the use of `onPageRefreshStart` to
distinguish between\ninitial loads and subsequent refreshes, clarifying
that\n`meta.isInitialLoad` is set to `false` for refreshes and `true`
by\ndefault.\n- Included code examples and sample indexed event
structures for
both\nfeatures.","sha":"ca05a06f00e013a18198cb46ce051d64f0d3f4b1"}},"sourceBranch":"main","suggestedTargetBranches":["9.0","8.18","8.19"],"targetPullRequestStates":[{"branch":"9.0","label":"v9.0.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"8.18","label":"v8.18.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"},{"branch":"main","label":"v9.1.0","branchLabelMappingKey":"^v9.1.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/221807","number":221807,"mergeCommit":{"message":"Update
TTFMP documentation for meta fields. (#221807)\n\nEnhances the
performance metrics documentation by explaining how\nto use the
`meta.description` field for contextualizing render time\nevents and how
to track subsequent page or section loads
using\n`onPageRefreshStart`.\n\n\n- Added a section describing the
default meaning of render time and how\nto provide a custom
`description` in the `meta` field of `onPageReady`\nfor more precise
event context.\n- Documented the use of `onPageRefreshStart` to
distinguish between\ninitial loads and subsequent refreshes, clarifying
that\n`meta.isInitialLoad` is set to `false` for refreshes and `true`
by\ndefault.\n- Included code examples and sample indexed event
structures for
both\nfeatures.","sha":"ca05a06f00e013a18198cb46ce051d64f0d3f4b1"}},{"branch":"8.19","label":"v8.19.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

Co-authored-by: Abdul Wahab Zahid <awahab07@yahoo.com>

dev_docs/tutorials/performance/adding_custom_performance_metrics.mdx

@@ -294,6 +294,64 @@ This event will be indexed with the following structure:
 }
 ```
 
+#### Add context to render time events
+
+To provide additional context about what duration means for a particular reported event, a `description` to the `meta` field of `onPageReady()` can be added.
+
+This helps analysts understand exactly what the measurement represents in your specific implementation.
+
+```typescript
+onPageReady({
+  meta: {
+    description: '[ttfmp_onboarding] The UI with onboarding categories is rendered'
+  }
+});
+```
+
+#### Tracking Refreshes or Subsequent Loads
+
+The `meta` field supports an `isInitialLoad` boolean flag, which indicates whether the performance event was triggered during the application's initial load or as a result of a subsequent user interaction. This helps distinguish between first page loads and subsequent refreshes as subsequent refreshes may be quite different in terms of performance compared to the initial load.
+
+By default, when you call `onPageReady()` without first calling `onPageRefreshStart()`, the event will be recorded with `isInitialLoad: true`, indicating it was the initial page load.
+
+To track subsequent refreshes (after initial load):
+
+1. Call `onPageRefreshStart()` when a refresh action begins
+2. Call `onPageReady()` when the refresh completes
+
+When this pattern is followed, the performance event will be recorded with `isInitialLoad: false`.
+
+###### Code example
+
+```typescript
+// When a user initiates a refresh action
+const handleRefresh = useCallback(() => {
+  onPageRefreshStart(); // Mark the start of refresh
+  fetchData().then(() => {
+    // Once data is loaded and UI is updated
+    onPageReady(); // This will record with isInitialLoad: false
+  });
+}, [onPageRefreshStart, onPageReady]);
+```
+
+This will be indexed as:
+
+```typescript
+{
+  "_index": "backing-ebt-kibana-browser-performance-metrics-000001",
+  "_source": {
+    "timestamp": "2024-08-13T11:29:58.275Z",
+    "event_type": "performance_metric",
+    "eventName": "kibana:plugin_render_time",
+    "duration": 736,
+    "meta": {
+      "is_initial_load": false  // Indicates this was a refresh, not initial load
+    },
+    ...
+  }
+}
+```
+
 #### Add time ranges
 
 The meta field supports telemetry on time ranges, providing calculated metrics for enhanced context. This includes: