From fe455155366c12d183d5e863f9123d11249138cb Mon Sep 17 00:00:00 2001 From: Munir Abdinur <62392438+mabdinur@users.noreply.github.com> Date: Tue, 11 Aug 2020 02:53:18 +0000 Subject: [PATCH] Add spring webmvc documentation (#915) * add readme and rename WebMvcFilter * Update README.md * format * clean up readme * clean up readme * clean up readme * Update README.md * fix web mvc naming * format, clean up comments * format, clean up comments --- ...ava => WebMvcFilterAutoConfiguration.java} | 10 +-- ...CProperties.java => WebMvcProperties.java} | 2 +- .../main/resources/META-INF/spring.factories | 2 +- ...=> WebMvcFilterAutoConfigurationTest.java} | 14 +-- .../spring/spring-webmvc-3.1/README.md | 90 +++++++++++++++++++ .../webmvc}/SpringWebMvcServerTracer.java | 2 +- .../webmvc/WebMvcTracingFilter.java} | 6 +- 7 files changed, 108 insertions(+), 18 deletions(-) rename instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/{WebMVCFilterAutoConfiguration.java => WebMvcFilterAutoConfiguration.java} (82%) rename instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/{WebMVCProperties.java => WebMvcProperties.java} (96%) rename instrumentation-core/spring/spring-boot-autoconfigure/src/test/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/{WebMVCFilterAutoConfigurationTest.java => WebMvcFilterAutoConfigurationTest.java} (80%) create mode 100644 instrumentation-core/spring/spring-webmvc-3.1/README.md rename instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/{springwebmvc => spring/webmvc}/SpringWebMvcServerTracer.java (98%) rename instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/{springwebmvc/WebMVCTracingFilter.java => spring/webmvc/WebMvcTracingFilter.java} (92%) diff --git a/instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMVCFilterAutoConfiguration.java b/instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMvcFilterAutoConfiguration.java similarity index 82% rename from instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMVCFilterAutoConfiguration.java rename to instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMvcFilterAutoConfiguration.java index 0d22649dc8..137e529962 100644 --- a/instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMVCFilterAutoConfiguration.java +++ b/instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMvcFilterAutoConfiguration.java @@ -16,7 +16,7 @@ package io.opentelemetry.instrumentation.spring.autoconfigure.webmvc; -import io.opentelemetry.instrumentation.springwebmvc.WebMVCTracingFilter; +import io.opentelemetry.instrumentation.spring.webmvc.WebMvcTracingFilter; import io.opentelemetry.trace.Tracer; import org.springframework.boot.autoconfigure.condition.ConditionalOnClass; import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty; @@ -27,13 +27,13 @@ import org.springframework.web.filter.OncePerRequestFilter; /** Configures {@link WebMVCFilter} for tracing. */ @Configuration -@EnableConfigurationProperties(WebMVCProperties.class) +@EnableConfigurationProperties(WebMvcProperties.class) @ConditionalOnProperty(prefix = "opentelemetry.trace.web", name = "enabled", matchIfMissing = true) @ConditionalOnClass(OncePerRequestFilter.class) -public class WebMVCFilterAutoConfiguration { +public class WebMvcFilterAutoConfiguration { @Bean - public WebMVCTracingFilter otelWebMVCTracingFilter(final Tracer tracer) { - return new WebMVCTracingFilter(tracer); + public WebMvcTracingFilter otelWebMvcTracingFilter(final Tracer tracer) { + return new WebMvcTracingFilter(tracer); } } diff --git a/instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMVCProperties.java b/instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMvcProperties.java similarity index 96% rename from instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMVCProperties.java rename to instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMvcProperties.java index bd475aee37..beceec1f46 100644 --- a/instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMVCProperties.java +++ b/instrumentation-core/spring/spring-boot-autoconfigure/src/main/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMvcProperties.java @@ -25,7 +25,7 @@ import org.springframework.boot.context.properties.ConfigurationProperties; * exist in application context */ @ConfigurationProperties(prefix = "opentelemetry.trace.web") -public final class WebMVCProperties { +public final class WebMvcProperties { private boolean enabled = true; public boolean isEnabled() { diff --git a/instrumentation-core/spring/spring-boot-autoconfigure/src/main/resources/META-INF/spring.factories b/instrumentation-core/spring/spring-boot-autoconfigure/src/main/resources/META-INF/spring.factories index 4c63aebcfa..f56a9506ef 100644 --- a/instrumentation-core/spring/spring-boot-autoconfigure/src/main/resources/META-INF/spring.factories +++ b/instrumentation-core/spring/spring-boot-autoconfigure/src/main/resources/META-INF/spring.factories @@ -6,5 +6,5 @@ io.opentelemetry.instrumentation.spring.autoconfigure.exporters.logging.LoggingS io.opentelemetry.instrumentation.spring.autoconfigure.TracerAutoConfiguration,\ io.opentelemetry.instrumentation.spring.autoconfigure.httpclients.resttemplate.RestTemplateAutoConfiguration,\ io.opentelemetry.instrumentation.spring.autoconfigure.httpclients.webclient.WebClientAutoConfiguration,\ -io.opentelemetry.instrumentation.spring.autoconfigure.webmvc.WebMVCFilterAutoConfiguration,\ +io.opentelemetry.instrumentation.spring.autoconfigure.webmvc.WebMvcFilterAutoConfiguration,\ io.opentelemetry.instrumentation.spring.autoconfigure.aspects.TraceAspectAutoConfiguration diff --git a/instrumentation-core/spring/spring-boot-autoconfigure/src/test/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMVCFilterAutoConfigurationTest.java b/instrumentation-core/spring/spring-boot-autoconfigure/src/test/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMvcFilterAutoConfigurationTest.java similarity index 80% rename from instrumentation-core/spring/spring-boot-autoconfigure/src/test/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMVCFilterAutoConfigurationTest.java rename to instrumentation-core/spring/spring-boot-autoconfigure/src/test/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMvcFilterAutoConfigurationTest.java index 7ecf736d78..d8b0777075 100644 --- a/instrumentation-core/spring/spring-boot-autoconfigure/src/test/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMVCFilterAutoConfigurationTest.java +++ b/instrumentation-core/spring/spring-boot-autoconfigure/src/test/java/io/opentelemetry/instrumentation/spring/autoconfigure/webmvc/WebMvcFilterAutoConfigurationTest.java @@ -19,19 +19,19 @@ package io.opentelemetry.instrumentation.spring.autoconfigure.webmvc; import static org.assertj.core.api.Assertions.assertThat; import io.opentelemetry.instrumentation.spring.autoconfigure.TracerAutoConfiguration; -import io.opentelemetry.instrumentation.springwebmvc.WebMVCTracingFilter; +import io.opentelemetry.instrumentation.spring.webmvc.WebMvcTracingFilter; import org.junit.jupiter.api.DisplayName; import org.junit.jupiter.api.Test; import org.springframework.boot.autoconfigure.AutoConfigurations; import org.springframework.boot.test.context.runner.ApplicationContextRunner; -/** Spring Boot auto configuration test for {@link WebMVCFilterAutoConfiguration} */ -class WebMVCFilterAutoConfigurationTest { +/** Spring Boot auto configuration test for {@link WebMvcFilterAutoConfiguration} */ +class WebMvcFilterAutoConfigurationTest { private final ApplicationContextRunner contextRunner = new ApplicationContextRunner() .withConfiguration( AutoConfigurations.of( - TracerAutoConfiguration.class, WebMVCFilterAutoConfiguration.class)); + TracerAutoConfiguration.class, WebMvcFilterAutoConfiguration.class)); @Test @DisplayName("when web is ENABLED should initialize WebMvcTracingFilter bean") @@ -40,7 +40,7 @@ class WebMVCFilterAutoConfigurationTest { .withPropertyValues("opentelemetry.trace.web.enabled=true") .run( (context) -> { - assertThat(context.getBean("otelWebMVCTracingFilter", WebMVCTracingFilter.class)) + assertThat(context.getBean("otelWebMvcTracingFilter", WebMvcTracingFilter.class)) .isNotNull(); }); } @@ -52,7 +52,7 @@ class WebMVCFilterAutoConfigurationTest { .withPropertyValues("opentelemetry.trace.web.enabled=false") .run( (context) -> { - assertThat(context.containsBean("otelWebMVCTracingFilter")).isFalse(); + assertThat(context.containsBean("otelWebMvcTracingFilter")).isFalse(); }); } @@ -61,7 +61,7 @@ class WebMVCFilterAutoConfigurationTest { void noProperty() { this.contextRunner.run( (context) -> { - assertThat(context.getBean("otelWebMVCTracingFilter", WebMVCTracingFilter.class)) + assertThat(context.getBean("otelWebMvcTracingFilter", WebMvcTracingFilter.class)) .isNotNull(); }); } diff --git a/instrumentation-core/spring/spring-webmvc-3.1/README.md b/instrumentation-core/spring/spring-webmvc-3.1/README.md new file mode 100644 index 0000000000..d8c3a428f3 --- /dev/null +++ b/instrumentation-core/spring/spring-webmvc-3.1/README.md @@ -0,0 +1,90 @@ +# Manual Instrumentation for Spring Web MVC + +Provides OpenTelemetry tracing for spring-webmvc RestControllers by leveraging spring-webmvc [filters](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/filter). + +## Quickstart + +### Add these dependencies to your project. + +Replace `SPRING_VERSION` with the version of spring you're using. + - `Minimum version: 3.1` + +Replace `OPENTELEMETRY_VERSION` with the latest stable [release](https://mvnrepository.com/artifact/io.opentelemetry). + - `Minimum version: 0.8.0` + +For Maven add to your `pom.xml`: + +```xml + + + + io.opentelemetry.instrumentation + opentelemetry-spring-webmvc-3.1 + OPENTELEMETRY_VERSION + + + + + + io.opentelemetry + opentelemetry-exporters-logging + OPENTELEMETRY_VERSION + + + + + + org.springframework + spring-webmvc + SPRING_VERSION + + + +``` + +For Gradle add to your dependencies: + +```groovy + +// opentelemetry instrumentation +implementation 'io.opentelemetry.instrumentation:opentelemetry-spring-webmvc-3.1:OPENTELEMETRY_VERSION' + +// opentelemetry exporter +// replace this default exporter with your opentelemetry exporter (ex. otlp/zipkin/jaeger/..) +implementation 'io.opentelemetry:opentelemetry-exporters-logging:OPENTELEMETRY_VERSION' + +// required to instrument spring-webmvc +// this artifact should already be present in your application +implementation 'org.springframework:spring-webmvc:SPRING_VERSION' +``` + +### Features + +#### WebMvcTracingFilter + +WebMvcTracingFilter adds OpenTelemetry server spans to requests processed by request dispatch, on any spring servlet container. An example is shown below: + +##### Usage + +```java +import io.opentelemetry.instrumentation.spring.webmvc.WebMvcTracingFilter +import io.opentelemetry.trace.Tracer; + +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.context.annotation.Bean; +import org.springframework.context.annotation.Configuration; +import org.springframework.web.client.RestTemplate; + +@Configuration +public class WebMvcTracingFilterConfig { + + @Bean + public WebMvcTracingFilter webMvcTracingFilter(Tracer tracer) { + return new WebMvcTracingFilter(tracer); + } +} +``` + +### Starter Guide + +Check out the opentelemetry [quick start](https://github.com/open-telemetry/opentelemetry-java/blob/master/QUICKSTART.md) to learn more about OpenTelemetry instrumentation. diff --git a/instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/springwebmvc/SpringWebMvcServerTracer.java b/instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/spring/webmvc/SpringWebMvcServerTracer.java similarity index 98% rename from instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/springwebmvc/SpringWebMvcServerTracer.java rename to instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/spring/webmvc/SpringWebMvcServerTracer.java index 0a1a8f57f6..0c5ed411a9 100644 --- a/instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/springwebmvc/SpringWebMvcServerTracer.java +++ b/instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/spring/webmvc/SpringWebMvcServerTracer.java @@ -14,7 +14,7 @@ * limitations under the License. */ -package io.opentelemetry.instrumentation.springwebmvc; +package io.opentelemetry.instrumentation.spring.webmvc; import io.grpc.Context; import io.opentelemetry.context.propagation.HttpTextFormat.Getter; diff --git a/instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/springwebmvc/WebMVCTracingFilter.java b/instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/spring/webmvc/WebMvcTracingFilter.java similarity index 92% rename from instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/springwebmvc/WebMVCTracingFilter.java rename to instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/spring/webmvc/WebMvcTracingFilter.java index 1afe35e3d4..0d49277b13 100644 --- a/instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/springwebmvc/WebMVCTracingFilter.java +++ b/instrumentation-core/spring/spring-webmvc-3.1/src/main/java/io/opentelemetry/instrumentation/spring/webmvc/WebMvcTracingFilter.java @@ -14,7 +14,7 @@ * limitations under the License. */ -package io.opentelemetry.instrumentation.springwebmvc; +package io.opentelemetry.instrumentation.spring.webmvc; import io.opentelemetry.context.Scope; import io.opentelemetry.trace.Span; @@ -27,13 +27,13 @@ import javax.servlet.http.HttpServletResponse; import org.springframework.core.Ordered; import org.springframework.web.filter.OncePerRequestFilter; -public class WebMVCTracingFilter extends OncePerRequestFilter implements Ordered { +public class WebMvcTracingFilter extends OncePerRequestFilter implements Ordered { private static final String FILTER_CLASS = "WebMVCTracingFilter"; private static final String FILTER_METHOD = "doFilterInteral"; private final SpringWebMvcServerTracer tracer; - public WebMVCTracingFilter(Tracer tracer) { + public WebMvcTracingFilter(Tracer tracer) { this.tracer = new SpringWebMvcServerTracer(tracer); }