concept doc updates (#74)

* concept doc updates

* fix typo

concepts/README.md

@@ -1,22 +1,45 @@
-# Dapr concepts
+# Dapr concepts
-
+
-This directory contains various Dapr concepts. The goal of these documents is to expand your knowledge on the [Dapr spec](https://github.com/dapr/spec). 
+This directory contains various Dapr concepts. The goal of these documents is to expand your knowledge on the [Dapr spec](https://github.com/dapr/spec). 
-
+
-
+## Core Concepts
-## Core Concepts
+
-
+* [**Bindings**](./bindings/Readme.md)
-* [Terminology](./terminology/terminology.md)
+  
-* [Bindings](./bindings/Readme.md)
+  A binding provides defines a bi-directional connection to an external cloud/on-premise service or system. Dapr allows you to invoke the external service through the standard Dapr binding API, and it allows your application to be triggered by events snet by the connected service.
-* [Pub-sub](./publish-subscribe-messaging/Readme.md)
+
-* [Secrets](./components/secrets.md)
+* **Components**
-* [State](./state-management/state-management.md)
+  
-* [Tracing](./tracing-logging/tracing-logging.md)
+  Dapr uses a modular design, in which functionalities are grouped and delivered by a number of *components*, such as  [pub-sub](./components/redis.md) and [secrets](./components/secrets.md). Many of the components are pluggable so that you can swap out the default implemenation with your custom implementations. 
-
+
-## Actors
+* [**Distributed Tracing**](./tracing-logging/tracing-logging.md)
-
+
-* [Overview](./actor/actor_overview.md)
+  Distirbuted tracing collects and aggregates trace events by transactions. It allows you to trace the entire call chain across multiple services. Dapr integrates with [OpenTelemetry](https://opentelemetry.io/) for distributed tracing and metrics collection. 
-* [Features](./actor/actors_features.md)
+
-
+* [**Pub-sub**](./publish-subscribe-messaging/pub-sub-messaging.md)
-## Extensibility
+  
-
+  Pub-sub is a loosely coupled messaging pattern where senders (or publishers) publishes messages to a topic, to which subscribers subscribe. Dapr natively supports the pub-sub pattern.
-* [Redis](./components/redis.md)
+
+* [**Secrets**](./components/secrets.md)
+
+  In Dapr, a secret is any piece of private information that you want to guard against unwanted users. Dapr offers a simple secret API and integrates with secret stores such as Azure Key Vault and Kubernetes secret stores to store the secrets.
+
+* [**State**](./state-management/state-management.md)
+
+  Application state is anything an application wants to perserve beyound a single session. Dapr allows pluggable state stores behind a key/value-based state API.
+
+* [Terminology](./terminology/terminology.md)
+* [Bindings](./bindings/Readme.md)
+* [Pub-sub](./publish-subscribe-messaging/Readme.md)
+* [Secrets](./components/secrets.md)
+* [State](./state-management/state-management.md)
+* [Tracing](./tracing-logging/tracing-logging.md)
+
+## Actors
+
+* [Overview](./actor/actor_overview.md)
+* [Features](./actor/actors_features.md)
+
+## Extensibility
+
+* [Redis](./components/redis.md)

concepts/state-management/state-management.md

@@ -83,5 +83,7 @@ SELECT AVG(value) FROM StateTable WHERE Id LIKE '<dapr-id>-<therometer>-*-temper
 ## References
 * [Spec: Dapr state managment specification](https://github.com/dapr/spec/blob/master/state.md)
 * [Spec: Dapr actors specification](https://github.com/dapr/spec/blob/master/actors.md)
-* [How-to: Query Redis store](../../howto/query-state-store/query-redis-store.md) 
+* [How-to: Set up Azure Cosmos DB store](../../howto/setup-state-store/setup-azure-cosmosdb.md)
 * [How-to: Query Azure Cosmos DB store](../../howto/query-state-store/query-cosmosdb-store.md) 
+* [How-to: Set up Redis store](../../howto/setup-state-store/setup-redis.md)
+* [How-to: Query Redis store](../../howto/query-state-store/query-redis-store.md) 

concepts/terminology/terminology.md

@@ -1,3 +0,0 @@
-# documentation 
-
-Content for this file to be added

concepts/tracing-logging/tracing-logging.md

@@ -1,3 +1,41 @@
-# documentation 
+# Distributed tracing 
+
+Dapr uses OpenTelemetry (previously known as OpenCensus) for distributed traces and metrics collection. OpenTelemetry supports various backends including [Azure Monitor](https://azure.microsoft.com/en-us/services/monitor/), [Datadog](https://www.datadoghq.com), [Instana](https://www.instana.com), [Jaeger](https://www.jaegertracing.io/), [SignalFX](https://www.signalfx.com/), [Stackdriver](https://cloud.google.com/stackdriver), [Zipkin](https://zipkin.io) and others. 
+
+![Tracing](../../images/tracing.png)
+
+# Tracing Design
+
+Dapr adds a HTTP/grPC middleware to the Dapr sidecar. The middleware intercepts all Dapr and application traffic and automatically injects correlation IDs to trace distributed transactions. This design has several benifits:
+
+* No need for code instrumentation. All traffic is automatically traced (with configurable tracing levels).
+* Consistent tracing behavior across microservices. Tracing a configured and managed on Dapr sidecar so that it remains consistent across services made by different teams and potentially written in different programming languages.
+* Configurable and extensible. By leveraging OpenTelemetry, Dapr tracing can be configured to work with popular tracing backends, including custom backends a customer may have.
+
+# Correlation ID
+
+For HTTP requests, Dapr injects a **X-Correlation-ID** header to requests. For gRPC calls, Dapr inserts a **X-Correlation-ID** as a field of a **header** metadata. When a request arrives without an correlation ID, Dapr creates a new one. Otherwise, it passes the correlation ID along the call chain.
+
+# Configuration
+
+Dapr tracing is configured by a configuration file (in local mode) or a Kubernetes configuration object (in Kubernetes mode). For example, to define a Zipkin exporter, define the following configuration object:
+
+```yaml
+apiVersion: actions.io/v1alpha1
+kind: Configuration
+metadata:
+  name: zipkin
+spec:
+  tracing:
+    enabled: true
+    exporterType: zipkin
+    exporterAddress: "http://zipkin.default.svc.cluster.local:9411/api/v2/spans"
+    expandParams: true
+    includeBody: true
+```
+
+Please see the [References](#references) section for more details on how to configure tracing on local environment and Kubernetes environment.
+
+# References
+* [How-to: set up distributed tracing](../../howto/diagnose-with-tracing/readme.md)
 
-Content for this file to be added

howto/diagnose-with-tracing/Readme.md

@@ -0,0 +1,120 @@
+# Set up distributed tracing
+
+Dapr integrates seamlessly with OpenTelemetry for telemtry and tracing. It is recommended to run Dapr with tracing enabled for any production scenario. Since Dapr uses OpenTelemetry, you can configure various exporters for tracing and telemtry data based on your environment, whether it is running in the cloud or on-premises.
+
+## How to configure distributed tracing with Zipkin on Kubernetes
+
+The following steps will show you how to configure Dapr to send distributed tracing data to Zipkin running as a container in your Kubernetes cluster, and how to view them.
+
+
+### Setup
+
+First, deploy Zipkin:
+
+```
+kubectl run zipkin --image openzipkin/zipkin --port 9411
+```
+
+Create a Kubernetes Service for the Zipkin pod:
+
+```
+kubectl expose deploy zipkin --type ClusterIP --port 9411
+```
+
+Next, create the following YAML file locally:
+
+```
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+  name: zipkin
+spec:
+  tracing:
+    enabled: true
+    exporterType: zipkin
+    exporterAddress: "http://zipkin.default.svc.cluster.local:9411/api/v2/spans"
+    expandParams: true
+    includeBody: true
+```
+
+Finally, deploy the Dapr configuration:
+
+```
+kubectl apply -f config.yaml
+```
+
+In order to enable this configuration for your Dapr sidecar, add the following annotation to your pod spec template:
+
+```
+annotations:
+  dapr.io/config: "zipkin"
+```
+
+That's it! your sidecar is now configured for use with Open Census and Zipkin.
+
+### Viewing Tracing Data
+
+To view traces, connect to the Zipkin Service and open the UI:
+
+```
+kubectl port-forward svc/zipkin 9411:9411
+```
+
+On your browser, go to ```http://localhost:9411``` and you should see the Zipkin UI.
+
+![zipkin](../../images/zipkin_ui.png)
+
+## How to configure distributed tracing with Zipkin when running in stand-alone mode
+
+For standalone mode, create an Dapr Configuration CRD file locally and reference it with the Dapr CLI.
+
+1. Create the following YAML file:
+
+```
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+  name: zipkin
+spec:
+  tracing:
+    enabled: true
+    exporterType: zipkin
+    exporterAddress: "http://localhost:9411/api/v2/spans"
+    expandParams: true
+    includeBody: true
+```
+
+2. Launch Zipkin using Docker:
+
+```
+docker run -d -p 9411:9411 openzipkin/zipkin
+```
+
+3. Launch Dapr with the `--config` param:
+
+```
+dapr run --app-id mynode --app-port 3000 --config ./cofig.yaml node app.js
+```
+
+## Tracing Configuration
+
+The `tracing` section under the `Configuration` spec contains the following properties:
+
+```
+tracing:
+    enabled: true
+    exporterType: zipkin
+    exporterAddress: ""
+    expandParams: true
+    includeBody: true
+```
+
+The following table lists the different properties.
+
+Property | Type | Description
+---- | ------- | -----------
+enabled  | bool | Set tracing to be enabled or disabled
+exporterType  | string | Name of the Open Census exporter to use. For example: Zipkin, Azure Monitor, etc
+exporterAddress  | string | URL of the exporter
+expandParams  | bool | When true, expands parameters passed to HTTP endpoints
+includeBody  | bool | When true, includes the request body in the tracing event

howto/diagnose-with-tracing/setup-development-environment.md

@@ -1,3 +0,0 @@
-# documentation 
-
-Content for this file to be added

howto/diagnose-with-tracing/setup-kubernetes-environment.md

@@ -1,3 +0,0 @@
-# documentation 
-
-Content for this file to be added