From 86dab0835488f8e53176042a6c253dccd282625e Mon Sep 17 00:00:00 2001 From: Wing <69376949+wingwong-knh@users.noreply.github.com> Date: Sat, 15 May 2021 16:04:31 +0800 Subject: [PATCH] Refine protocols (#6949) --- docs/en/protocols/Trace-Data-Protocol-v3.md | 38 ++++++++++----------- docs/en/protocols/query-protocol.md | 34 +++++++++--------- 2 files changed, 36 insertions(+), 36 deletions(-) diff --git a/docs/en/protocols/Trace-Data-Protocol-v3.md b/docs/en/protocols/Trace-Data-Protocol-v3.md index a85efcb08e..3fe886f2cc 100644 --- a/docs/en/protocols/Trace-Data-Protocol-v3.md +++ b/docs/en/protocols/Trace-Data-Protocol-v3.md @@ -7,38 +7,38 @@ also implemented in [HTTP 1.1](HTTP-API-Protocol.md) ### Report service instance status 1. Service Instance Properties -Service instance has more information than a name, once the agent wants to report this, use `ManagementService#reportInstanceProperties` service -providing a string-key/string-value pair list as the parameter. `language` of target instance is expected at least. +Service instance contains more information than just a name. Once the agent wants to report this, use `ManagementService#reportInstanceProperties` service +to provide a string-key/string-value pair list as the parameter. `language` of target instance is expected at least. 2. Service Ping -Service instance should keep alive with the backend. The agent should set a scheduler using `ManagementService#keepAlive` service in every minute. +Service instance should keep alive with the backend. The agent should set a scheduler using `ManagementService#keepAlive` service every minute. ### Send trace and metrics -After you have service id and service instance id, you could send traces and metrics. Now we +After you have the service ID and service instance ID ready, you could send traces and metrics. Now we have -1. `TraceSegmentReportService#collect` for skywalking native trace format -1. `JVMMetricReportService#collect` for skywalking native jvm format +1. `TraceSegmentReportService#collect` for the SkyWalking native trace format +1. `JVMMetricReportService#collect` for the SkyWalking native jvm format -For trace format, there are some notices -1. Segment is a concept in SkyWalking, it should include all span for per request in a single OS process, usually single thread based on language. -2. Span has 3 different groups. +For trace format, note that: +1. The segment is a unique concept in SkyWalking. It should include all spans for each request in a single OS process, which is usually a single language-based thread. +2. There are three types of spans. * EntrySpan -EntrySpan represents a service provider, also the endpoint of server side. As an APM system, we are targeting the -application servers. So almost all the services and MQ-consumer are EntrySpan(s). +EntrySpan represents a service provider, which is also the endpoint on the server end. As an APM system, SkyWalking targets the +application servers. Therefore, almost all the services and MQ-consumers are EntrySpans. * LocalSpan -LocalSpan represents a normal Java method, which don't relate with remote service, neither a MQ producer/consumer -nor a service(e.g. HTTP service) provider/consumer. +LocalSpan represents a typical Java method which is not related to remote services. It is neither a MQ producer/consumer +nor a provider/consumer of a service (e.g. HTTP service). * ExitSpan -ExitSpan represents a client of service or MQ-producer, as named as `LeafSpan` at early age of SkyWalking. -e.g. accessing DB by JDBC, reading Redis/Memcached are cataloged an ExitSpan. +ExitSpan represents a client of service or MQ-producer. It is known as the `LeafSpan` in the early stages of SkyWalking. +For example, accessing DB by JDBC, and reading Redis/Memcached are classified as ExitSpans. -3. Span across thread or process parent info is called Reference. Reference carries trace id, -segment id, span id, service name, service instance name, endpoint name and target address used at client side(not required in across thread) +3. Cross-thread/process span parent information is called "reference". Reference carries the trace ID, +segment ID, span ID, service name, service instance name, endpoint name, and target address used on the client end (note: this is not required in cross-thread operations) of this request in the parent. -Follow [Cross Process Propagation Headers Protocol v3](Skywalking-Cross-Process-Propagation-Headers-Protocol-v3.md) to get more details. +See [Cross Process Propagation Headers Protocol v3](Skywalking-Cross-Process-Propagation-Headers-Protocol-v3.md) for more details. -4. `Span#skipAnalysis` could be TRUE, if this span doesn't require backend analysis. +4. `Span#skipAnalysis` may be TRUE, if this span doesn't require backend analysis. diff --git a/docs/en/protocols/query-protocol.md b/docs/en/protocols/query-protocol.md index fdd4e177e2..fd2af4cc07 100644 --- a/docs/en/protocols/query-protocol.md +++ b/docs/en/protocols/query-protocol.md @@ -5,8 +5,8 @@ native visualization tool or 3rd party system, including Web UI, CLI or private Query protocol official repository, https://github.com/apache/skywalking-query-protocol. ### Metadata -Metadata includes the brief info of the whole under monitoring services and their instances, endpoints, etc. -Use multiple ways to query this meta data. +Metadata contains concise information on all services and their instances, endpoints, etc. under monitoring. +You may query the metadata in different ways. ```graphql extend type Query { getGlobalBrief(duration: Duration!): ClusterBrief @@ -35,7 +35,7 @@ extend type Query { ``` ### Topology -Show the topology and dependency graph of services or endpoints. Including direct relationship or global map. +The topology and dependency graphs of services and endpoints. Includes direct relationships or global maps. ```graphql extend type Query { @@ -51,13 +51,13 @@ extend type Query { ``` ### Metrics -Metrics query targets all the objects defined in [OAL script](../concepts-and-designs/oal.md). You could get the +Metrics query targets all objects defined in [OAL script](../concepts-and-designs/oal.md). You may obtain the metrics data in linear or thermodynamic matrix formats based on the aggregation functions in script. -3 types of metrics could be query -1. Single value. The type of most default metrics is single value, consider this as default. `getValues` and `getLinearIntValues` are suitable for this. -1. Multiple value. One metrics defined in OAL include multiple value calculations. Use `getMultipleLinearIntValues` to get all values. `percentile` is a typical multiple value func in OAL. -1. Heatmap value. Read [Heatmap in WIKI](https://en.wikipedia.org/wiki/Heat_map) for detail. `thermodynamic` is the only OAL func. Use `getThermodynamic` to get the values. +3 types of metrics can be queried: +1. Single value. Most default metrics are in single value. `getValues` and `getLinearIntValues` are suitable for this purpose. +1. Multiple value. A metric defined in OAL includes multiple value calculations. Use `getMultipleLinearIntValues` to obtain all values. `percentile` is a typical multiple value function in OAL. +1. Heatmap value. Read [Heatmap in WIKI](https://en.wikipedia.org/wiki/Heat_map) for details. `thermodynamic` is the only OAL function. Use `getThermodynamic` to get the values. ```graphql extend type Query { getValues(metric: BatchMetricConditions!, duration: Duration!): IntValues @@ -74,10 +74,10 @@ extend type Query { Metrics are defined in the `config/oal/*.oal` files. ### Aggregation -Aggregation query means the metrics data need a secondary aggregation in query stage, which makes the query -interfaces have some different arguments. Such as, `TopN` list of services is a very typical aggregation query, -metrics stream aggregation just calculates the metrics values of each service, but the expected list needs ordering metrics data -by the values. +Aggregation query means that the metrics data need a secondary aggregation at query stage, which causes the query +interfaces to have some different arguments. A typical example of aggregation query is the `TopN` list of services. +Metrics stream aggregation simply calculates the metrics values of each service, but the expected list requires ordering metrics data +by their values. Aggregation query is for single value metrics only. @@ -95,16 +95,16 @@ extend type Query { ``` ### Others -The following query(s) are for specific features, including trace, alarm or profile. +The following queries are for specific features, including trace, alarm, and profile. 1. Trace. Query distributed traces by this. -1. Alarm. Through alarm query, you can have alarm trend and details. +1. Alarm. Through alarm query, you can find alarm trends and their details. -The actual query GraphQL scrips could be found inside `query-protocol` folder in [here](../../../oap-server/server-query-plugin/query-graphql-plugin/src/main/resources). +The actual query GraphQL scripts can be found in the `query-protocol` folder [here](../../../oap-server/server-query-plugin/query-graphql-plugin/src/main/resources). ## Condition ### Duration -Duration is a widely used parameter type as the APM data is time related. The explanations are as following. -Step is related the precision. +Duration is a widely used parameter type as the APM data is time-related. See the following for more details. +Step relates to precision. ```graphql # The Duration defines the start and end time for each query operation. # Fields: `start` and `end` -- GitLab