Skip to content

Commit cbb51bd

Browse files
dhaval24dhaval24
authored
Azure Application Insights SpringBoot Starter (#646)
* Added application insights starter for spring boot * Added a way to disable default modules, added documentation and readme * Polish readme * Added properties to disable quick pulse integration, all web modules; Clarified all default values in readme; Changed default logging level to error; Added @ConditionalOnWebApplication for web configurations. * Fixed bean ordering issue * Added properties for channel and new sampler, created TelemetryType enum for property auto complete * Added documentation to added properties, added default values, updated readme. * Changed sampling configuration, added more tests for autoconfiguration * Changed constants with default values to public in order to use them in spring boot starter * Added explicit dependency on TelemetryConfiguration for QuickPulse bean * Polish * Updated documentation regarding configuration values window * Updated documentation of properties * update build script to fix pom generation, enforced InternalLoggerBean to be created first * improving the way to locate agent and registering web app * adding way to get empty telemetry configuration object * adding max_instant_rety configuration for boot * refactoring spelling error * fix a test * fixing broken initialization * changing SpringBootContextInitializer to TelemetryInitializer, contextTags are not reflected on UX if not in bond schema definition * updating enabling web modules and enabling AI, adding autoconfiguration for JMX counters and JVM counters * migrate tests to junit4 * adding more tests * Heartbeat updates to accomodate autoconfig in SpringBoot * Adding auto cofiguration for SpringBoot * removing SpringBootInitializer to push meta deta, instead moving to heartbeat * autoconfigure cloud_RoleName, removed field injection to constructor and setter injection, added java docs, added tests and improved README * fixing dependency version * specifying the version number * resolving merge conflict, removed unused Operating system conditional, some refactoring to make the AutoConfiguration class simple * remove unused imports * modifying version number * updating the archive base name for consistency, adding javadocs * adding null check, some fixes and reducing styling * fix test and intermediate commit * removing TelemetryType enum for better maintanability, refactoring starter accordingly, making HeartBeatPayloadProviderInterface bean, fixing critical issue with sampling configuration * Revert "improving the way to locate agent and registering web app" This reverts commit bc19586. * modularizing way to specify version number of starter, adding starter version number to HB telemetry * reverting a file and fixing dual initialization * adding the configuration parity tests * updating readme with migration steps * Smoke Tests for SpringBoot Application using SpringBoot AI Starter (#665) * smoke test for SpringBoot * smoke test app springboot * trying java 7 * trying source and target compatibility * fixing assert * enabling the temporarily disbabled smoke tests * Reverting temporary adjustments
1 parent f79cdb8 commit cbb51bd

File tree

35 files changed

+2592
-120
lines changed

35 files changed

+2592
-120
lines changed

‎azure-application-insights-spring-boot-starter/README.md‎

Lines changed: 201 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,201 @@
1+
2+
**Application Insights Spring Boot Starter**
3+
4+
This Starter provides you the minimal and required configuration to use Application Insights in your Spring Boot application.
5+
6+
**Requirements**
7+
Spring Boot 1.5+ or 2.0+
8+
9+
**Quick Start**
10+
11+
*1. Add dependency*
12+
Gradle:
13+
```groovy
14+
compile "com.microsoft.azure:azure-application-insights-spring-boot-starter:${version}"
15+
```
16+
17+
Maven:
18+
```xml
19+
<dependency>
20+
<groupId>com.microsoft.azure</groupId>
21+
<artifactId>azure-application-insights-spring-boot-starter</artifactId>
22+
<version>${version}</version>
23+
</dependency>
24+
```
25+
26+
*2. Provide Instrumentation Key*
27+
28+
Add property
29+
```
30+
azure.application-insights.instrumentation-key=<key from the Azure Portal>
31+
```
32+
into your `application.properties`
33+
34+
*3. Run your application*
35+
36+
Start your spring boot application as usual and in few minutes you'll start getting events.
37+
38+
**Additional Configuration**
39+
40+
#### Sending custom telemetry
41+
```java
42+
@RestController
43+
public class TelemetryController {
44+
45+
@Autowired
46+
private TelemetryClient telemetryClient;
47+
48+
@RequestMapping("/telemetry")
49+
public void telemetry() {
50+
telemetryClient.trackEvent("my event");
51+
}
52+
}
53+
```
54+
55+
56+
#### Sending logs to the application insight
57+
58+
Follow the instructions from [Spring Boot logging documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/howto-logging.html) to configure custom logback or log4j2 appender.
59+
60+
`logback-spring.xml`:
61+
```xml
62+
<appender name="aiAppender"
63+
class="com.microsoft.applicationinsights.logback.ApplicationInsightsAppender">
64+
</appender>
65+
<root level="trace">
66+
<appender-ref ref="aiAppender" />
67+
</root>
68+
```
69+
70+
`log4j2.xml`:
71+
```xml
72+
<Configuration packages="com.microsoft.applicationinsights.log4j.v2">
73+
<Appenders>
74+
<ApplicationInsightsAppender name="aiAppender" />
75+
</Appenders>
76+
<Loggers>
77+
<Root level="trace">
78+
<AppenderRef ref="aiAppender"/>
79+
</Root>
80+
</Loggers>
81+
</Configuration>
82+
```
83+
84+
#### Register own telemetry module, processor or initializer by defining it as a bean in the configuration
85+
```java
86+
@SpringBootApplication
87+
public class MyApplication {
88+
89+
public static void main(String[] args) {
90+
SpringApplication.run(MyApplication.class, args);
91+
}
92+
93+
@Bean
94+
public TelemetryModule myTelemetryModule() {
95+
return new MyTelemetryModule();
96+
}
97+
98+
@Bean
99+
public TelemetryInitializer myTelemetryInitializer() {
100+
return new MyTelemetryInitializer();
101+
}
102+
103+
@Bean
104+
public TelemetryProcessor myTelemetryProcessor() {
105+
return new MyTelemetryProcessor();
106+
}
107+
108+
@Bean
109+
public ContextInitializer myContextInitializer() {
110+
return new MyContextInitializer();
111+
}
112+
}
113+
```
114+
115+
116+
#### Configure more parameters using `application.properties`
117+
```properties
118+
# Instrumentation key from the Azure Portal. Required.
119+
azure.application-insights.instrumentation-key=00000000-0000-0000-0000-000000000000
120+
121+
# Enable/Disable tracking. Default value: true.
122+
azure.application-insights.enabled=true
123+
124+
# Enable/Disable web modules. Default value: true.
125+
azure.application-insights.web.enabled=true
126+
127+
# Logging type [console, file]. Default value: console.
128+
azure.application-insights.logger.type=console
129+
# Logging level [all, trace, info, warn, error, off]. Default value: error.
130+
azure.application-insights.logger.level=error
131+
132+
# Enable/Disable QuickPulse (Live Metrics). Default value: True
133+
azure.application-insights.quick-pulse.enabled=true
134+
135+
# Enable/Disable developer mode, all telemetry will be sent immediately without batching. Significantly affects performance and should be used only in developer environment. Default value: false.
136+
azure.application-insights.channel.in-process.developer-mode=false
137+
# Endpoint address, Default value: https://dc.services.visualstudio.com/v2/track.
138+
azure.application-insights.channel.in-process.endpoint-address=https://dc.services.visualstudio.com/v2/track
139+
# Maximum count of telemetries that will be batched before sending. Must be between 1 and 1000. Default value: 500.
140+
azure.application-insights.channel.in-process.max-telemetry-buffer-capacity=500
141+
# Interval to send telemetry. Must be between 1 and 300. Default value: 5 seconds.
142+
azure.application-insights.channel.in-process.flush-interval-in-seconds=5
143+
# Size of disk space that Application Insights can use to store telemetry in case of network outage. Must be between 1 and 1000. Default value: 10 megabytes.
144+
azure.application-insights.channel.in-process.max-transmission-storage-files-capacity-in-mb=10
145+
# Enable/Disable throttling on sending telemetry data. Default value: true.
146+
azure.application-insights.channel.in-process.throttling=true
147+
148+
# Percent of telemetry events that will be sent to Application Insights. Percentage must be close to 100/N where N is an integer.
149+
# E.g. 50 (=100/2), 33.33 (=100/3), 25 (=100/4), 20, 1 (=100/100), 0.1 (=100/1000). Default value: 100 (all telemetry events).
150+
azure.application-insights.telemetry-processor.sampling.percentage=100
151+
# If set only telemetry of specified types will be included. Default value: all telemetries are included;
152+
azure.application-insights.telemetry-processor.sampling.include=
153+
# If set telemetry of specified type will be excluded. Default value: none telemetries are excluded.
154+
azure.application-insights.telemetry-processor.sampling.exclude=
155+
156+
# Enable/Disable default telemetry modules. Default value: true.
157+
azure.application-insights.default-modules.ProcessPerformanceCountersModule.enabled=true
158+
azure.application-insights.default-modules.JvmPerformanceCountersModule.enabled=true
159+
azure.application-insights.default-modules.WebRequestTrackingTelemetryModule.enabled=true
160+
azure.application-insights.default-modules.WebSessionTrackingTelemetryModule.enabled=true
161+
azure.application-insights.default-modules.WebUserTrackingTelemetryModule.enabled=true
162+
azure.application-insights.default-modules.WebPerformanceCounterModule.enabled=true
163+
azure.application-insights.default-modules.WebOperationIdTelemetryInitializer.enabled=true
164+
azure.application-insights.default-modules.WebOperationNameTelemetryInitializer.enabled=true
165+
azure.application-insights.default-modules.WebSessionTelemetryInitializer.enabled=true
166+
azure.application-insights.default-modules.WebUserTelemetryInitializer.enabled=true
167+
azure.application-insights.default-modules.WebUserAgentTelemetryInitializer.enabled=true
168+
169+
#Enable/Disable heartbeat module. Default value : true
170+
azure.application-insights.heart-beat.enabled=true
171+
#Default heartbeat interval is 15 minutes. Minimum heartbeat interval can be 30 seconds.
172+
azure.application-insights.heart-beat.heart-beat-interval=900
173+
#If set of properties are specified they would be excluded from Heartbeat payload
174+
azure.application-insights.heart-beat.excluded-heart-beat-properties-list=
175+
#If set of HeartBeat providers are specified they would be excluded
176+
azure.application-insights.heart-beat.excluded-heart-beat-provider-list=
177+
```
178+
179+
### Completely disable Application Insights using `application.properties`
180+
```properties
181+
azure.application-insights.enabled=false
182+
azure.application-insights.web.enabled=false
183+
```
184+
Note: Do not configure `azure.application-insights.instrumentation-key` property for optimal performance
185+
and avoiding any Application Insights beans creation by Spring.
186+
187+
188+
## Migrating from XML based configuration ##
189+
1. Please remove ApplicationInsights.xml file from the project resources or class path.
190+
2. Add applicationinsights-spring-boot-starter-<version_number>.jar file to pom.xml or build.gradle (you do not need to specify applicationinsights-core and web jars independently).
191+
The starter takes are of it for you.
192+
3. Please configure springboot Application.properties file with Application Insights Instrumentation key.
193+
4. Compile the project and execute it from your IDE or command line using java -jar applicationjarname
194+
5. To specify AI properties using command line please refer to SpringBoot Documentation.
195+
6. To use [ApplicationInsigts Java agent](https://docs.microsoft.com/en-us/azure/application-insights/app-insights-java-agent) please follow official documentation
196+
4. To get an initialized instance of TelemetryClient please use Spring autowired annotation. This will provide a fully initialized instance of TelemetryClient.
197+
198+
```Java
199+
@Autowired
200+
TelemetryClient client;
201+
```

‎azure-application-insights-spring-boot-starter/build.gradle‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
import com.microsoft.applicationinsights.build.tasks.PropsFileGen
2+
3+
/*
4+
* ApplicationInsights-Java
5+
* Copyright (c) Microsoft Corporation
6+
* All rights reserved.
7+
*
8+
* MIT License
9+
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
10+
* software and associated documentation files (the ""Software""), to deal in the Software
11+
* without restriction, including without limitation the rights to use, copy, modify, merge,
12+
* publish, distribute, sublicense, and/or sell copies of the Software, and to permit
13+
* persons to whom the Software is furnished to do so, subject to the following conditions:
14+
* The above copyright notice and this permission notice shall be included in all copies or
15+
* substantial portions of the Software.
16+
* THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
17+
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
18+
* PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
19+
* FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
20+
* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
21+
* DEALINGS IN THE SOFTWARE.
22+
*/
23+
24+
apply from: "$buildScriptsDir/common-java.gradle"
25+
apply from: "$buildScriptsDir/publishing.gradle"
26+
27+
archivesBaseName = 'applicationinsights-spring-boot-starter'
28+
version = project.properties['spring.boot.starter.version-number']
29+
30+
def starterVersionFileDir = "$project.buildDir/src/generated/main/resources"
31+
task generateVersionProperties(type: PropsFileGen) {
32+
targetFile = new File(starterVersionFileDir, "starter-version.properties")
33+
property "version", project.version
34+
}
35+
36+
processResources.dependsOn generateVersionProperties
37+
38+
sourceSets {
39+
main {
40+
resources {
41+
srcDir starterVersionFileDir
42+
}
43+
}
44+
}
45+
46+
dependencies {
47+
compile (project(':core'))
48+
compile (project(':web'))
49+
provided('org.springframework.boot:spring-boot:1.5.9.RELEASE')
50+
provided('org.springframework.boot:spring-boot-autoconfigure:1.5.9.RELEASE')
51+
provided('org.springframework.boot:spring-boot-starter-web:1.5.9.RELEASE')
52+
provided('org.springframework.boot:spring-boot-configuration-processor:1.5.9.RELEASE')
53+
testCompile('junit:junit:4.12')
54+
testCompile('org.springframework.boot:spring-boot-starter-test:1.5.9.RELEASE')
55+
testCompile('org.assertj:assertj-core:2.6.0')
56+
}
57+
58+
compileJava.dependsOn(processResources)
59+
// region Publishing properties
60+
61+
projectPomName = project.msftAppInsightsJavaSdk + " Spring Boot starter"
62+
projectPomDescription = "This is the Spring Boot starter of " + project.msftAppInsightsJavaSdk
63+
64+
whenPomConfigured = { p ->
65+
def agentArtifactId = project(":agent").jar.baseName
66+
p.dependencies = p.dependencies.findAll { dep -> dep.artifactId != agentArtifactId }
67+
}

‎azure-application-insights-spring-boot-starter/gradle.properties‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
spring.boot.starter.version-number=1.0.0-BETA

0 commit comments

Comments
 (0)