Merge pull request #440 from dapr/youngp/lf

Improve appinsight distributed trace setup guide and add deployment yamls

howto/diagnose-with-tracing/azure-monitor.md

@@ -1,28 +1,39 @@
-# Set up distributed tracing with Azure Monitor
+# Set up distributed tracing with Application insights
 
-Dapr integrates with Application Monitor through OpenTelemetry's default exporter along with a dedicated agent known as [Local Forwarder](https://docs.microsoft.com/en-us/azure/azure-monitor/app/opencensus-local-forwarder).
+Dapr integrates with Application Insights through OpenTelemetry's default exporter along with a dedicated agent known as [Local Forwarder](https://docs.microsoft.com/en-us/azure/azure-monitor/app/opencensus-local-forwarder).
 
-## How to configure distributed tracing with Azure Monitor
+> Note: Local forwarder is still under preview, but being deprecated. Application insights team recommends to use [Opentelemetry collector](https://github.com/open-telemetry/opentelemetry-collector) (which is in alpha state) for the future so that we're working on moving from local forwarder to [Opentelemetry collector](https://github.com/open-telemetry/opentelemetry-collector).
 
-The following steps will show you how to configure Dapr to send distributed tracing data to Azure Monitor.
+## How to configure distributed tracing wit Application insights
 
-### Setup Azure Monitor
+The following steps will show you how to configure Dapr to send distributed tracing data to Application insights.
+
+### Setup Application insights
 
 1. First, you'll need an Azure account. Please see instructions [here](https://azure.microsoft.com/free/) to apply for a **free** Azure account.
 2. Follow instructions [here](https://docs.microsoft.com/en-us/azure/azure-monitor/app/create-new-resource) to create a new Application Insights resource.
+3. Get Application insights Intrumentation key from your application insights page
+4. Go to `Configure -> API Access`
+5. Click `Create API Key`
+6. Select all checkboxes under `Choose what this API key will allow apps to do:`
+   - Read telemetry
+   - Write annotations
+   - Authenticate SDK control channel
+7. Generate Key and get API key
 
 ### Setup the Local Forwarder
 
-The Local Forwarder listens to OpenTelemetry's traces through
+#### Local environment
-Please follow the insturctions [here](https://docs.microsoft.com/en-us/azure/azure-monitor/app/opencensus-local-forwarder) to setup Local Forwarder as a local service or daemon.
 
-> **NOTE**: At the time of writing, there's no official guidance on packaging and running the Local Forwarder as a Docker container. To use Local Forwarder on Kubernetes, you'll need to package the Local Forwarder as a Docker container and register a *ClusterIP* service. Then, you should set the service as the export target of the native exporter.
+1. Run localfowarder
 
-### How to configure distributed tracing with Azure Monitor
+```bash
+docker run -e APPINSIGHTS_INSTRUMENTATIONKEY=<Your Instrumentation Key> -e APPINSIGHTS_LIVEMETRICSSTREAMAUTHENTICATIONAPIKEY=<Your API Key> -d -p 55678:55678 daprio/dapr-localforwarder:0.1-beta1
+```
 
-You'll need two YAML files - a Dapr configuration file that enables tracing, and a native export configuration file that configures the native exporter.
+> Note: dapr-localforwarder is created by using [0.1-beta1 release](https://github.com/microsoft/ApplicationInsights-LocalForwarder/releases/tag/v0.1-beta1). If you want to create your own image, please use [this dockerfile](./localforwarder/Dockerfile).
 
-1. Create the following YAML files:
+1. Copy *tracing.yaml* to a *components* folder under the same folder where you run you application. 
 
 * native.yaml
 
@@ -37,7 +48,7 @@ spec:
   - name: enabled
     value: "true"
   - name: agentEndpoint
-    value: "<Local forwarder address, for example: 50.140.60.170:6789>"
+    value: "localhost:55678"
 ```
 
 * tracing.yaml
@@ -54,19 +65,70 @@ spec:
     includeBody: true
 ```
 
-2. When running under local mode, copy *tracing.yaml* to a *components* folder under the same folder where you run you application. When running under Kubernetes model, use kubectl to apply the above CRD files:
-
-```bash
-kubectl apply -f tracing.yaml
-kubectl apply -f native.yaml
-```
-
 3. When running in the local mode, you need to launch Dapr with the `--config` parameter:
 
 ```bash
 dapr run --app-id mynode --app-port 3000 --config ./tracing.yaml node app.js
 ```
 
+#### Kubernetes environment
+
+1. Download [dapr-localforwarder.yaml](./localforwarder/dapr-localforwarder.yaml)
+2. Replace `<APPINSIGHT INSTRUMENTATIONKEY>` with your Instrumentation Key and `<APPINSIGHT API KEY>` with the generated key in the file
+
+```yaml
+          - name: APPINSIGHTS_INSTRUMENTATIONKEY
+            value: <APPINSIGHT INSTRUMENTATIONKEY> # Replace with your ikey
+          - name: APPINSIGHTS_LIVEMETRICSSTREAMAUTHENTICATIONAPIKEY
+            value: <APPINSIGHT API KEY> # Replace with your generated api key
+```
+
+3. Deploy dapr-localfowarder.yaml
+
+```bash
+kubectl apply -f ./dapr-localforwarder.yaml
+```
+
+4. Create the following YAML files
+
+* native.yaml
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: native
+spec:
+  type: exporters.native
+  metadata:
+  - name: enabled
+    value: "true"
+  - name: agentEndpoint
+    value: "<Local forwarder address, e.g. dapr-localforwarder.default.svc.cluster.local:55678>"
+```
+
+* tracing.yaml
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+  name: tracing
+spec:
+  tracing:
+    enabled: true
+    expandParams: true
+    includeBody: true
+```
+
+5. Use kubectl to apply the above CRD files:
+
+```bash
+kubectl apply -f tracing.yaml
+kubectl apply -f native.yaml
+```
+
+6. Deploy your app with tracing
 When running in the Kubernetes model, you need to add a `dapr.io/config` annotation to your container that you want to participate in the distributed tracing, as shown in the following example:
 
 ```yaml
@@ -92,7 +154,7 @@ That's it! There's no need include any SDKs or instrument your application code
 
 Generate some workloads. And after a few minutes, you should see tracing logs appearing in your Application Insights resource. And you can also use **Application map** to examine the topology of your services, as shown below:
 
-![Azure Monitor screen](../../images/azure-monitor.png)
+![Application map](../../images/azure-monitor.png)
 
 ## Tracing Configuration
 

howto/diagnose-with-tracing/localforwarder/Dockerfile

@@ -0,0 +1,8 @@
+FROM mcr.microsoft.com/dotnet/core/runtime:2.1
+RUN mkdir /lf
+WORKDIR /lf
+RUN curl -LsO https://github.com/microsoft/ApplicationInsights-LocalForwarder/releases/download/v0.1-beta1/LF-ConsoleHost-linux-x64.tar.gz
+RUN tar xzf LF-ConsoleHost-linux-x64.tar.gz
+RUN rm -f LF-ConsoleHost-linux-x64.tar.gz
+EXPOSE 55678
+ENTRYPOINT ["/lf/Microsoft.LocalForwarder.ConsoleHost", "noninteractive"]

howto/diagnose-with-tracing/localforwarder/appinsight-tracing.yaml

@@ -0,0 +1,23 @@
+---
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+  name: tracing
+spec:
+  tracing:
+    enabled: true
+    expandParams: true
+    includeBody: true
+---
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: native
+spec:
+  type: exporters.native
+  metadata:
+  - name: enabled
+    value: "true"
+  - name: agentEndpoint
+    value: dapr-localforwarder.default.svc.cluster.local:55678
+---

howto/diagnose-with-tracing/localforwarder/dapr-localforwarder.yaml

@@ -0,0 +1,42 @@
+kind: Service
+apiVersion: v1
+metadata:
+  name: dapr-localforwarder
+  labels:
+    app: dapr-localforwarder
+spec:
+  selector:
+    app: dapr-localforwarder
+  ports:
+  - protocol: TCP
+    port: 55678
+    targetPort: 55678
+  type: ClusterIP
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: dapr-localforwarder
+  labels:
+    app: dapr-localforwarder
+spec:
+  replicas: 3 # Adjust replica # based on your telemetry volume
+  selector:
+    matchLabels:
+      app: dapr-localforwarder
+  template:
+    metadata:
+      labels:
+        app: dapr-localforwarder
+    spec:
+      containers:
+      - name: dapr-localforwarder
+        image: docker.io/daprio/dapr-localforwarder:0.1-beta1
+        ports:
+        - containerPort: 55678
+        imagePullPolicy: Always
+        env:
+          - name: APPINSIGHTS_INSTRUMENTATIONKEY
+            value: <APPINSIGHT INSTRUMENTATIONKEY> # Replace with your ikey
+          - name: APPINSIGHTS_LIVEMETRICSSTREAMAUTHENTICATIONAPIKEY
+            value: <APPINSIGHT API KEY> # Replace with your generated api key