Merge pull request #518 from gavlyukovskiy/spring-boot-starter

Added application insights starter for spring boot

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

@@ -0,0 +1,164 @@
+
+**Application Insights Spring Boot Starter**
+
+This Starter provides you the minimal and required configuration to use Application Insights in your Spring Boot application.
+
+**Requirements**
+Spring Boot 1.5+ or 2.0+
+
+**Quick Start**
+
+*1. Add dependency*
+Gradle:
+```groovy
+compile "com.microsoft.azure:azure-application-insights-spring-boot-starter:${version}"
+```
+
+Maven:
+```xml
+<dependency>
+  <groupId>com.microsoft.azure</groupId>
+  <artifactId>azure-application-insights-spring-boot-starter</artifactId>
+  <version>${version}</version>
+</dependency>
+```
+
+*2. Provide Instrumentation Key*
+
+Add property
+```
+azure.application-insights.instrumentation-key=<key from the Azure Portal>
+```
+into your `application.properties`
+
+*3. Run your application*
+
+Start your spring boot application as usual and in few minutes you'll start getting events.
+
+**Additional Configuration**
+
+#### Sending custom telemetry
+```java
+@RestController
+public class TelemetryController {
+
+    @Autowired
+    private TelemetryClient telemetryClient;
+
+    @RequestMapping("/telemetry")
+    public void telemetry() {
+        telemetryClient.trackEvent("my event");
+    }
+}
+```
+
+
+#### Sending logs to the application insight
+
+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.
+
+`logback-spring.xml`:
+```xml
+<appender name="aiAppender"
+  class="com.microsoft.applicationinsights.logback.ApplicationInsightsAppender">
+</appender>
+<root level="trace">
+  <appender-ref ref="aiAppender" />
+</root>
+```
+
+`log4j2.xml`:
+```xml
+<Configuration packages="com.microsoft.applicationinsights.log4j.v2">
+  <Appenders>
+    <ApplicationInsightsAppender name="aiAppender" />
+  </Appenders>
+  <Loggers>
+    <Root level="trace">
+      <AppenderRef ref="aiAppender"/>
+    </Root>
+  </Loggers>
+</Configuration>
+```
+
+#### Register own telemetry module, processor or initializer by defining it as a bean in the configuration
+```java
+@SpringBootApplication
+public class MyApplication {
+
+    public static void main(String[] args) {
+        SpringApplication.run(MyApplication.class, args);
+    }
+
+    @Bean
+    public TelemetryModule myTelemetryModule() {
+        return new MyTelemetryModule();
+    }
+
+    @Bean
+    public TelemetryInitializer myTelemetryInitializer() {
+        return new MyTelemetryInitializer();
+    }
+
+    @Bean
+    public TelemetryProcessor myTelemetryProcessor() {
+        return new MyTelemetryProcessor();
+    }
+
+    @Bean
+    public ContextInitializer myContextInitializer() {
+        return new MyContextInitializer();
+    }
+}
+```
+
+
+#### Configure more parameters using `application.properties`
+```properties
+# Instrumentation key from the Azure Portal. Required.
+azure.application-insights.instrumentation-key=00000000-0000-0000-0000-000000000000
+
+# Enable/Disable tracking. Default value: true.
+azure.application-insights.enabled=true
+
+# Enable/Disable web modules. Default value: true.
+azure.application-insights.web.enabled=true
+
+# Logging type [console, file]. Default value: console.
+azure.application-insights.logger.type=console
+# Logging level [all, trace, info, warn, error, off]. Default value: error.
+azure.application-insights.logger.level=error
+
+# 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.
+azure.application-insights.channel.in-process.developer-mode=false
+# Endpoint address, Default value: https://dc.services.visualstudio.com/v2/track.
+azure.application-insights.channel.in-process.endpoint-address=https://dc.services.visualstudio.com/v2/track
+# Maximum count of telemetries that will be batched before sending. Must be between 1 and 1000. Default value: 500.
+azure.application-insights.channel.in-process.max-telemetry-buffer-capacity=500
+# Interval to send telemetry. Must be between 1 and 300. Default value: 5 seconds.
+azure.application-insights.channel.in-process.flush-interval-in-seconds=5
+# 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.
+azure.application-insights.channel.in-process.max-transmission-storage-files-capacity-in-mb=10
+# Enable/Disable throttling on sending telemetry data. Default value: true.
+azure.application-insights.channel.in-process.throttling=true
+
+# Percent of telemetry events that will be sent to Application Insights. Percentage must be close to 100/N where N is an integer.
+# 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).
+azure.application-insights.telemetry-processor.sampling.percentage=100
+# If set only telemetry of specified types will be included. Default value: all telemetries are included;
+azure.application-insights.telemetry-processor.sampling.include=
+# If set telemetry of specified type will be excluded. Default value: none telemetries are excluded.
+azure.application-insights.telemetry-processor.sampling.exclude=
+
+# Enable/Disable default telemetry modules. Default value: true.
+azure.application-insights.default-modules.ProcessPerformanceCountersModule.enabled=true
+azure.application-insights.default-modules.WebRequestTrackingTelemetryModule.enabled=true
+azure.application-insights.default-modules.WebSessionTrackingTelemetryModule.enabled=true
+azure.application-insights.default-modules.WebUserTrackingTelemetryModule.enabled=true
+azure.application-insights.default-modules.WebPerformanceCounterModule.enabled=true
+azure.application-insights.default-modules.WebOperationIdTelemetryInitializer.enabled=true
+azure.application-insights.default-modules.WebOperationNameTelemetryInitializer.enabled=true
+azure.application-insights.default-modules.WebSessionTelemetryInitializer.enabled=true
+azure.application-insights.default-modules.WebUserTelemetryInitializer.enabled=true
+azure.application-insights.default-modules.WebUserAgentTelemetryInitializer.enabled=true
+```

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

