Merge pull request #3723 from hhunter-ms/upmerge_09-12

Upmerge 09/12

daprdocs/content/en/concepts/building-blocks-concept.md

@@ -6,15 +6,15 @@ weight: 200
 description: "Modular best practices accessible over standard HTTP or gRPC APIs"
 ---
 
-A [building block]({{< ref building-blocks >}}) is an HTTP or gRPC API that can be called from your code and uses one or more Dapr components.
-
-Building blocks address common challenges in building resilient, microservices applications and codify best practices and patterns. Dapr consists of a set of building blocks, with extensibility to add new building blocks.
+A [building block]({{< ref building-blocks >}}) is an HTTP or gRPC API that can be called from your code and uses one or more Dapr components. Dapr consists of a set of API building blocks, with extensibility to add new building blocks. Dapr's building blocks:
+- Address common challenges in building resilient, microservices applications 
+- Codify best practices and patterns
 
 The diagram below shows how building blocks expose a public API that is called from your code, using components to implement the building blocks' capability.
 
 <img src="/images/concepts-building-blocks.png" width=250>
 
-The following are the building blocks provided by Dapr:
+Dapr provides the following building blocks:
 
 <img src="/images/building_blocks.png" width=1200>
 
@@ -25,7 +25,6 @@ The following are the building blocks provided by Dapr:
 | [**Publish and subscribe**]({{< ref "pubsub-overview.md" >}}) | `/v1.0/publish` `/v1.0/subscribe`|  Pub/Sub is a loosely coupled messaging pattern where senders (or publishers) publish messages to a topic, to which subscribers subscribe. Dapr supports the pub/sub pattern between applications.
 | [**Bindings**]({{< ref "bindings-overview.md" >}}) | `/v1.0/bindings` | A binding provides a bi-directional connection to an external cloud/on-premise service or system. Dapr allows you to invoke the external service through the  Dapr binding API, and it allows your application to be triggered by events sent by the connected service.
 | [**Actors**]({{< ref "actors-overview.md" >}}) | `/v1.0/actors` |  An actor is an isolated, independent unit of compute and state with single-threaded execution. Dapr provides an actor implementation based on the virtual actor pattern which provides a single-threaded programming model and where actors are garbage collected when not in use.
-| [**Observability**]({{< ref "observability-concept.md" >}}) | `N/A` |  Dapr system components and runtime emit metrics, logs, and traces to debug, operate and monitor Dapr system services, components and user applications.
 | [**Secrets**]({{< ref "secrets-overview.md" >}}) | `/v1.0/secrets` | Dapr provides a secrets building block API and integrates with secret stores such as public cloud stores, local stores and Kubernetes to store the secrets. Services can call the secrets API to retrieve secrets, for example to get a connection string to a database.
 | [**Configuration**]({{< ref "configuration-api-overview.md" >}}) | `/v1.0/configuration` | The Configuration API enables you to retrieve and subscribe to application configuration items for supported configuration stores. This enables an application to retrieve specific configuration information, for example, at start up or when configuration changes are made in the store. 
 | [**Distributed lock**]({{< ref "distributed-lock-api-overview.md" >}}) | `/v1.0-alpha1/lock` | The distributed lock API enables you to take a lock on a resource so that multiple instances of an application can access the resource without conflicts and provide consistency guarantees.  

daprdocs/content/en/concepts/components-concept.md

