diff --git a/docs/en/guides/Plugin-test.md b/docs/en/guides/Plugin-test.md index 7280da162..166c6e980 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 a9de22b04..d3c9e5e97 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 273fa4c0a..03426b797 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 1d3e78468..188d15eba 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 5bad99e9e..d56a43853 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 b8ddd5954..e14f23cce 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 1b22c7bd0..6fdd3025d 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; }