diff --git a/docs/en/guides/Plugin-test.md b/docs/en/guides/Plugin-test.md index 7280da162e6f4b9014afd30730664d6a97989f68..166c6e980a9752907ac11f9047e08d3363439b5e 100644 --- a/docs/en/guides/Plugin-test.md +++ b/docs/en/guides/Plugin-test.md @@ -211,7 +211,7 @@ as the version number, it will be changed in the test for every version. | `null` | Null or empty String | | `eq` | Equal(default) | -**Segment verify description format** +**Expected Data Format Of The Segment** ```yml segmentItems: - @@ -231,7 +231,7 @@ segmentItems: | segmentId | trace ID. | spans | segment span list. Follow the next section to see how to describe every span. -**Span verify description format** +**Expected Data Format Of The Span** **Notice**: The order of span list should follow the order of the span finish time. @@ -294,6 +294,46 @@ The verify description for SegmentRef | networkAddress | The peer value of parent exit span. | refType | Ref type, options, CrossProcess or CrossThread. +**Expected Data Format Of The Meter Items** +```yml +meterItems: +- + serviceName: SERVICE_NAME(string) + meterSize: METER_SIZE(int) + meters: + - ... +``` + +| Field | Description +| --- | --- +| serviceName | Service Name. +| meterSize | The number of meters is expected. +| meters | meter list. Follow the next section to see how to describe every meter. + +**Expected Data Format Of The Meter** + +```yml + meterId: + name: NAME(string) + tags: + - {name: TAG_NAME(string), value: TAG_VALUE(string)} + singleValue: SINGLE_VALUE(double) + histogramBuckets: + - HISTOGRAM_BUCKET(double) + ... +``` + +The verify description for MeterId + +| Field | Description +|--- |--- +| name | meter name. +| tags | meter tags. +| tags.name | tag name. +| tags.value | tag value. +| singleValue | counter or gauge value. Using condition operate of the number to validate, such as `gt`, `ge`. If current meter is histogram, don't need to write this field. +| histogramBuckets | histogram bucket. The bucket list must be ordered. The tool assert at least one bucket of the histogram having nonzero count. If current meter is counter or gauge, don't need to write this field. + ### startup.sh This script provide a start point to JVM based service, most of them starts by a `java -jar`, with some variables. @@ -378,9 +418,9 @@ dependent services are database or cluster. Notice, because heartbeat service could be traced fully or partially, so, segmentSize in `expectedData.yaml` should use `ge` as the operator, and don't include the segments of heartbeat service in the expected segment data. -### The example Process of Writing Expected Data +### The example Process of Writing Tracing Expected Data -Expected data file, `expectedData.yaml`, include `SegmentItems`. +Expected data file, `expectedData.yaml`, include `SegmentItems` part. We are using the HttpClient plugin to show how to write the expected data. @@ -485,6 +525,80 @@ SegmentB span list should like following - {parentEndpoint: /httpclient-case/case/httpclient, networkAddress: 'localhost:8080', refType: CrossProcess, parentSpanId: 1, parentTraceSegmentId: not null, parentServiceInstance: not null, parentService: not null, traceId: not null} ``` +### The example Process of Writing Meter Expected Data + +Expected data file, `expectedData.yaml`, include `MeterItems` part. + +We are using the toolkit plugin to demonstrate how to write the expected data. When write the [meter plugin](Java-Plugin-Development-Guide.md#meter-plugin), the expected data file keeps the same. + +There is one key point of testing +1. Build a meter and operate it. + +Such as `Counter`: +```java +MeterFactory.counter("test_counter").tag("ck1", "cv1").build().increment(1d); +MeterFactory.histogram("test_histogram").tag("hk1", "hv1").steps(1d, 5d, 10d).build().addValue(2d); +``` + +``` ++-------------+ +------------------+ +| Plugin | | Agent core | +| | | | ++-----|-------+ +---------|--------+ + | | + | | + | Build or operate +-+ + +------------------------> |-| + | |-] + | |-| + | |-| + | |-| + | |-| + | <--------------------------| + | +-+ + | | + | | + | | + | | + + + +``` + +#### meterItems + +By following the flow of the toolkit case, there should be two meters created. +1. Meter `test_counter` created from `MeterFactory#counter`. Let's name it as `MeterA`. +1. Meter `test_histogram` created from `MeterFactory#histogram`. Let's name it as `MeterB`. + +```yml +meterItems: + - serviceName: toolkit-case + meterSize: 2 +``` + +They're showing two kinds of meter, MeterA has a single value, MeterB has a histogram value. + +MeterA should like following, `counter` and `gauge` use the same data format. +```yaml +- meterId: + name: test_counter + tags: + - {name: ck1, value: cv1} + singleValue: gt 0 +``` + +MeterB should like following. +```yaml +- meterId: + name: test_histogram + tags: + - {name: hk1, value: hv1} + histogramBuckets: + - 0.0 + - 1.0 + - 5.0 + - 10.0 +``` + ## Local Test and Pull Request To The Upstream First of all, the test case project could be compiled successfully, with right project structure and be able to deploy. diff --git a/test/plugin/agent-test-tools/pom.xml b/test/plugin/agent-test-tools/pom.xml index a9de22b04ee1b16fd08e0912e035f11170f8b473..d3c9e5e97146feb7787b8613a1d28f0167148634 100644 --- a/test/plugin/agent-test-tools/pom.xml +++ b/test/plugin/agent-test-tools/pom.xml @@ -35,7 +35,7 @@ pom - 46778565b1c4d25a55a07cd8f7c246d14de22322 + d75f7e1f593bd3816f6cd815482e355658adb8a0 ${project.basedir}/target/agent-test-tools https://github.com/apache/skywalking-agent-test-tool.git diff --git a/test/plugin/containers/jvm-container/src/main/docker/run.sh b/test/plugin/containers/jvm-container/src/main/docker/run.sh index 273fa4c0aa3cd4605658bd10bb91b7d71c158f70..03426b797fd09b4d477aacc9da8a617da3116bdf 100644 --- a/test/plugin/containers/jvm-container/src/main/docker/run.sh +++ b/test/plugin/containers/jvm-container/src/main/docker/run.sh @@ -80,6 +80,7 @@ export agent_opts=" -Dskywalking.agent.service_name=${SCENARIO_NAME} -Dskywalking.logging.dir=${LOGS_HOME} -Dskywalking.agent.authentication=test-token + -Dskywalking.meter.report_interval=1 -Xms256m -Xmx256m ${agent_opts}" exec /var/run/${SCENARIO_NAME}/${SCENARIO_START_SCRIPT} 1>${LOGS_HOME}/scenario.out & diff --git a/test/plugin/containers/tomcat-container/src/main/docker/catalina.sh b/test/plugin/containers/tomcat-container/src/main/docker/catalina.sh index 1d3e784685bd3506284d90ca813015386280f49b..188d15eba9ea4049feda1e7fe589de8e9f13f9df 100644 --- a/test/plugin/containers/tomcat-container/src/main/docker/catalina.sh +++ b/test/plugin/containers/tomcat-container/src/main/docker/catalina.sh @@ -117,6 +117,7 @@ if [ -f "${AGENT_FILE_PATH}/skywalking-agent.jar" ]; then -Dskywalking.collector.backend_service=localhost:19876 -Dskywalking.agent.service_name=${SCENARIO_NAME} -Dskywalking.agent.authentication=test-token + -Dskywalking.meter.report_interval=1 -Dskywalking.logging.dir=${LOGS_HOME} -Xms256m -Xmx256m -XX:PermSize=64M -XX:MaxPermSize=64" fi diff --git a/test/plugin/scenarios/apm-toolkit-trace-scenario/config/expectedData.yaml b/test/plugin/scenarios/apm-toolkit-trace-scenario/config/expectedData.yaml index 5bad99e9e3d0a16a3e67a9c6f3690638f8de7473..d56a438533e5b60d8052549d61521f852e82aa47 100644 --- a/test/plugin/scenarios/apm-toolkit-trace-scenario/config/expectedData.yaml +++ b/test/plugin/scenarios/apm-toolkit-trace-scenario/config/expectedData.yaml @@ -309,3 +309,27 @@ segmentItems: parentTraceSegmentId: not null, parentServiceInstance: not null, parentService: apm-toolkit-trace-scenario, traceId: not null} skipAnalysis: 'true' + +meterItems: +- serviceName: apm-toolkit-trace-scenario + meterSize: 3 + meters: + - meterId: + name: test_counter + tags: + - {name: ck1, value: cv1} + singleValue: gt 0 + - meterId: + name: test_gauge + tags: + - {name: gk1, value: gv1} + singleValue: gt 0 + - meterId: + name: test_histogram + tags: + - {name: hk1, value: hv1} + histogramBuckets: + - 0.0 + - 1.0 + - 5.0 + - 10.0 diff --git a/test/plugin/scenarios/apm-toolkit-trace-scenario/pom.xml b/test/plugin/scenarios/apm-toolkit-trace-scenario/pom.xml index b8ddd5954400cf84479217af6d91d99d5d798fd9..e14f23cce13078d4c17eef5e23fe029e0b63bafc 100644 --- a/test/plugin/scenarios/apm-toolkit-trace-scenario/pom.xml +++ b/test/plugin/scenarios/apm-toolkit-trace-scenario/pom.xml @@ -59,6 +59,11 @@ httpclient 4.3 + + org.apache.skywalking + apm-toolkit-meter + 8.2.0-SNAPSHOT + @@ -115,4 +120,12 @@ http://repo.spring.io/milestone + + + + apache-snapshot + Apache Snapshot + https://repository.apache.org/content/repositories/snapshots + + \ No newline at end of file diff --git a/test/plugin/scenarios/apm-toolkit-trace-scenario/src/main/java/test/org/apache/skywalking/apm/testcase/toolkit/controller/TestController.java b/test/plugin/scenarios/apm-toolkit-trace-scenario/src/main/java/test/org/apache/skywalking/apm/testcase/toolkit/controller/TestController.java index 1b22c7bd05c7615d1aae5f27b66b094273d2c967..6fdd3025dbbb2d2e1f4f1c7f66df433adf95c22c 100644 --- a/test/plugin/scenarios/apm-toolkit-trace-scenario/src/main/java/test/org/apache/skywalking/apm/testcase/toolkit/controller/TestController.java +++ b/test/plugin/scenarios/apm-toolkit-trace-scenario/src/main/java/test/org/apache/skywalking/apm/testcase/toolkit/controller/TestController.java @@ -18,19 +18,22 @@ package test.org.apache.skywalking.apm.testcase.toolkit.controller; -import java.io.IOException; import org.apache.http.HttpEntity; import org.apache.http.client.ResponseHandler; import org.apache.http.client.methods.HttpGet; import org.apache.http.impl.client.CloseableHttpClient; import org.apache.http.impl.client.HttpClients; import org.apache.http.util.EntityUtils; +import org.apache.skywalking.apm.toolkit.meter.MeterFactory; import org.apache.skywalking.apm.toolkit.trace.ActiveSpan; import org.apache.skywalking.apm.toolkit.trace.TraceContext; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; +import java.io.IOException; +import java.util.Arrays; + @RestController @RequestMapping("/case") public class TestController { @@ -75,6 +78,12 @@ public class TestController { } return true; }); + + // meter + MeterFactory.counter("test_counter").tag("ck1", "cv1").build().increment(2d); + MeterFactory.gauge("test_gauge", () -> 1d).tag("gk1", "gv1").build(); + MeterFactory.histogram("test_histogram").tag("hk1", "hv1").steps(Arrays.asList(1d, 5d, 10d)) + .build().addValue(4d); return SUCCESS; }