@@ -11,14 +11,18 @@ Dapr uses a modular design where functionality is delivered as a component. Each
 You can contribute implementations and extend Dapr's component interfaces capabilities via:
 
 - The [components-contrib repository](https://github.com/dapr/components-contrib)
-- [Pluggable components]({{<ref "components-concept.md#built-in-and-pluggable-components" >}}).
+- [Pluggable components]({{< ref "components-concept.md#built-in-and-pluggable-components" >}}).
 
 A building block can use any combination of components. For example, the [actors]({{< ref "actors-overview.md" >}}) and the [state management]({{< ref "state-management-overview.md" >}}) building blocks both use [state components](https://github.com/dapr/components-contrib/tree/master/state).
 
 As another example, the [pub/sub]({{< ref "pubsub-overview.md" >}}) building block uses [pub/sub components](https://github.com/dapr/components-contrib/tree/master/pubsub).
 
 You can get a list of current components available in the hosting environment using the `dapr components` CLI command.
 
+{{% alert title="Note" color="primary" %}} 
+For any component that returns data to the app, it is recommended to set the memory capacity of the Dapr sidecar accordingly (process or container) to avoid potential OOM panics. For example in Docker use the `--memory` option. For Kubernetes, use the `dapr.io/sidecar-memory-limit` annotation. For processes this depends on the OS and/or process orchestration tools.*
+{{% /alert %}}
+
 ## Component specification
 
 Each component has a specification (or spec) that it conforms to. Components are configured at design-time with a YAML file which is stored in either:

daprdocs/content/en/concepts/dapr-services/sidecar.md

@@ -49,25 +49,31 @@ For a detailed list of all available arguments run `daprd --help` or see this [t
    daprd --app-id myapp
    ```
 
-2. Specify the port your application is listening to
+1. Specify the port your application is listening to
 
    ```bash
    daprd --app-id --app-port 5000
    ```
 
-3. If you are using several custom resources and want to specify the location of the resource definition files, use the `--resources-path` argument:
+1. If you are using several custom resources and want to specify the location of the resource definition files, use the `--resources-path` argument:
 
    ```bash
    daprd --app-id myapp --resources-path <PATH-TO-RESOURCES-FILES>
    ```
 
-4. Enable collection of Prometheus metrics while running your app
+1. If you've organized your components and other resources (for example, resiliency policies, subscriptions, or configuration) into separate folders or a shared folder, you can specify multiple resource paths:
+
+   ```bash
+   daprd --app-id myapp --resources-path <PATH-1-TO-RESOURCES-FILES> --resources-path <PATH-2-TO-RESOURCES-FILES>
+   ```
+
+1. Enable collection of Prometheus metrics while running your app
 
    ```bash
    daprd --app-id myapp --enable-metrics
    ```
 
-5. Listen to IPv4 and IPv6 loopback only
+1. Listen to IPv4 and IPv6 loopback only
 
    ```bash
    daprd --app-id myapp --dapr-listen-addresses '127.0.0.1,[::1]'

daprdocs/content/en/concepts/observability-concept.md

@@ -27,7 +27,7 @@ Maintaining this instrumentation code, which is not part of the core logic of th
 
 ## Observability for your application with Dapr
 
-When you leverage Dapr API building blocks to perform service-to-service calls and pub/sub messaging, Dapr offers an advantage with respect to [distributed tracing]({{< ref develop-tracing >}}). Since this inter-service communication flows through the Dapr runtime (or "sidecar"), Dapr is in a unique position to offload the burden of application-level instrumentation.
+When you leverage Dapr API building blocks to perform service-to-service calls, pub/sub messaging, and other APIs, Dapr offers an advantage with respect to [distributed tracing]({{< ref tracing >}}). Since this inter-service communication flows through the Dapr runtime (or "sidecar"), Dapr is in a unique position to offload the burden of application-level instrumentation.
 
 ### Distributed tracing
 
@@ -37,7 +37,7 @@ Dapr can be [configured to emit tracing data]({{< ref setup-tracing.md >}}) usin
 
 ### Automatic tracing context generation
 
-Dapr uses [W3C tracing]({{< ref w3c-tracing-overview >}}) specification for tracing context, included as part Open Telemetry (OTEL), to generate and propagate the context header for the application or propagate user-provided context headers. This means that you get tracing by default with Dapr.
+Dapr uses the [W3C tracing]({{< ref tracing >}}) specification for tracing context, included as part Open Telemetry (OTEL), to generate and propagate the context header for the application or propagate user-provided context headers. This means that you get tracing by default with Dapr.
 
 ## Observability for the Dapr sidecar and control plane
 
@@ -54,7 +54,7 @@ Dapr generates [logs]({{< ref logs.md >}}) to:
 - Provide visibility into sidecar operation 
 - Help users identify issues and perform debugging
 
-Log events contain warning, error, info, and debug messages produced by Dapr system services. You can also configure Dapr to send logs to collectors, such as Open Telemetry Collector, [Fluentd]({{< ref fluentd.md >}}), [New Relic]({{< ref "operations/monitoring/logging/newrelic.md" >}}), [Azure Monitor]({{< ref azure-monitor.md >}}), and other observability tools, so that logs can be searched and analyzed to provide insights.
+Log events contain warning, error, info, and debug messages produced by Dapr system services. You can also configure Dapr to send logs to collectors, such as [Open Telemetry Collector]({{< ref otel-collector >}}), [Fluentd]({{< ref fluentd.md >}}), [New Relic]({{< ref "operations/observability/logging/newrelic.md" >}}), [Azure Monitor]({{< ref azure-monitor.md >}}), and other observability tools, so that logs can be searched and analyzed to provide insights.
 
 ### Metrics
 
@@ -70,5 +70,5 @@ Conversely, Dapr can be configured to probe for the [health of your application]
 
 ## Next steps
 
-- [Learn more about observability in developing with Dapr]({{< ref develop-tracing >}})
+- [Learn more about observability in developing with Dapr]({{< ref tracing >}})
 - [Learn more about observability in operating with Dapr]({{< ref tracing >}})