1 # spring 2 [![Build Status][travis-image]][travis-url] 3 [![Windows Build Status][appveyor-image]][appveyor-url] 4 [![Maven Central][maven-image]][maven-url] 5 6 Provides annotation support for projects that use Spring. 7 8 ## Quickstart 9 10 ### Add the dependencies to your project. 11 12 Replace `SPRING_VERSION` with the version of spring you're using. 13 14 For Maven add to your `pom.xml`: 15 ```xml 16 <dependencies> 17 <!-- census --> 18 <dependency> 19 <groupId>io.opencensus</groupId> 20 <artifactId>opencensus-api</artifactId> 21 <version>0.16.1</version> 22 </dependency> 23 <dependency> 24 <groupId>io.opencensus</groupId> 25 <artifactId>opencensus-contrib-spring</artifactId> 26 <version>0.16.1</version> 27 </dependency> 28 <dependency> 29 <groupId>io.opencensus</groupId> 30 <artifactId>opencensus-impl</artifactId> 31 <version>0.16.1</version> 32 <scope>runtime</scope> 33 </dependency> 34 35 <!-- spring aspects --> 36 <dependency> 37 <groupId>org.springframework</groupId> 38 <artifactId>spring-aspects</artifactId> 39 <version>SPRING_VERSION</version> 40 <scope>runtime</scope> 41 </dependency> 42 43 </dependencies> 44 ``` 45 46 For Gradle add to your dependencies: 47 ```gradle 48 compile 'io.opencensus:opencensus-api:0.16.1' 49 compile 'io.opencensus:opencensus-contrib-spring:0.16.1' 50 runtime 'io.opencensus:opencensus-impl:0.16.1' 51 runtime 'org.springframework:spring-aspects:SPRING_VERSION' 52 ``` 53 54 ### Features 55 56 #### Traced Annotation 57 58 The `opencensus-contrib-spring` package provides support for a `@Traced` annotation 59 that can be applied to methods. When applied, the method will be wrapped in a 60 Span, [https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/Span.md](https://github.com/census-instrumentation/opencensus-specs/blob/master/trace/Span.md) 61 62 If the method throws an exception, the `Span` will be marked with a status of `Status.UNKNOWN` 63 and the stack trace will be added to the span as an annotation. 64 65 To enable the `@Traced` annotation, include the `CensusSpringAspect` bean. 66 67 ```xml 68 <!-- traces explicit calls to Traced --> 69 <bean id="censusAspect" class="io.opencensus.contrib.spring.aop.CensusSpringAspect"> 70 <constructor-arg ref="tracer"/> 71 </bean> 72 ``` 73 74 #### Database Support 75 76 The `opencensus-contrib-spring` package also includes support for tracing database 77 calls. When database support is included, all calls to `java.sql.PreparedStatement.execute*` 78 will be wrapped in a Span in the same way that `@Traced` wraps methods. 79 80 To enable database support, include the `CensusSpringSqlAspect` bean. 81 82 ```xml 83 <!-- traces all SQL calls --> 84 <bean id="censusSQLAspect" class="io.opencensus.contrib.spring.aop.CensusSpringSqlAspect"> 85 <constructor-arg ref="tracer"/> 86 </bean> 87 ``` 88 89 #### Complete Spring XML configuration 90 91 The following contains a complete spring xml file to configure `opencensus-contrib-spring` 92 with support for both `@Traced` and database connection tracing. 93 94 **Note:** This example does not include the configuration of any exporters. That will 95 need to be done separately. 96 97 **TBD:*** Include examples of spring with exporters. 98 99 ```xml 100 <beans xmlns="http://www.springframework.org/schema/beans" 101 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 102 xmlns:aop="http://www.springframework.org/schema/aop" 103 xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.2.xsd http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop.xsd"> 104 105 <aop:aspectj-autoproxy/> 106 107 <!-- traces explicit calls to Traced --> 108 <bean id="censusAspect" class="io.opencensus.contrib.spring.aop.CensusSpringAspect"> 109 <constructor-arg ref="tracer"/> 110 </bean> 111 112 <!-- traces all SQL calls --> 113 <bean id="censusSQLAspect" class="io.opencensus.contrib.spring.aop.CensusSpringSqlAspect"> 114 <constructor-arg ref="tracer"/> 115 </bean> 116 117 <!-- global tracer --> 118 <bean id="tracer" class="io.opencensus.trace.Tracing" factory-method="getTracer"/> 119 </beans> 120 ``` 121 122 ### Traced Usage 123 124 Once configured, you can use the `@Traced` annotation to indicate that a method should 125 be wrapped with a `Span`. By default, `@Traced` will use the name of the method as the 126 span name. However, `@Traced` supports an optional name attribute to allow a custom 127 span name to be specified. 128 129 ```java 130 @Traced() 131 void example1() { 132 // do work 133 } 134 135 // a custom span name can also be provided to Traced 136 @Traced(name = "custom-span-name") 137 void example2() { 138 // do moar work 139 } 140 ``` 141 142 #### Notes 143 144 `opencensus-contrib-spring` support only enables annotations. You will still need to configure opencensus and register exporters / views. 145 146 [travis-image]: https://travis-ci.org/census-instrumentation/opencensus-java.svg?branch=master 147 [travis-url]: https://travis-ci.org/census-instrumentation/opencensus-java 148 [appveyor-image]: https://ci.appveyor.com/api/projects/status/hxthmpkxar4jq4be/branch/master?svg=true 149 [appveyor-url]: https://ci.appveyor.com/project/opencensusjavateam/opencensus-java/branch/master 150 [maven-image]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-contrib-spring/badge.svg 151 [maven-url]: https://maven-badges.herokuapp.com/maven-central/io.opencensus/opencensus-contrib-spring 152 153 #### Java Versions 154 155 Java 6 or above is required for using this artifact. 156 157 #### About the `aop` package 158 159 `opencensus-contrib-spring` makes heavy use of Aspect Oriented Programming [AOP](https://en.wikipedia.org/wiki/Aspect-oriented_programming) to 160 add behavior to annotations. Fortunately, Spring supports this natively so we can leverage the capabilities they've already built in. 161
