From 8dbfd678f1fdc7def1a91faa8282a28510ac5977 Mon Sep 17 00:00:00 2001 From: zhangwei Date: Fri, 24 Apr 2020 20:00:08 +0800 Subject: [PATCH 1/4] modification doc --- docs/en/guides/Plugin-test.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/guides/Plugin-test.md b/docs/en/guides/Plugin-test.md index f034f23b8aca..67273a1667eb 100644 --- a/docs/en/guides/Plugin-test.md +++ b/docs/en/guides/Plugin-test.md @@ -101,8 +101,8 @@ File Name | Descriptions | Field | description | --- | --- | type | Image type, options, `jvm` or `tomcat`. Required. -| entryService | The entrance endpoint(URL) for test case access. Required. -| healthCheck | The health check endpoint(URL) for test case access. Required. +| entryService | The entrance endpoint(URL) for test case access. Required. (Verb: GET) +| healthCheck | The health check endpoint(URL) for test case access. Required. (Verb: HEAD) | startScript | Path of start up script. Required in `type: jvm` only. | framework | Case name. | runningMode | Running mode whether with the optional plugin, options, `default`(default), `with_optional`, `with_bootstrap` From 68beb692110e2ff61d29279fd24a3851de27aea8 Mon Sep 17 00:00:00 2001 From: zhangwei Date: Fri, 24 Apr 2020 22:08:37 +0800 Subject: [PATCH 2/4] modification doc --- docs/en/guides/Plugin-test.md | 113 +++++++++------------------------- 1 file changed, 29 insertions(+), 84 deletions(-) diff --git a/docs/en/guides/Plugin-test.md b/docs/en/guides/Plugin-test.md index 67273a1667eb..8f1d9ee029d0 100644 --- a/docs/en/guides/Plugin-test.md +++ b/docs/en/guides/Plugin-test.md @@ -3,7 +3,7 @@ Plugin test framework is designed for verifying the plugins' function and compatible status. As there are dozens of plugins and hundreds of versions need to be verified, it is impossible to do manually. The test framework uses container based tech stack, requires a set of real services with agent installed, then the test mock -OAP backend is running to check the segments and register data sent from agents. +OAP backend is running to check the segments data sent from agents. Every plugin maintained in the main repo requires corresponding test cases, also matching the versions in the supported list doc. @@ -90,7 +90,7 @@ The following files are required in every test case. File Name | Descriptions ---|--- `configuration.yml` | Declare the basic case inform, including, case name, entrance endpoints, mode, dependencies. -`expectedData.yaml` | Describe the expected Segment(s), including two major parts, (1) Register metadata (2) Segments +`expectedData.yaml` | Describe the expected segmentItems. `support-version.list` | List the target versions for this case `startup.sh` |`JVM-container` only, don't need this when use`Tomcat-container` @@ -101,8 +101,8 @@ File Name | Descriptions | Field | description | --- | --- | type | Image type, options, `jvm` or `tomcat`. Required. -| entryService | The entrance endpoint(URL) for test case access. Required. (Verb: GET) -| healthCheck | The health check endpoint(URL) for test case access. Required. (Verb: HEAD) +| entryService | The entrance endpoint(URL) for test case access. Required. (HTTP Method: GET) +| healthCheck | The health check endpoint(URL) for test case access. Required. (HTTP Method: HEAD) | startScript | Path of start up script. Required in `type: jvm` only. | framework | Case name. | runningMode | Running mode whether with the optional plugin, options, `default`(default), `with_optional`, `with_bootstrap` @@ -210,33 +210,11 @@ as the version number, it will be changed in the test for every version. | `null` | Null or empty String | | `eq` | Equal(default) | - -**Register verify description format** -```yml -registryItems: - services: - - { SERVICE_NAME: SERVICE_ID(int) } - ... - instances: - - { SERVICE_CODE: INSTANCE_COUNT(int) } - ... - operationNames: - ... -``` - - -| Field | Description -| --- | --- -| services | The registered service codes. Normally, not 0 should be enough. -| instances | The number of service instances exists in this test case. -| operationNames | Since 7.1.0, there is no operation name register. Ignore this. - - **Segment verify description format** ```yml -segments: +segmentItems: - - serviceName: SERVICE_CODE(string) + serviceName: SERVICE_NAME(string) segmentSize: SEGMENT_SIZE(int) segments: - segmentId: SEGMENT_ID(string) @@ -247,7 +225,7 @@ segments: | Field | Description | --- | --- -| serviceName | Service code. +| serviceName | Service Name. | segmentSize | The number of segments is expected. | segmentId | trace ID. | spans | segment span list. Follow the next section to see how to describe every span. @@ -258,15 +236,13 @@ segments: ```yml operationName: OPERATION_NAME(string) - operationId: SPAN_ID(int) parentSpanId: PARENT_SPAN_ID(int) spanId: SPAN_ID(int) startTime: START_TIME(int) endTime: END_TIME(int) isError: IS_ERROR(string: true, false) spanLayer: SPAN_LAYER(string: DB, RPC_FRAMEWORK, HTTP, MQ, CACHE) - spanType: SPAN_TYPE(string: Exit, Entry, Local ) - componentName: COMPONENT_NAME(string) + spanType: SPAN_TYPE(string: Exit, Entry, Local) componentId: COMPONENT_ID(int) tags: - {key: TAG_KEY(string), value: TAG_VALUE(string)} @@ -275,51 +251,47 @@ segments: - {key: LOG_KEY(string), value: LOG_VALUE(string)} ... peer: PEER(string) - peerId: PEER_ID(int) refs: - { - parentSpanId: PARENT_SPAN_ID(int), + traceId: TRACE_ID(string), parentTraceSegmentId: PARENT_TRACE_SEGMENT_ID(string), - entryServiceInstanceId: ENTRY_SERVICE_INSTANCE_ID(int) - parentServiceInstanceId: PARENT_SERVICE_INSTANCE_ID(int), - networkAddress: NETWORK_ADDRESS(string), - networkAddressId: NETWORK_ADDRESS_ID(int), + parentSpanId: PARENT_SPAN_ID(int), + parentService: PARENT_SERVICE(string), + parentServiceInstance: PARENT_SERVICE_INSTANCE(string), parentEndpoint: PARENT_ENDPOINT_NAME(string), - parentEndpointId: PARENT_ENDPOINT_ID(int), - entryEndpoint: ENTRY_ENDPOINT_NAME(string), - entryServiceInstanceId: ENTRY_ENDPOINT_ID(int), + networkAddress: NETWORK_ADDRESS(string), + refType: REF_TYPE(string: CrossProcess, CrossThread) } ... ``` | Field | Description |--- |--- -| operationName | Span Operation Name -| operationId | Should be 0 for now +| operationName | Span Operation Name. | parentSpanId | Parent span id. **Notice**: The parent span id of the first span should be -1. | spanId | Span Id. **Notice**, start from 0. | startTime | Span start time. It is impossible to get the accurate time, not 0 should be enough. | endTime | Span finish time. It is impossible to get the accurate time, not 0 should be enough. | isError | Span status, true or false. -| componentName | Component name, should be null in most cases, use component id instead. | componentId | Component id for your plugin. | tags | Span tag list. **Notice**, Keep in the same order as the plugin coded. | logs | Span log list. **Notice**, Keep in the same order as the plugin coded. -| SpanLayer | Options, DB, RPC_FRAMEWORK, HTTP, MQ, CACHE -| SpanType | Span type, options, Exit, Entry or Local +| SpanLayer | Options, DB, RPC_FRAMEWORK, HTTP, MQ, CACHE. +| SpanType | Span type, options, Exit, Entry or Local. | peer | Remote network address, IP + port mostly. For exit span, this should be required. -| peerId | Not 0 for now. - -The verify description for SegmentRef, +The verify description for SegmentRef | Field | Description |---- |---- +| traceId | +| parentTraceSegmentId | Parent SegmentId, pointing to the segment id in the parent segment. | parentSpanId | Parent SpanID, pointing to the span id in the parent segment. -| entryServiceInstanceId/parentServiceInstanceId | Not 0 should be enough -| networkAddress/networkAddressId | The peer value of parent exit span. `networkAddressId` should be 0, as the mock tool doesn't do register for real. -| parentEndpoint/parentEndpointId | The endpoint of parent/downstream service. Usually set `parentEndpoint` as literal string name, unless there is no parent endpoint, set `parentEndpointId` as -1. -| entryEndpoint/entryServiceInstanceId | The endpoint of first service in the distributed chain. Usually set `entryEndpoint` as literal string name, unless there is no endpoint at the entry service, set `entryServiceInstanceId` as -1. +| parentService | The service of parent/downstream service name. +| parentServiceInstance | The instance of parent/downstream service instance name. +| parentEndpoint | The endpoint of parent/downstream service. +| networkAddress | The peer value of parent exit span. +| refType | Ref type, options, CrossProcess or CrossThread . ### startup.sh @@ -407,7 +379,7 @@ and don't include the segments of heartbeat service in the expected segment data ### The example Process of Writing Expected Data -Expected data file, `expectedData.yaml`, includes `RegistryItems` and `SegmentIntems`. +Expected data file, `expectedData.yaml`, include `SegmentIntems`. We are using the HttpClient plugin to show how to write the expected data. @@ -437,24 +409,6 @@ There are two key points of testing | | | + + + ``` - -#### RegistryItems - -HttpClient test case is running in Tomcat container, only one instance exists, so -1. instance number is 1 -1. applicationId is not 0 -1. Because we have two servlet mapping paths, so two operation names. No health check operation name here. - -```yml -registryItems: - services: - - {httpclient-case: nq 0} - instances: - - {httpclient-case: 1} - operationNames: - - httpclient-case: [/httpclient-case/case/httpclient,/httpclient-case/case/context-propagate] -``` - #### segmentItems By following the flow of HttpClient case, there should be two segments created. @@ -462,7 +416,7 @@ By following the flow of HttpClient case, there should be two segments created. 1. Segment represents the ContextPropagateServlet access. Let's name it as `SegmentB`. ```yml -segments: +segmentItems: - serviceName: httpclient-case segmentSize: ge 2 # Could have more than one health check segments, because, the dependency is not standby. ``` @@ -476,7 +430,6 @@ SegmentA span list should like following - segmentId: not null spans: - operationName: /httpclient-case/case/context-propagate - operationId: eq 0 parentSpanId: 0 spanId: 1 startTime: nq 0 @@ -484,16 +437,13 @@ SegmentA span list should like following isError: false spanLayer: Http spanType: Exit - componentName: null componentId: eq 2 tags: - {key: url, value: 'http://127.0.0.1:8080/httpclient-case/case/context-propagate'} - {key: http.method, value: GET} logs: [] - peer: null - peerId: eq 0 + peer: 127.0.0.1:8080 - operationName: /httpclient-case/case/httpclient - operationId: eq 0 parentSpanId: -1 spanId: 0 startTime: nq 0 @@ -501,14 +451,12 @@ SegmentA span list should like following spanLayer: Http isError: false spanType: Entry - componentName: null componentId: 1 tags: - {key: url, value: 'http://localhost:{SERVER_OUTPUT_PORT}/httpclient-case/case/httpclient'} - {key: http.method, value: GET} logs: [] peer: null - peerId: eq 0 ``` SegmentB should only have one Tomcat entry span, but includes the Ref pointing to SegmentA. @@ -519,7 +467,6 @@ SegmentB span list should like following spans: - operationName: /httpclient-case/case/context-propagate - operationId: eq 0 parentSpanId: -1 spanId: 0 tags: @@ -531,12 +478,10 @@ SegmentB span list should like following spanLayer: Http isError: false spanType: Entry - componentName: null componentId: 1 peer: null - peerId: eq 0 refs: - - {parentSpanId: 1, parentTraceSegmentId: "${httpclient-case[0]}", entryServiceName: "/httpclient-case/case/httpclient", networkAddress: "127.0.0.1:8080",parentServiceName: "/httpclient-case/case/httpclient",entryApplicationInstanceId: nq 0 } + - {parentEndpoint: /httpclient-case/case/httpclient, networkAddress: 'localhost:8080', refType: CrossProcess, parentSpanId: 1, parentTraceSegmentId: not null, parentServiceInstance: not null, parentService: not null, traceId: not null} ``` ## Local Test and Pull Request To The Upstream From 419554b2532ab598394ebee0b2ab92cde7ee0e3d Mon Sep 17 00:00:00 2001 From: Brandon Fergerson Date: Sat, 25 Apr 2020 00:57:10 -0400 Subject: [PATCH 3/4] Update docs/en/guides/Plugin-test.md --- docs/en/guides/Plugin-test.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/guides/Plugin-test.md b/docs/en/guides/Plugin-test.md index 8f1d9ee029d0..9ad7d328faaf 100644 --- a/docs/en/guides/Plugin-test.md +++ b/docs/en/guides/Plugin-test.md @@ -291,7 +291,7 @@ The verify description for SegmentRef | parentServiceInstance | The instance of parent/downstream service instance name. | parentEndpoint | The endpoint of parent/downstream service. | networkAddress | The peer value of parent exit span. -| refType | Ref type, options, CrossProcess or CrossThread . +| refType | Ref type, options, CrossProcess or CrossThread. ### startup.sh From 5b2b5980cdc8d0b2b0c7724a7482b5b1fab0cd0e Mon Sep 17 00:00:00 2001 From: Brandon Fergerson Date: Sat, 25 Apr 2020 00:58:29 -0400 Subject: [PATCH 4/4] Update docs/en/guides/Plugin-test.md --- docs/en/guides/Plugin-test.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/guides/Plugin-test.md b/docs/en/guides/Plugin-test.md index 9ad7d328faaf..efd3687af67f 100644 --- a/docs/en/guides/Plugin-test.md +++ b/docs/en/guides/Plugin-test.md @@ -379,7 +379,7 @@ and don't include the segments of heartbeat service in the expected segment data ### The example Process of Writing Expected Data -Expected data file, `expectedData.yaml`, include `SegmentIntems`. +Expected data file, `expectedData.yaml`, include `SegmentItems`. We are using the HttpClient plugin to show how to write the expected data.