Skip to content

Commit

Permalink
Merge pull request #3627 from hhunter-ms/upmerge_07-24
Browse files Browse the repository at this point in the history
Upmerge 07/24
  • Loading branch information
hhunter-ms authored Jul 24, 2023
2 parents 1a1f044 + 675b333 commit 599670a
Show file tree
Hide file tree
Showing 111 changed files with 1,973 additions and 831 deletions.
118 changes: 118 additions & 0 deletions .github/scripts/algolia.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,118 @@
import os
from re import S
import sys
import json
from bs4 import BeautifulSoup
from algoliasearch.search_client import SearchClient

url = "docs.dapr.io"
if len(sys.argv) > 1:
starting_directory = os.path.join(os.getcwd(), str(sys.argv[1]))
else:
starting_directory = os.getcwd()

ALGOLIA_APP_ID = os.getenv('ALGOLIA_APP_ID')
ALGOLIA_API_KEY = os.getenv('ALGOLIA_API_WRITE_KEY')
ALGOLIA_INDEX_NAME = os.getenv('ALGOLIA_INDEX_NAME')

client = SearchClient.create(ALGOLIA_APP_ID, ALGOLIA_API_KEY)
index = client.init_index(ALGOLIA_INDEX_NAME)

excluded_files = [
"404.html",
]

exluded_directories = [
"zh-hans",
]

rankings = {
"Getting started": 0,
"Concepts": 100,
"Developing applications": 200,
"Operations": 300,
"Reference": 400,
"Contributing": 500,
"Home": 600
}

def scan_directory(directory: str, pages: list):
if os.path.basename(directory) in exluded_directories:
print(f'Skipping directory: {directory}')
return
for file in os.listdir(directory):
path = os.path.join(directory, file)
if os.path.isfile(path):
if file.endswith(".html") and file not in excluded_files:
if '<!-- DISABLE_ALGOLIA -->' not in open(path, encoding="utf8").read():
print(f'Indexing: {path}')
pages.append(path)
else:
print(f'Skipping hidden page: {path}')
else:
scan_directory(path, pages)

def parse_file(path: str):
data = {}
data["hierarchy"] = {}
data["rank"] = 999
data["subrank"] = 99
data["type"] = "lvl2"
data["lvl0"] = ""
data["lvl1"] = ""
data["lvl2"] = ""
data["lvl3"] = ""
text = ""
subrank = 0
with open(path, "r", errors='ignore') as file:
content = file.read()
soup = BeautifulSoup(content, "html.parser")
for meta in soup.find_all("meta"):
if meta.get("name") == "description":
data["lvl2"] = meta.get("content")
data["hierarchy"]["lvl1"] = meta.get("content")
elif meta.get("property") == "og:title":
data["lvl0"] = meta.get("content")
data["hierarchy"]["lvl0"] = meta.get("content")
data["hierarchy"]["lvl2"] = meta.get("content")
elif meta.get("property") == "og:url":
data["url"] = meta.get("content")
data["path"] = meta.get("content").split(url)[1]
data["objectID"] = meta.get("content").split(url)[1]
breadcrumbs = soup.find_all("li", class_="breadcrumb-item")
try:
subrank = len(breadcrumbs)
data["subrank"] = subrank
except:
subrank = 99
data["subrank"] = 99
for bc in breadcrumbs:
section = bc.text.strip()
data["lvl1"] = section
data["hierarchy"]["lvl0"] = section
try:
data["rank"] = rankings[section] + subrank
except:
print(f"Rank not found for section {section}")
data["rank"] = 998
break
for p in soup.find_all("p"):
if p.text != "":
text = text + p.text
data["text"] = text
return data

def index_payload(payload):
res = index.replace_all_objects(payload)
res.wait()


if __name__ == "__main__":
pages = []
payload = []
scan_directory(starting_directory, pages)
for page in pages:
data = parse_file(page)
if "objectID" in data:
payload.append(data)
index_payload(payload)
56 changes: 18 additions & 38 deletions daprdocs/assets/scss/_code.scss
Original file line number Diff line number Diff line change
@@ -1,64 +1,44 @@
// Code formatting.

