mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 17:28:26 -04:00
add docs for how to report performance metrics (#139197)
* add docs for how to report performance metrics * Update dev_docs/tutorials/adding_performance_metrics.mdx Co-authored-by: Alejandro Fernández Haro <afharo@gmail.com> * Update dev_docs/tutorials/adding_performance_metrics.mdx Co-authored-by: Alejandro Fernández Haro <afharo@gmail.com> * Update dev_docs/tutorials/adding_performance_metrics.mdx Co-authored-by: Alejandro Fernández Haro <afharo@gmail.com> * Update dev_docs/tutorials/adding_performance_metrics.mdx Co-authored-by: Alejandro Fernández Haro <afharo@gmail.com> * add dashboard loaded event example * add note/reminder for free field values Co-authored-by: Alejandro Fernández Haro <afharo@gmail.com> Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
This commit is contained in:
Baturalp Gurdin
GitHub
parent
a9ab0bf351
commit
ec7af1a00b
2 changed files with 87 additions and 0 deletions
84
dev_docs/tutorials/adding_performance_metrics.mdx
Normal file
84
dev_docs/tutorials/adding_performance_metrics.mdx
Normal file
|
|
@ -0,0 +1,84 @@
|
|||
---
|
||||
id: kibDevTutorialAddingPerformanceMetrics
|
||||
slug: /kibana-dev-docs/tutorial/adding_performance_metrics
|
||||
title: Adding Performance Metrics
|
||||
summary: Learn how to instrument your code and analyze performance
|
||||
date: 2022-07-07
|
||||
tags: ['kibana', 'onboarding', 'setup', 'performance', 'development', 'telemetry']
|
||||
---
|
||||
|
||||
Reporting performance events is as easy as shown below. However, it's highly suggested to follow guidelines for what to report in certain fields:
|
||||
|
||||
```typescript
|
||||
import { reportPerformanceMetricEvent } from '@kbn/ebt-tools';
|
||||
|
||||
reportPerformanceMetricEvent(analytics, {
|
||||
eventName: KIBANA_LOADED_EVENT,
|
||||
meta: {
|
||||
// fields that are searchable-as-keywords but not aggregateable
|
||||
kibana_version: this.coreContext.env.packageInfo.version,
|
||||
protocol : window.location.protocol,
|
||||
},
|
||||
duration: timing[LOAD_FIRST_NAV],
|
||||
key1 : LOAD_START,
|
||||
value1 : timing[LOAD_START],
|
||||
key2 : LOAD_BOOTSTRAP_START,
|
||||
value2 : timing[LOAD_BOOTSTRAP_START],
|
||||
key3 : LOAD_CORE_CREATED,
|
||||
value3 : timing[LOAD_CORE_CREATED],
|
||||
key4 : LOAD_SETUP_DONE,
|
||||
value4 : timing[LOAD_SETUP_DONE],
|
||||
key5 : LOAD_START_DONE,
|
||||
value5 : timing[LOAD_START_DONE],
|
||||
});
|
||||
|
||||
reportPerformanceMetricEvent(analytics, {
|
||||
eventName: "dashboard_loaded",
|
||||
meta: {
|
||||
// fields that are searchable-as-keywords but not aggregateable
|
||||
kibana_version: this.coreContext.env.packageInfo.version,
|
||||
protocol : window.location.protocol,
|
||||
},
|
||||
duration: 2265,
|
||||
key1 : "time_to_data",
|
||||
value1 : 1801,
|
||||
key2 : "num_of_panels",
|
||||
value2 : 7,
|
||||
});
|
||||
```
|
||||
|
||||
Normally reporting an event requires a registration of event type however since we want
|
||||
performance metrics to be uniform across all kibana we already summarized it with the structure above.
|
||||
We welcome all the feedback based on your usecases.
|
||||
|
||||
# Guidelines of What to report in Performance Metric Events
|
||||
|
||||
|
||||
In order to simplify the consumption of performance telemetry, we'd like to standardize the shape of events. This requires considering the following aspects:
|
||||
- `Performance` - amount and size of events being sent
|
||||
- `Discoverability` - how easy it is to find different events, dimensions and metrics
|
||||
- `Queriability` - we would like to have the ability to write complex queries on top of telemetry data; for example getting all dashboard load events that took over 10 seconds for dashboards that contain less than 5 panels.
|
||||
- `Flexibility` - Teams should be able to flexibly design their event structure without having to define custom mappings (except for edge cases). I.e. a team can decide that the first free field is always used for that page load.
|
||||
- `Ease of visualization` - it should be easy to visualize the data
|
||||
- `Index field explosion` - having too many field names in the index, damages the performance when visualizing the data.
|
||||
|
||||
And event schema is composed of fields which is designed for specific purposes:
|
||||
|
||||
- `Event name` We decided to report all metric events under a single event_type, so that we can avoid registering it multiple times. This requires us to add a special standard field for eventName.
|
||||
- `Standardized fields` (duration) these fields represent common values that might be reported for performance. This can include duration for time based reports, status, heapSize, memorySize, etc. Standardized fields will be mapped as is to the index, so they can be visualized.
|
||||
- `Free fields` (key1, value1, key2, value2, ..., key5, value5) A limited set of integer-numbered free key-value pairs that can be used to report additional use-case specific fields. Teams may use them to create their own internal sub-schema. For example, a team may choose to use key1 to always report the loading time of a certain component that is always present on the page. Free fields will be mapped, if present, to the index, so they can be visualized. If a free field becomes popular, it can be promoted to a standardized field, freeing up the free field for other use.
|
||||
- `Non-standard fields` (kibana_version, protocol ...) - additional fields may be added to an event by extending them to the `meta` object. However, those won't be automatically mapped to the index. Since the `meta` field is a Flattened Field, this means those fields will be searchable by default, but an additional field mapping would be required to visualize them.
|
||||
|
||||
**Note**: It's important to keep in mind `Free Field` values are integer otherwise they will be rounded.
|
||||
|
||||
Events should be meaningful and can have multiple sub metrics which will give specific information of certain action. For example
|
||||
page-load event 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 specific event e.g. page-load.
|
||||
|
||||
# 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).
|
||||
|
|
@ -103,6 +103,9 @@
|
|||
{
|
||||
"label": "Tutorials",
|
||||
"items": [
|
||||
{
|
||||
"id": "kibDevTutorialAddingPerformanceMetrics"
|
||||
},
|
||||
{
|
||||
"id": "kibDevTutorialSetupWindowsDevWSL"
|
||||
},
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue