Merge remote-tracking branch 'origin/develop'

.gitignore

@@ -250,3 +250,6 @@ paket-files/
 # JetBrains Rider
 .idea/
 *.sln.iml
+
+# Local global.json
+global.json

README.md

@@ -1,41 +1,75 @@
-Microsoft Application Insights for Kubernetes
-==
+# Microsoft Application Insights for Kubernetes
+
 This repository has code for Application Insights for Kubernetes, which works on .NET Core applications within the containers, managed by Kubernetes, on Azure Container Service.
 
 **Note:** `Microsoft Application Insights for Kubernetes` (this library) is an enhancement to the [Microsoft Application Insights](https://github.com/Microsoft/ApplicationInsights-aspnetcore). You can choose to run **Application Insights** without this library in Kubernetes cluster too. However, when using `Microsoft Application Insights for Kubernetes`, you will see Kubernetes related properties like *Pod-Name, Deployment ...* on all your telemetry entries. Proper values will also be set to make use of the rich features like enabling the Application Map to show the multiple micro services on the same map.
 
-### Continous Integration Status
-|Rolling Build                    | Nightly Build                |
-|---------------------------------|:-----------------------------|
-|![Rolling-Build Status](https://devdiv.visualstudio.com/_apis/public/build/definitions/0bdbc590-a062-4c3f-b0f6-9383f67865ee/5974/badge) | ![Nightly-Build Status](https://devdiv.visualstudio.com/_apis/public/build/definitions/0bdbc590-a062-4c3f-b0f6-9383f67865ee/5976/badge) |
+## Continuous Integration Status
+
+| Rolling Build                                                                                                                           | Nightly Build                                                                                                                           |
+| --------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
+| ![Rolling-Build Status](https://devdiv.visualstudio.com/_apis/public/build/definitions/0bdbc590-a062-4c3f-b0f6-9383f67865ee/5974/badge) | ![Nightly-Build Status](https://devdiv.visualstudio.com/_apis/public/build/definitions/0bdbc590-a062-4c3f-b0f6-9383f67865ee/5976/badge) |
 
 ## Get Started
+
 ### Prerequisite
+
 * [Application Insights for ASP.NET Core](https://github.com/Microsoft/ApplicationInsights-aspnetcore)
 * [Docker Containers](https://www.docker.com/)
 * [Kubernetes](https://kubernetes.io/)
 
-### Walkthrough
-We support **ASP.NET Core** application as well as **.NET Core** application.
+### Instrument an ASP.NET Core application
+
+These are the basic steps to instrument an ASP.NET Core application to enable Application Insights for Kubernetes. You will need to run the application in containers managed by Kubernetes to see the change.
+
+1. Add reference to **Application Insights SDK** and **Application Insights for Kubernetes**:
+
+    ```shell
+    dotnet add package Microsoft.ApplicationInsights.AspNetCore
+    dotnet add package Microsoft.ApplicationInsights.Kubernetes
+    ```
+
+1. Enable **Application Insights** and **Application Insights for Kubernetes Enricher** in `Startup.cs`:
+
+    ```csharp
+    public void ConfigureServices(IServiceCollection services)
+    {
+        ...
+        services.AddApplicationInsightsTelemetry("----Your Application Insights Instrumentation Key ----");
+        services.AddApplicationInsightsKubernetesEnricher();
+        services.AddMvc();
+        ...
+    }
+    ```
+
+1. Build the application in containers, then deploy the container with Kubernetes.
+
+**Notes:** Those steps are not considered the best practice to set the instrumentation key for application insights. Refer to [Enable Application Insights server-side telemetry](https://docs.microsoft.com/en-us/azure/azure-monitor/app/asp-net-core#enable-application-insights-server-side-telemetry-without-visual-studio) for various options. Also, consider deploy Kubernetes Secrets to secure it.
 
-* For **ASP.NET Core** Application: Refer [Getting Started](https://github.com/Microsoft/ApplicationInsights-Kubernetes/wiki/Getting-Started-for-ASP.NET-Core-Applications) for a simple walkthrough.
+### Walk-through
 
-* For **.NET Core** Application: Refer [Getting Started](https://github.com/Microsoft/ApplicationInsights-Kubernetes/wiki/Getting-Started-for-.NET-Core-Applications) for a simple walkthrough.
+Both **ASP.NET Core** and **.NET Core** applications are supported.
 
-* Follow [this example](examples/BasicUsage_clr21_RBAC) for Role-based access control (RBAC) enabled Kubernetes clusters.
+* For **ASP.NET Core** Application: Refer to [Getting Started](https://github.com/Microsoft/ApplicationInsights-Kubernetes/wiki/Getting-Started-for-ASP.NET-Core-Applications) for a simple walk-through.
+
+* For **.NET Core** Application: Refer to [Getting Started](examples/BasicConsoleAppILogger/README.md) for a simple walk-through.
+
+* Follow [this example](examples/BasicUsage_clr21_RBAC) for **Role-based access control (RBAC)** enabled Kubernetes clusters.
 
 ### Configuration Details
 
-Customize configurations are supported for `v1.0.2+`. There are several ways to customize the settings. For example:
+Customize configurations are supported starting with version 1.0.2 of the ApplicationInsights.Kubernetes package. There are several ways to customize the settings. For example:
+
+1. Using code:
 
-1. By the code:
     ```csharp
     services.AddApplicationInsightsKubernetesEnricher(option=> {
         option.InitializationTimeout = TimeSpan.FromSeconds(15);
     });
     ```
 
-2. By `appsettings.json`:
+2. Using `appsettings.json`:
+
     ```jsonc
     {
         "Logging": {
@@ -47,40 +81,48 @@ Customize configurations are supported for `v1.0.2+`. There are several ways to
         }
     }
     ```
-3. By environment varialbe:
-    ```
+
+3. Using environment variables:
+
+    ```shell
     AppInsightsForKubernetes__InitializationTimeout=3.1:12:15.34
     ```
 
     All the related configurations have to be put in a section named `AppInsightsForKubernetes`. The supported keys/values are listed below:
 
-    | Key                   | Value/Types | Default Value | Description                                                                                            |
-    |-----------------------|-------------|---------------|--------------------------------------------------------------------------------------------------------|
-    | InitializationTimeout | TimeSpan    | 00:02:00      |  Maximum time to wait for spinning up the container. Accepted format: [d.]hh:mm:ss[.fffffff]. |
+    | Key                   | Value/Types | Default Value | Description                                                                                  |
+    | --------------------- | ----------- | ------------- | -------------------------------------------------------------------------------------------- |
+    | InitializationTimeout | TimeSpan    | 00:02:00      | Maximum time to wait for spinning up the container. Accepted format: [d.]hh:mm:ss[.fffffff]. |
+
+The configuration uses the ASP.NET Core conventions. Refer to [Configuration in ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-2.1) for more information.
 
-The configuration uses with the conventions in ASP.NET Core. Refer [Configuration in ASP.NET Core](https://docs.microsoft.com/en-us/aspnet/core/fundamentals/configuration/?view=aspnetcore-2.1) for more information.
+### Verify the cluster configuration (Linux Container only)
 
-### Verify the cluster configuration
 Use the [troubleshooting image](https://github.com/Microsoft/ApplicationInsights-Kubernetes/tree/develop/troubleshooting) to verify the cluster is properly configured.
 
 ### Learn more
+
 * To build a container for Kubernetes that have Application Insights baked in for the existing applications, please refer the example of [Zero Code light up](https://github.com/Microsoft/ApplicationInsights-Kubernetes/tree/develop/examples/ZeroUserCodeLightup).
-* To enable Application Insights for Kubernetes by environement variable instead of code, please refer [Hosting startup for ApplicationInsights.Kubernetes](https://github.com/Microsoft/ApplicationInsights-Kubernetes/wiki/Hosting-startup-for-ApplicationInsights.Kubernetes).
+* To enable diagnostic logs when Application Insights for Kubernetes doesn't work as expected, reference [How to enable self diagnostics for ApplicationInsights.Kubernetes](docs/SelfDiagnostics.MD).
 * Still want more? Read the [Wikis](https://github.com/Microsoft/ApplicationInsights-Kubernetes/wiki).
 
 ### Next step
+
 Profile your application for performance improvement using [Application Insights Profiler for Linux](https://github.com/Microsoft/ApplicationInsights-Profiler-AspNetCore).
 
 ## Contributing
+
 ### Report issues
-Please file bug, discussion or any other interesting topics in [issues](https://github.com/Microsoft/ApplicationInsights-Kubernetes/issues) on github.
 
-### Trouble Shooting
-When Microsoft.ApplicationInsights.Kubernetes doesn't work properly, you can turn on self-diagnostics to see the traces in Kubernetes' logs. Refer [this wiki page](https://github.com/Microsoft/ApplicationInsights-Kubernetes/wiki/%5BAdvanced%5D-How-to-enable-self-diagnostics-for-ApplicationInsights.Kubernetes) for instructions to turn on trace.
+Please file bug, discussion or any other interesting topics in [issues](https://github.com/Microsoft/ApplicationInsights-Kubernetes/issues) on GitHub.
+
+### Troubleshooting
+
+When Microsoft.ApplicationInsights.Kubernetes doesn't work properly, you can turn on self-diagnostics to see the traces in Kubernetes' logs. Refer to [How to enable self diagnostics for ApplicationInsights.Kubernetes](./docs/SelfDiagnostics.md) for instructions.
 
 ### Developing
-Please refer the [Develop Guide](https://github.com/Microsoft/ApplicationInsights-Kubernetes/wiki/Development-Guide).
 
+Please refer the [Develop Guide](https://github.com/Microsoft/ApplicationInsights-Kubernetes/wiki/Development-Guide).
 
 ---
 This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

dev/.vscode/launch.json

@@ -0,0 +1,24 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": ".NET Core Launch - F5 WebApi",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "Build F5 WebApi",
+            "program": "${workspaceFolder}/F5WebApi/bin/Debug/netcoreapp2.2/F5WebApi.dll",
+            "args": [],
+            "cwd": "${workspaceFolder}/F5WebApi",
+            "stopAtEntry": false,
+            "launchBrowser": {
+                "enabled": true
+            },
+            "env": {
+                "ASPNETCORE_ENVIRONMENT": "Development"
+            }
+        }
+    ]
+}

dev/.vscode/tasks.json

@@ -0,0 +1,20 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "Build F5 WebApi",
+            "command": "dotnet build",
+            "type": "shell",
+            "group": "build",
+            "presentation": {
+                "reveal": "always"
+            },
+            "options": {
+                "cwd": "${workspaceFolder}/F5WebApi"
+            },
+            "problemMatcher": "$msCompile"
+        }
+    ]
+}

dev/F5WebApi/Controllers/ValuesController.cs

@@ -0,0 +1,45 @@
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Threading.Tasks;
+using Microsoft.AspNetCore.Mvc;
+
+namespace F5WebApi.Controllers
+{
+    [Route("api/[controller]")]
+    [ApiController]
+    public class ValuesController : ControllerBase
+    {
+        // GET api/values
+        [HttpGet]
+        public ActionResult<IEnumerable<string>> Get()
+        {
+            return new string[] { "value1", "value2" };
+        }
+
+        // GET api/values/5
+        [HttpGet("{id}")]
+        public ActionResult<string> Get(int id)
+        {
+            return "value";
+        }
+
+        // POST api/values
+        [HttpPost]
+        public void Post([FromBody] string value)
+        {
+        }
+
+        // PUT api/values/5
+        [HttpPut("{id}")]
+        public void Put(int id, [FromBody] string value)
+        {
+        }
+
+        // DELETE api/values/5
+        [HttpDelete("{id}")]
+        public void Delete(int id)
+        {
+        }
+    }
+}

dev/F5WebApi/F5WebApi.csproj

@@ -0,0 +1,17 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>netcoreapp2.2</TargetFramework>
+    <AspNetCoreHostingModel>InProcess</AspNetCoreHostingModel>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Microsoft.AspNetCore.App" />
+    <PackageReference Include="Microsoft.ApplicationInsights.AspNetCore" Version="2.7.0" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\ApplicationInsights.Kubernetes\ApplicationInsights.Kubernetes.csproj" />
+  </ItemGroup>
+
+</Project>

dev/F5WebApi/Program.cs

@@ -0,0 +1,17 @@
+using Microsoft.AspNetCore;
+using Microsoft.AspNetCore.Hosting;
+
+namespace F5WebApi
+{
+    public class Program
+    {
+        public static void Main(string[] args)
+        {
+            CreateHostBuilder(args).Build().Run();
+        }
+
+        public static IWebHostBuilder CreateHostBuilder(string[] args) =>
+            WebHost.CreateDefaultBuilder(args)
+                .UseStartup<Startup>();
+    }
+}

dev/F5WebApi/Properties/launchSettings.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "http://json.schemastore.org/launchsettings.json",
+  "iisSettings": {
+    "windowsAuthentication": false, 
+    "anonymousAuthentication": true, 
+    "iisExpress": {
+      "applicationUrl": "http://localhost:31345",
+      "sslPort": 44371
+    }
+  },
+  "profiles": {
+    "IIS Express": {
+      "commandName": "IISExpress",
+      "launchBrowser": true,
+      "launchUrl": "api/values",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "F5WebApi": {
+      "commandName": "Project",
+      "launchBrowser": true,
+      "launchUrl": "api/values",
+      "applicationUrl": "https://localhost:5001;http://localhost:5000",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

dev/F5WebApi/Startup.cs

@@ -0,0 +1,59 @@
+using System.Diagnostics;
+using Microsoft.ApplicationInsights.Kubernetes.Debugging;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Hosting;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace F5WebApi
+{
+    public class Startup
+    {
+        public Startup(IConfiguration configuration)
+        {
+            Configuration = configuration;
+        }
+
+        public IConfiguration Configuration { get; }
+
+        // This method gets called by the runtime. Use this method to add services to the container.
+        public void ConfigureServices(IServiceCollection services)
+        {
+            // To use this project for F5 debugging, follow these steps:
+
+            // Output the diagnostic source logs to the console.
+            var observer = new ApplicationInsightsKubernetesDiagnosticObserver(DiagnosticLogLevel.Trace);
+            ApplicationInsightsKubernetesDiagnosticSource.Instance.Observable.SubscribeWithAdapter(observer);
+
+            // Step 1. Set iKey in the parameter below.
+            services.AddApplicationInsightsTelemetry("your-instrumentation-key");
+
+            // Step 2. Call proper overloads of AddApplicationInsightsKubernetesEnricher.
+            services.AddApplicationInsightsKubernetesEnricher(applyOptions: null,
+                kubernetesServiceCollectionBuilder: KubernetesDebuggingServiceCollectionBuilderFactory.Instance.Create(),
+                detectKubernetes: () => true);
+            // Step 3. Set a break point and press F5.
+            // ~
+
+            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_2);
+        }
+
+        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
+        public void Configure(IApplicationBuilder app, IHostingEnvironment env)
+        {
+            if (env.IsDevelopment())
+            {
+                app.UseDeveloperExceptionPage();
+            }
+            else
+            {
+                // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
+                app.UseHsts();
+            }
+
+            app.UseHttpsRedirection();
+            app.UseMvc();
+        }
+    }
+}

dev/F5WebApi/appsettings.Development.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Debug",
+      "System": "Information",
+      "Microsoft": "Information"
+    }
+  }
+}