From 70b1ec69de8688a7ffc7279676f7ebeae914f7dc Mon Sep 17 00:00:00 2001 From: Wing <69376949+wingwong-knh@users.noreply.github.com> Date: Fri, 3 Sep 2021 18:06:59 -0700 Subject: [PATCH] Refine README.md (#7649) --- docs/en/ui/README.md | 113 ++++++++++++++++++++----------------------- 1 file changed, 53 insertions(+), 60 deletions(-) diff --git a/docs/en/ui/README.md b/docs/en/ui/README.md index d677de3b2f..76437d640d 100644 --- a/docs/en/ui/README.md +++ b/docs/en/ui/README.md @@ -1,29 +1,28 @@ -# UI Introduction -SkyWalking official UI provides the default and powerful visualization capabilities for SkyWalking observing distributed -cluster. +# Introduction to UI +The SkyWalking official UI provides the default and powerful visualization capabilities for SkyWalking to observe distributed +clusters. -The latest introduction video could be found on the Youtube +Watch the latest introduction video on Youtube: [![RocketBot UI](https://img.youtube.com/vi/mfKaToAKl7k/0.jpg)](http://www.youtube.com/watch?v=mfKaToAKl7k) -SkyWalking dashboard includes the following part. +The SkyWalking dashboard includes these parts: -1. **Feature Tab Selector Zone**. The key features are list there. The more details will be introduced below. -1. **Reload Zone**. Control the reload mechanism, including reload periodically or manually. -1. **Time Selector Zone**. Control the timezone and time range. And a Chinese/English switch button here, default, the UI -uses the browser language setting. We also welcome to contribute more languages. +1. **Feature Tab Selector Zone**. The key features are listed there. More details will be introduced below. +1. **Reload Zone**. It controls the reload mechanism, including the option to reload periodically or manually. +1. **Time Selector Zone**. It controls the timezone and time range, and comes with a Chinese/English language switch button. By default, the UI +uses the language setting of the browser. We also welcome translation contributions to extend our reach into more languages. ## Dashboard -Dashboard provide metrics of service, service instance and endpoint. There are a few metrics terms you need to understand -* Throughput CPM , represents calls per minute. -* Apdex score, Read [Apdex in WIKI](https://en.wikipedia.org/wiki/Apdex) -* Response Time Percentile, including `p99`, `p95`, `p90`, `p75`, `p50`. Read [percentile in WIKI](https://en.wikipedia.org/wiki/Percentile) -* SLA, represents the successful rate. For HTTP, it means the rate of 200 response code. +The dashboard provides metrics of services, service instances, and endpoints. Here's a quick terminology guide on metrics: +* **Throughput CPM**: Represents calls per minute. +* **Apdex score**: See [Apdex on Wiki](https://en.wikipedia.org/wiki/Apdex). +* **Response Time Percentile**: Includes `p99`, `p95`, `p90`, `p75`, and `p50`. See [percentile on Wiki](https://en.wikipedia.org/wiki/Percentile). +* **SLA**: Represents the success rate. For HTTP, the response status code is default to 200. -Service, Instance and Dashboard selector could reload manually rather than reload the whole page. NOTICE, the **Reload Zone** -wouldn't reload these selectors. +The Service, Instance and Dashboard selectors can be reloaded manually, so it's not necessary to always reload the whole page. Note that the **Reload Zone** does not reload these selectors. @@ -31,13 +30,12 @@ Two default dashboards are provided to visualize the metrics of service and data -User could click the `lock` button left aside the `Service/Instance/Endpoint Reload` button to custom your own dashboard. +Click the `Lock` button on the left of the `Service/Instance/Endpoint Reload` button to customize your dashboard. ### Custom Dashboard -Users could customize the dashboard. The default dashboards are provided through the default templates located in -`/ui-initialized-templates` folders. +Users may customize their dashboards. The default dashboards are provided in the default templates located in the `/ui-initialized-templates` folders. -The template file must end with `.yml` or `.yaml` and follows this format. +The template file must end with `.yml` or `.yaml`. It follows this format: ```yaml templates: - name: template name # The unique name @@ -81,73 +79,68 @@ templates: disabled: false ``` -**NOTE**, UI initialized templates would only be initialized if there is no template in the storage has the same name. -Check the entity named as `ui_template` in your storage. +**NOTE**: UI initialized templates would only be initialized if no template in the storage has the same name. +Check the entity named `ui_template` in your storage. ## Topology -Topology map shows the relationship among the services and instances with metrics. +A topology map shows the relationship between services and instances with metrics. -* Topology shows the default global topology including all services. -* **Service Selector** provides 2 level selectors, service group list and service name list. The group name is separated from -the service name if it follows `::` format. Topology map is available for single group, single service, -or global(include all services). -* **Custom Group** provides the any sub topology capability of service group. -* **Service Deep Dive** opens when you click any service. The honeycomb could do metrics, trace and alarm query of the selected service. -* **Service Relationship Metrics** gives the metrics of service RPC interactions and instances of these two services. +Global topology is shown by default, which means that all services are included. +* **Service Selector** provides two-level selectors, service group lists, and service name lists. The group name is separated from +the service name if it follows the `::` format. Topology maps are available for single group, single service, +or global (where all services are included). +* **Custom Group** allows you to create sub-topologies for a service group. +* **Service Deep Dive** opens when you click on any service. The honeycomb could carry out metrics, trace, and alarm query of the selected service. +* **Service Relationship Metrics** provides the metrics of service RPC interactions and the instances of these two services. ## Trace Query -Trace query is a typical feature as SkyWalking provided distributed agents. +Since SkyWalking provides distributed agents, trace query is a key feature. -* **Trace Segment List** is not the trace list. Every trace has several segments belonging to different services. If -query by all services or by trace id, different segments with same trace id could be list there. -* **Span** is clickable, the detail of each span will pop up on the left side. -* **Trace Views** provides 3 typical and different usage views to visualize the trace. +* **Trace Segment List** is not the same as a trace list. Every trace has several segments belonging to different services. If you start a query by all services or by trace IDs, different segments with the same trace ID may be listed there. +* **Span** can be clicked. The details of each span will pop up on the left. +* **Trace Views** provides three typical and different usage views to visualize the trace. ## Profile -Profile is an interaction feature. It provides the method level performance diagnosis. +Profile is an interactive feature. It provides method-level performance diagnoses. -To start the profile analysis, user need to create the profile task +To start profile analysis, you need to create a profile task: 1. Select the specific service. -1. Set the endpoint name. This endpoint name typically is the operation name of the first span. Find this on the trace +1. Set the Endpoint Name. This endpoint name is typically the operation name of the first span. Find this on the trace segment list view. -1. Monitor time could start right now or from any given future time. -1. Monitor duration defines the observation time window to find the suitable request to do performance analysis. -Even the profile add a very limited performance impact to the target system, but it is still an additional load. This duration -make the impact controllable. -1. Min duration threshold provides a filter mechanism, if a request of the given endpoint response quickly, it wouldn't be -profiled. This could make sure, the profiled data is the expected one. -1. Max sampling count gives the max dataset of agent will collect. It helps to reduce the memory and network load. -1. One implicit condition, **in any moment, SkyWalking only accept one profile task for each service**. -1. Agent could have different settings to control or limit this feature, read document setup for more details. -1. Not all SkyWalking ecosystem agent supports this feature, java agent from 7.0.0 supports this in default. +1. Monitor Time could start right now or from any given future time. +1. Monitor Duration defines the observation time window to find the suitable request to conduct performance analysis. +Even though the profile has a very limited performance impact on the target system, it still amounts to an additional load. Setting this duration allows you to control the impact. +1. Min Duration Threshold provides a filter mechanism. If a request of the given endpoint responds quickly, it will not be profiled. This ensures that the profiled data is the expected one. +1. Max Sampling Count gives the maximum dataset to be collected by the agent. It helps reduce memory and network load. +1. An implicit condition is that **at any moment, SkyWalking only accepts one profile task for each service**. +1. Individual agents may have different settings to control or limit this feature. Read document setup for more details. +1. Not all SkyWalking ecosystem agents support this feature. Java agent from version 7.0.0 supports this by default. -Once the profile done, the profiled trace segments would show up. And you could request for analysis for any span. -Typically, we analysis spans having long self duration, if the span and its children both have long duration, you could choose -`include children` or `exclude childrend` to set the analysis boundaries. +Once the profile is done, the profiled trace segments would show up, and you could request to analyze any span. +Typically, we analyze spans with long duration. If a span and its children both have long duration, you could set the analysis boundaries by choosing to `Include Children` or `Exclude Children`. -After choose the right span, and click the `analysis` button, you will see the stack based analysis result. The slowest methods -have been highlighted. +Choose the appropriate span, and click `Analyze`. You will see the stack-based analysis results. The slowest methods are highlighted. ### Advanced features -1. Since 7.1.0, the profiled trace collects the HTTP request parameters for Tomcat and SpringMVC Controller automatically. +1. Since version 7.1.0, the profiled trace automatically collects the HTTP request parameters for Tomcat and SpringMVC Controller. ## Log -Since 8.3.0, SkyWalking provides log query for the browser monitoring. Use [Apache SkyWalking Client JS](https://github.com/apache/skywalking-client-js) -agent would collect metrics and error logs. -Since 8.5.0, SkyWalking supports collecting logs through our native agents and 3rd party agents(such as Fluentd, Filebeat). -Read [Log Analyzer Document](../setup/backend/log-analyzer.md) for more details. +Since version 8.3.0, SkyWalking has provided log query for browser monitoring. Use [Apache SkyWalking Client JS](https://github.com/apache/skywalking-client-js) agent to collect metrics and error logs. + +Since version 8.5.0, SkyWalking supports collecting logs through its native agents and third party agents (such as Fluentd and Filebeat). +See [Log Analyzer Document](../setup/backend/log-analyzer.md) for more details. ## Alarm -Alarm page lists all triggered alarm. Read the backend setup documentation to know how to set up the alarm rule or integrate -with 3rd party system. +The alarm page lists all triggered alarms. See backend setup documentation to learn how to set up alarm rules or integrate +with third party systems.