@@ -0,0 +1,51 @@
+/*
+ * ApplicationInsights-Java
+ * Copyright (c) Microsoft Corporation
+ * All rights reserved.
+ *
+ * MIT License
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this
+ * software and associated documentation files (the ""Software""), to deal in the Software
+ * without restriction, including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ * The above copyright notice and this permission notice shall be included in all copies or
+ * substantial portions of the Software.
+ * THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+ * PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+ * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
+apply from: "$buildScriptsDir/common-java.gradle"
+apply from: "$buildScriptsDir/publishing.gradle"
+
+archivesBaseName = 'azure-application-insights-spring-boot-starter'
+
+dependencies {
+    compile (project(':core'))
+    compile (project(':web'))
+    provided('org.springframework.boot:spring-boot:1.5.9.RELEASE')
+    provided('org.springframework.boot:spring-boot-autoconfigure:1.5.9.RELEASE')
+    provided('org.springframework.boot:spring-boot-starter-web:1.5.9.RELEASE')
+    provided('org.springframework.boot:spring-boot-configuration-processor:1.5.9.RELEASE')
+
+    testCompile('org.junit.jupiter:junit-jupiter-api:5.0.2')
+    testCompile('org.junit.jupiter:junit-jupiter-params:5.0.2')
+    testCompile('org.junit.jupiter:junit-jupiter-engine:5.0.2')
+    testCompile('org.springframework.boot:spring-boot-starter-test:1.5.9.RELEASE')
+    testCompile('org.assertj:assertj-core:3.9.0')
+}
+
+// region Publishing properties
+
+projectPomName = project.msftAppInsightsJavaSdk + " Spring Boot starter"
+projectPomDescription = "This is the Spring Boot starter of " + project.msftAppInsightsJavaSdk
+
+whenPomConfigured = { p ->
+    def agentArtifactId = project(":agent").jar.baseName
+    p.dependencies = p.dependencies.findAll { dep -> dep.artifactId != agentArtifactId }
+    writePomToArtifactsDirectory(p, project.name)
+}

azure-application-insights-spring-boot-starter/src/main/java/com/microsoft/applicationinsights/boot/ApplicationInsightsModuleConfiguration.java

@@ -0,0 +1,70 @@
+/*
+ * ApplicationInsights-Java
+ * Copyright (c) Microsoft Corporation
+ * All rights reserved.
+ *
+ * MIT License
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this
+ * software and associated documentation files (the ""Software""), to deal in the Software
+ * without restriction, including without limitation the rights to use, copy, modify, merge,
+ * publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ * The above copyright notice and this permission notice shall be included in all copies or
+ * substantial portions of the Software.
+ * THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+ * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+ * PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE
+ * FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ * DEALINGS IN THE SOFTWARE.
+ */
+
+package com.microsoft.applicationinsights.boot;
+
+import com.microsoft.applicationinsights.boot.conditional.ConditionalOnOperatingSystem;
+import com.microsoft.applicationinsights.boot.conditional.OperatingSystem;
+import com.microsoft.applicationinsights.boot.initializer.SpringBootContextInitializer;
+import com.microsoft.applicationinsights.extensibility.initializer.DeviceInfoContextInitializer;
+import com.microsoft.applicationinsights.extensibility.initializer.SdkVersionContextInitializer;
+import com.microsoft.applicationinsights.internal.perfcounter.ProcessPerformanceCountersModule;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.core.env.Environment;
+
+/**
+ * {@link Configuration} for non-web applications.
+ *
+ * @author Arthur Gavlyukovskiy
+ */
+@Configuration
+public class ApplicationInsightsModuleConfiguration {
+
+    @Bean
+    public SpringBootContextInitializer springBootContextInitializer(Environment environment) {
+        return new SpringBootContextInitializer(environment);
+    }
+
+    @Bean
+    public SdkVersionContextInitializer sdkVersionContextInitializer() {
+        return new SdkVersionContextInitializer();
+    }
+
+    @Bean
+    public DeviceInfoContextInitializer deviceInfoContextInitializer() {
+        return new DeviceInfoContextInitializer();
+    }
+
+    @Bean
+    @ConditionalOnOperatingSystem(OperatingSystem.WINDOWS)
+    @ConditionalOnProperty(value = "azure.application-insights.default-modules.ProcessPerformanceCountersModule.enabled", havingValue = "true", matchIfMissing = true)
+    public ProcessPerformanceCountersModule processPerformanceCountersModule() {
+        try {
+            return new ProcessPerformanceCountersModule();
+        }
+        catch (Exception e) {
+            throw new IllegalStateException("Could not initialize Windows performance counters module, " +
+                    "please set property 'azure.application-insights.default-modules.ProcessPerformanceCountersModule.enabled=false' to avoid this error message.", e);
+        }
+    }
+}