.copy-code-button {
color: #272822;
background-color: #FFF;
border-color: #0D2192;
border: 2px solid;
border-radius: 3px 3px 0px 0px;

/* right-align */
display: block;
margin-left: auto;
margin-right: 0;

margin-bottom: -2px;
padding: 3px 8px;
font-size: 0.8em;
.highlight .copy-icon {
position: absolute;
right: 20px;
top: 18px;
opacity: 0.7;
}

.copy-code-button:hover {
cursor: pointer;
background-color: #F2F2F2;
}

.copy-code-button:focus {
/* Avoid an ugly focus outline on click in Chrome,
but darken the button for accessibility.
See https://stackoverflow.com/a/25298082/1481479 */
background-color: #E6E6E6;
outline: 0;
}

.copy-code-button:active {
background-color: #D9D9D9;
}

.highlight pre {
/* Avoid pushing up the copy buttons. */
margin: 0;
}

.td-content {
// Highlighted code.

// Highlighted code.
.highlight {
@extend .card;

margin: 0rem 0;
padding: 0rem;

margin-bottom: 2rem;

max-width: 100%;


border: none;

pre {
margin: 0;
padding: 1rem;
border-radius: 10px;
}
}

// Inline code
p code, li > code, table code {
p code,
li>code,
table code {
color: inherit;
padding: 0.2em 0.4em;
margin: 0;
Expand All @@ -78,11 +58,11 @@
word-wrap: normal;
background-color: $gray-100;
padding: $spacer;

max-width: 100%;

> code {
background-color: inherit !important;
>code {
background-color: inherit !important;
padding: 0;
margin: 0;
font-size: 100%;
Expand Down
21 changes: 0 additions & 21 deletions daprdocs/config.toml
Original file line number Diff line number Diff line change
Expand Up @@ -206,27 +206,6 @@ url_latest_version = "https://docs.dapr.io"
[[params.versions]]
version = "v1.3"
url = "https://v1-3.docs.dapr.io"
[[params.versions]]
version = "v1.2"
url = "https://v1-2.docs.dapr.io"
[[params.versions]]
version = "v1.1"
url = "https://v1-1.docs.dapr.io"
[[params.versions]]
version = "v1.0"
url = "https://v1-0.docs.dapr.io"
[[params.versions]]
version = "v0.11"
url = "https://v0-11.docs.dapr.io"
[[params.versions]]
version = "v0.10"
url = "https://github.com/dapr/docs/tree/v0.10.0"
[[params.versions]]
version = "v0.9"
url = "https://github.com/dapr/docs/tree/v0.9.0"
[[params.versions]]
version = "v0.8"
url = "https://github.com/dapr/docs/tree/v0.8.0"

# UI Customization
[params.ui]
Expand Down
48 changes: 37 additions & 11 deletions daprdocs/content/en/concepts/observability-concept.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,42 +7,68 @@ description: >
Observe applications through tracing, metrics, logs and health
---

When building an application, understanding how the system is behaving is an important part of operating it - this includes having the ability to observe the internal calls of an application, gauging its performance and becoming aware of problems as soon as they occur. This is challenging for any system, but even more so for a distributed system comprised of multiple microservices where a flow, made of several calls, may start in one microservice but continue in another. Observability is critical in production environments, but also useful during development to understand bottlenecks, improve performance and perform basic debugging across the span of microservices.
When building an application, understanding the system behavior is an important, yet challenging part of operating it, such as:
- Observing the internal calls of an application
- Gauging its performance
- Becoming aware of problems as soon as they occur

While some data points about an application can be gathered from the underlying infrastructure (for example memory consumption, CPU usage), other meaningful information must be collected from an "application-aware" layer–one that can show how an important series of calls is executed across microservices. This usually means a developer must add some code to instrument an application for this purpose. Often, instrumentation code is simply meant to send collected data such as traces and metrics to observability tools or services that can help store, visualize and analyze all this information.
This can be particularly challenging for a distributed system comprised of multiple microservices, where a flow made of several calls may start in one microservice and continue in another.

Having to maintain this code, which is not part of the core logic of the application, is a burden on the developer, sometimes requiring understanding the observability tools' APIs, using additional SDKs etc. This instrumentation may also add to the portability challenges of an application, which may require different instrumentation depending on where the application is deployed. For example, different cloud providers offer different observability tools and an on-premises deployment might require a self-hosted solution.
Observability into your application is critical in production environments, and can be useful during development to:
- Understand bottlenecks
- Improve performance
- Perform basic debugging across the span of microservices

While some data points about an application can be gathered from the underlying infrastructure (memory consumption, CPU usage), other meaningful information must be collected from an "application-aware" layer – one that can show how an important series of calls is executed across microservices. Typically, you'd add some code to instrument an application, which simply sends collected data (such as traces and metrics) to observability tools or services that can help store, visualize, and analyze all this information.

Maintaining this instrumentation code, which is not part of the core logic of the application, requires understanding the observability tools' APIs, using additional SDKs, etc. This instrumentation may also present portability challenges for your application, requiring different instrumentation depending on where the application is deployed. For example:
- Different cloud providers offer different observability tools
- An on-premises deployment might require a self-hosted solution

## Observability for your application with Dapr

When building an application which leverages Dapr API building blocks to perform service-to-service calls and pub/sub messaging, Dapr offers an advantage with respect to [distributed tracing]({{<ref tracing>}}). Because 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 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.

### Distributed tracing

Dapr can be [configured to emit tracing data]({{<ref setup-tracing.md>}}), and because Dapr does so using the widely adopted protocols of [Open Telemetry (OTEL)](https://opentelemetry.io/) and [Zipkin](https://zipkin.io), it can be easily integrated with multiple observability tools.
Dapr can be [configured to emit tracing data]({{< ref setup-tracing.md >}}) using the widely adopted protocols of [Open Telemetry (OTEL)](https://opentelemetry.io/) and [Zipkin](https://zipkin.io). This makes it easily integrated with multiple observability tools.

<img src="/images/observability-tracing.png" width=1000 alt="Distributed tracing with Dapr">

### 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 [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.

## Observability for the Dapr sidecar and control plane

You also want to be able to observe Dapr itself, by collecting metrics on performance, throughput and latency and logs emitted by the Dapr sidecar, as well as the Dapr control plane services. Dapr sidecars have a health endpoint that can be probed to indicate their health status.
You can also observe Dapr itself, by:
- Generating logs emitted by the Dapr sidecar and the Dapr control plane services
- Collecting metrics on performance, throughput, and latency
- Using health endpoints probes to indicate the Dapr sidecar health status

<img src="/images/observability-sidecar.png" width=1000 alt="Dapr sidecar metrics, logs and health checks">

### Logging

Dapr generates [logs]({{<ref "logs.md">}}) to provide visibility into sidecar operation and to help users identify issues and perform debugging. Log events contain warning, error, info, and debug messages produced by Dapr system services. Dapr can also be configured to send logs to collectors such as [Fluentd]({{< ref fluentd.md >}}), [Azure Monitor]({{< ref azure-monitor.md >}}), and other observability tools, so that logs can be searched and analyzed to provide insights.
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.

### Metrics

Metrics are the series of measured values and counts that are collected and stored over time. [Dapr metrics]({{<ref "metrics">}}) provide monitoring capabilities to understand the behavior of the Dapr sidecar and control plane. For example, the metrics between a Dapr sidecar and the user application show call latency, traffic failures, error rates of requests, etc. Dapr [control plane metrics](https://github.com/dapr/dapr/blob/master/docs/development/dapr-metrics.md) show sidecar injection failures and the health of control plane services, including CPU usage, number of actor placements made, etc.
Metrics are a series of measured values and counts collected and stored over time. [Dapr metrics]({{< ref metrics >}}) provide monitoring capabilities to understand the behavior of the Dapr sidecar and control plane. For example, the metrics between a Dapr sidecar and the user application show call latency, traffic failures, error rates of requests, etc.

Dapr [control plane metrics](https://github.com/dapr/dapr/blob/master/docs/development/dapr-metrics.md) show sidecar injection failures and the health of control plane services, including CPU usage, number of actor placements made, etc.

### Health checks

The Dapr sidecar exposes an HTTP endpoint for [health checks]({{<ref sidecar-health.md>}}). With this API, user code or hosting environments can probe the Dapr sidecar to determine its status and identify issues with sidecar readiness.
The Dapr sidecar exposes an HTTP endpoint for [health checks]({{< ref sidecar-health.md >}}). With this API, user code or hosting environments can probe the Dapr sidecar to determine its status and identify issues with sidecar readiness.

Conversely, Dapr can be configured to probe for the [health of your application]({{< ref app-health.md >}}), and react to changes in the app's health, including stopping pub/sub subscriptions and short-circuiting service invocation calls.

## Next steps

Conversely, Dapr can be configured to probe for the [health of your application]({{<ref app-health.md >}}), and react to changes in the app's health, including stopping pub/sub subscriptions and short-circuiting service invocation calls.
- [Learn more about observability in developing with Dapr]({{< ref develop-tracing >}})
- [Learn more about observability in operating with Dapr]({{< ref tracing >}})
17 changes: 16 additions & 1 deletion daprdocs/content/en/concepts/security-concept.md
Original file line number Diff line number Diff line change
Expand Up @@ -211,6 +211,21 @@ The Dapr threat model is below.

## Security audit

### June 2023

In June 2023, Dapr completed a fuzzing audit done by Ada Logics.

The audit achieved the following:

- OSS-Fuzz integration
- 39 new fuzzers for Dapr
- Fuzz test coverage for Dapr Runtime, Kit and Components-contrib
- All fuzzers running continuously after the audit has completed

You can find the full report [here](/docs/Dapr-june-2023-fuzzing-audit-report.pdf).

3 issues were found during the audit.

### February 2021

In February 2021, Dapr went through a 2nd security audit targeting its 1.0 release by Cure53.
Expand Down Expand Up @@ -255,4 +270,4 @@ Visit [this page]({{< ref support-security-issues.md >}}) to report a security i

## Related links

[Operational Security]({{< ref "security.md" >}})
[Operational Security]({{< ref "security.md" >}})
Original file line number Diff line number Diff line change
Expand Up @@ -39,11 +39,11 @@ Style and tone conventions should be followed throughout all Dapr documentation

## Diagrams and images

Diagrams and images are invaluable visual aids for documentation pages. Diagrams are kept in a [Dapr Diagrams Deck](https://github.com/dapr/docs/tree/v1.10/daprdocs/static/presentations), which includes guidance on style and icons.
Diagrams and images are invaluable visual aids for documentation pages. Diagrams are kept in a [Dapr Diagrams Deck](https://github.com/dapr/docs/tree/v1.11/daprdocs/static/presentations), which includes guidance on style and icons.

As you create diagrams for your documentation:

- Save them as high-res PNG files into the [images folder](https://github.com/dapr/docs/tree/v1.10/daprdocs/static/images).
- Save them as high-res PNG files into the [images folder](https://github.com/dapr/docs/tree/v1.11/daprdocs/static/images).
- Name your PNG files using the convention of a concept or building block so that they are grouped.
- For example: `service-invocation-overview.png`.
- For more information on calling out images using shortcode, see the [Images guidance](#images) section below.
Expand Down Expand Up @@ -458,4 +458,4 @@ Steps to add a language:

## Next steps

Get started by copying and working from one of [the Dapr doc templates]({{< ref docs-templates >}}).
Get started by copying and working from one of [the Dapr doc templates]({{< ref docs-templates >}}).
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,5 @@ description: "Dapr capabilities that solve common development challenges for dis

Get a high-level [overview of Dapr building blocks]({{< ref building-blocks-concept >}}) in the **Concepts** section.

<img src="/images/buildingblocks-overview.png" alt="Diagram showing the different Dapr API building blocks" width=1000>
<img src="/images/buildingblocks-overview.png" alt="Diagram showing the different Dapr API building blocks" width=1000>

Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,10 @@ linkTitle: "Actors"
weight: 50
description: Encapsulate code and data in reusable actor objects as a common microservices design pattern
---

{{% alert title="More about Dapr Actors" color="primary" %}}
Learn more about how to use Dapr Actors:
- Try the [Actors quickstart]({{< ref actors-quickstart.md >}}).
- Explore actors via any of the [Dapr SDKs]({{< ref sdks >}}).
- Review the [Actors API reference documentation]({{< ref actors_api.md >}}).
{{% /alert %}}
Loading

0 comments on commit 599670a

Please sign in to comment.