From ead45955c3f47da579414951bc6943f56a852a61 Mon Sep 17 00:00:00 2001 From: Katerina Date: Wed, 29 May 2024 10:09:52 +0300 Subject: [PATCH] Add documentation for `kibana:plugin_render_time` (#184206) ## Summary closes https://github.com/elastic/observability-dev/issues/3374 1. Added the section # Report `kibana:plugin_render_time` metric event. 2. The rest changes are just auto-format --------- Co-authored-by: Vignesh Shanmugam --- .../adding_custom_performance_metrics.mdx | 202 ++++++++++++++---- 1 file changed, 166 insertions(+), 36 deletions(-) diff --git a/dev_docs/tutorials/performance/adding_custom_performance_metrics.mdx b/dev_docs/tutorials/performance/adding_custom_performance_metrics.mdx index 042283bb77dba0..4db207ad4aecb3 100644 --- a/dev_docs/tutorials/performance/adding_custom_performance_metrics.mdx +++ b/dev_docs/tutorials/performance/adding_custom_performance_metrics.mdx @@ -8,10 +8,12 @@ tags: ['kibana', 'onboarding', 'setup', 'performance', 'development', 'telemetry --- # Build and track custom performance metrics + Having access to performance metrics allows us to better understand user experience across Kibana, identify issues and fix it. Custom metrics allows to monitor critical flows like server start, saved objects fetching or dashboard loading times. -## Instrument your code to report metric event. +## Instrument your code to report custom metric event. + We use event-based telemetry (EBT) to report client-side metrics as events. If you want to add a custom metric on server side, please notify the #kibana-core team in advance. @@ -28,7 +30,7 @@ Once we have the time measurement, we can use the `reportPerformanceMetricEvent` ```typescript reportPerformanceMetricEvent(analytics, { - eventName: APP_ACTION, + eventName: APP_ACTION, duration: actionDuration, }); ``` @@ -42,7 +44,7 @@ Each document in the index has the following structure: ```typescript { - "_index": "backing-ebt-kibana-browser-performance-metrics-000001", // Performance metrics are stored at a dedicated simplified index (browser \ server). + "_index": "backing-ebt-kibana-browser-performance-metrics-000001", // Performance metrics are stored at a dedicated simplified index (browser \ server). "_source": { "timestamp": "2022-08-31T11:29:58.275Z" "event_type": "performance_metric", // All events share a common event type to simplify mapping @@ -67,11 +69,12 @@ Each document in the index has the following structure: ### Performance events with breakdowns and metadata -Lets assume we are interested in benchmarking the performance of a more complex event `COMPLEX_APP_ACTION`, that is made up of two steps: - - `INSPECT_DATA` measures the time it takes to retrieve a user's profile and check if there is a cached version of their data. - - If the cached data is fresh it proceeds with a flow `use-local-data` - - If data needs to be refreshed, it proceeds with a flow `load-data-from-api`. - - `PROCESS_DATA` loads and processes the data depending on the flow chosen in the previous step. +Lets assume we are interested in benchmarking the performance of a more complex event `COMPLEX_APP_ACTION`, that is made up of two steps: + +- `INSPECT_DATA` measures the time it takes to retrieve a user's profile and check if there is a cached version of their data. + - If the cached data is fresh it proceeds with a flow `use-local-data` + - If data needs to be refreshed, it proceeds with a flow `load-data-from-api`. +- `PROCESS_DATA` loads and processes the data depending on the flow chosen in the previous step. We could utilize the additional options supported by the `reportPerformanceMetricEvent` API: @@ -79,14 +82,14 @@ We could utilize the additional options supported by the `reportPerformanceMetri import { reportPerformanceMetricEvent } from '@kbn/ebt-tools'; reportPerformanceMetricEvent(analytics, { - eventName: COMPLEX_APP_ACTION, - duration, // Total duration in milliseconds - key1 : INSPECT_DATA, // Claiming free key1 to be used for INSPECT_DATA - value1 : durationOfStepA, // Total duration of step INSPECT_DATA in milliseconds - key2 : PROCESS_DATA, // Claiming free key2 to be used for PROCESS_DATA - value2 : durationOfStepB, // Total duration of step PROCESS_DATA in milliseconds + eventName: COMPLEX_APP_ACTION, + duration, // Total duration in milliseconds + key1: INSPECT_DATA, // Claiming free key1 to be used for INSPECT_DATA + value1: durationOfStepA, // Total duration of step INSPECT_DATA in milliseconds + key2: PROCESS_DATA, // Claiming free key2 to be used for PROCESS_DATA + value2: durationOfStepB, // Total duration of step PROCESS_DATA in milliseconds meta: { - dataSource: 'flow2', // Providing event specific context. This can be useful to create meaningful aggregations. + dataSource: 'flow2', // Providing event specific context. This can be useful to create meaningful aggregations. }, }); ``` @@ -95,7 +98,7 @@ This event will be indexed with the following structure: ```typescript { - "_index": "backing-ebt-kibana-browser-performance-metrics-000001", // Performance metrics are stored in a dedicated simplified index (browser \ server). + "_index": "backing-ebt-kibana-browser-performance-metrics-000001", // Performance metrics are stored in a dedicated simplified index (browser \ server). "_source": { "timestamp": "2022-08-31T11:29:58.275Z" "event_type": "performance_metric", // All events share a common event type to simplify mapping @@ -106,8 +109,8 @@ This event will be indexed with the following structure: "key2": PROCESS_DATA, // The key name of PROCESS_DATA "value2": 520, // The duration of step PROCESS_DATA "meta": { - "dataSource": 'load-data-from-api', - }, + "dataSource": 'load-data-from-api', + }, "context": { // Context holds information identifying the deployment, version, application and page that generated the event "version": "8.5.0-SNAPSHOT", "cluster_name": "job-ftr_configs_2-cluster-ftr", @@ -127,52 +130,54 @@ This event will be indexed with the following structure: ``` The performance metrics API supports **5 numbered free fields** that can be used to report numeric metrics that you intend to analyze. -Note that they can be used for any type of numeric information you may want to report and use to create your own flexible schema, +Note that they can be used for any type of numeric information you may want to report and use to create your own flexible schema, without having to add custom mappings. If you want to provide event specific context, you can add properties to the `meta` field. -The `meta` object is stored as a [flattened field](https://www.elastic.co/guide/en/elasticsearch/reference/current/flattened.html) hence +The `meta` object is stored as a [flattened field](https://www.elastic.co/guide/en/elasticsearch/reference/current/flattened.html) hence it's searchable and can be used to further breakdown event metrics. **Note**: It's important to keep in mind `free field` values are integers and floating point values will be rounded. ### How to choose and measure events -Events should be meaningful and can have multiple sub metrics which will give specific information of certain actions. For example -page-load events can be composed of render time, data load time during the page-load and so on. It's important to understand these -events will have meaning for performance investigations and that can be used in visualizations, aggregations. Considering this, -creating an event for cpuUsage does not bring any value because it doesn't bring any context with itself and reporting multiple of these +Events should be meaningful and can have multiple sub metrics which will give specific information of certain actions. For example +page-load events can be composed of render time, data load time during the page-load and so on. It's important to understand these +events will have meaning for performance investigations and that can be used in visualizations, aggregations. Considering this, +creating an event for cpuUsage does not bring any value because it doesn't bring any context with itself and reporting multiple of these events in different places of code will have so much variability during performance analysis of your code. However it can be nice attribute -to follow if it's important for you to look inside of a specific event e.g. `page-load`. +to follow if it's important for you to look inside of a specific event e.g. `page-load`. - **Make sure that the event is clearly defined and consistent** (i.e. same code flow is executed each time). Consider the start point and endpoint of the measurement and what happens between those points. For example: a `app-data-load` event should not include the time it takes to render the data. - **Choose event names wisely**. - Try to balance event names specificity. Calling an event `load` is too generic, calling an event `tsvb-data-load` is too specific (instead the visualization + Try to balance event names specificity. Calling an event `load` is too generic, calling an event `tsvb-data-load` is too specific (instead the visualization type can be specified in a `meta` field) -- **Distinguish between flows with event context**. +- **Distinguish between flows with event context**. If a function that loads data is called when an app loads, when the user changes filters and when the refresh button is clicked, you should distinguish between these flows by specifying a `meta` field. - **Avoid duplicate events**. - Make sure that measurement and reporting happens in a point of the code that is executed only once. + Make sure that measurement and reporting happens in a point of the code that is executed only once. For example, make sure that refresh events are reported only once per button click. - **Measure as close to the event as possible**. For example, if you're measuring the execution of a specific React Effect execution, place the measurement code inside the effect. - try to place the measurement start right before the navigation is performed and stop measuring as soon as all resources are loaded + try to place the measurement start right before the navigation is performed and stop measuring as soon as all resources are loaded - **Use the `window.performance` API**. - The [`performance.now()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now) API can be used to accurate way to receive timestamps - The [`performance.mark()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) API can be used to track performance without having to pollute the + The [`performance.now()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/now) API can be used to accurate way to receive timestamps + The [`performance.mark()`](https://developer.mozilla.org/en-US/docs/Web/API/Performance/mark) API can be used to track performance without having to pollute the code. -- **Keep performance in mind**. Reporting the performance of Kibana should never harm its own performance. +- **Keep performance in mind**. Reporting the performance of Kibana should never harm its own performance. Avoid sending events too frequently (`onMouseMove`) or adding serialized JSON objects (whole `SavedObjects`) into the meta object. ### Analyzing journey results + The telemetry data will be reported to the Telemetry Staging cluster alongside with execution context. Use the `context.labels.ciBuildName` label to filter down events to only those originating from performance runs and visualize the duration of events (or their breakdowns): - - Be sure to narrow your analysis down to performance events by specifying a filter `context.labels.ciBuildName: kibana-single-user-performance`. - Otherwise you might be looking at results originating from different hardware. - - You can look at the results of a specific journey by filtering on `context.labels.journeyName`. + +- Be sure to narrow your analysis down to performance events by specifying a filter `context.labels.ciBuildName: kibana-single-user-performance`. + Otherwise you might be looking at results originating from different hardware. +- You can look at the results of a specific journey by filtering on `context.labels.journeyName`. Please contact the #kibana-performance team if you need more help visualizing and tracking the results. @@ -181,7 +186,132 @@ Please contact the #kibana-performance team if you need more help visualizing an All users who are opted in to report telemetry will start reporting event based telemetry as well. The data is available to be analyzed on the production telemetry cluster. +# Report `kibana:plugin_render_time` metric event. + +The metric `kibana:plugin_render_time` measures the time from the start of navigation to the point at which the most meaningful component appears on the screen. + +This metric evaluates the loading performance of Kibana pages by measuring when the meaningful content becomes visible to users. The definition of meaningful content varies for different pages, necessitating custom instrumentation for each page to accurately measure this time. + +### How it works + +The `PerformanceContextProvider` utilizes the [browser's User Timing API](https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/User_timing) to track and analyze the performance of page transitions within the app. + +1. Upon each page change, a performance marker named `start::pageChange` is set. +2. Once the `onPageReady` function is called and the browser has finished rendering, another marker named `end::pageReady` is established. +3. The duration between these two markers is measured in **milliseconds** and reported as the `eventName: kibana:plugin_render_time` +4. Report the data using `reportPerformanceMetricEvent` API. + +### Instrument your code to report `kibana:plugin_render_time` metric event + +To instrument `kibana:plugin_render_time`, you need to use the `PerformanceContextProvider` at the root of your application after the `Router` and run the `onPageReady` function once the data for the most meaningful component is fetched. The meaningful data can be one or more elements or pieces of information that define the core content of the page. + +#### Code Example + +app.js + +``` +import React from 'react'; +import ReactDOM from 'react-dom'; +import { PerformanceContextProvider } from '@kbn/ebt-tools'; +import MyApp from './MyApp'; + +ReactDOM.render( + + + + , + + document.getElementById('root') +) + +``` + +``` +import React, { useEffect, useState } from 'react'; +import { usePerformanceContext } from '@kbn/ebt-tools'; + + +const MyApp = () => { + const { onPageReady } = usePerformanceContext(); + const [data, setData] = useState(null); + + useEffect(() => { + async function loadData() { + const fetchedData = await fetchData(); + if (fetchedData.status === 'success') { + setData(fetchedData); + + // Call onPageReady once the meaningful data has rendered and visible to the user + + onPageReady(); + } + } + + loadData(); + }, [onPageReady]); + + if (!data) { + return
Loading...
; + } + + return ( +
+

{data.title}

+

{data.content}

+
+ ); +}; + +export default MyApp; + + +``` + +This event will be indexed with the following structure: + +```typescript +{ + "_index": "backing-ebt-kibana-browser-performance-metrics-000001", // Performance metrics are stored in a dedicated simplified index (browser \ server). + "_source": { + "timestamp": "2022-08-31T11:29:58.275Z" + "event_type": "performance_metric", // All performance events share a common event type to simplify mapping + "eventName": 'kibana:plugin_render_time', // Event name as specified when reporting it + "duration": 736, // Event duration as specified when reporting it + "meta": { + "target": '/home', + }, + "context": { // Context holds information identifying the deployment, version, application and page that generated the event + "version": "8.5.0-SNAPSHOT", + "cluster_name": "elasticsearch", + "pageName": "application:home:app", + "applicationId": "home", + "page": "app", + "entityId": "61c58ad0-3dd3-11e8-b2b9-5d5dc1715159", + "branch": "main", + ... + }, + ... + }, +} +``` + +### Development environment + +The metric will be delivered to the [Telemetry Staging](https://telemetry-v2-staging.elastic.dev/) cluster, alongside with the event's context. +The data is updated periodically, so you might have to wait up to 30 minutes to see your data in the index. + +Once indexed, this metric will appear in `ebt-kibana` index. It is also mapped into an additional index, dedicated to performance metrics `ebt-kibana-browser-performance*`. + +[Dashboard]() + +### Production environment + +All users who are opted in to report telemetry will start reporting event based telemetry as well. +The data is available to be analyzed on the production telemetry cluster. + +[Dashboard]() + # Analytics Client Holds the public APIs to report events, enrich the events' context and set up the transport mechanisms. Please checkout package documentation to get more information about -[Analytics Client](https://github.com/elastic/kibana/blob/main/packages/analytics/README.md). \ No newline at end of file +[Analytics Client](https://github.com/elastic/kibana/blob/main/packages/analytics/README.md).