From 90691593890cfd0e63e591671ff527cc8dfc67bd Mon Sep 17 00:00:00 2001 From: Elena Kolevska Date: Thu, 31 Oct 2024 17:46:16 +0000 Subject: [PATCH 1/6] Updates docs for circuit breaker Signed-off-by: Elena Kolevska --- daprdocs/content/en/operations/resiliency/policies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/operations/resiliency/policies.md b/daprdocs/content/en/operations/resiliency/policies.md index 086ca7fd5..73e225167 100644 --- a/daprdocs/content/en/operations/resiliency/policies.md +++ b/daprdocs/content/en/operations/resiliency/policies.md @@ -88,7 +88,7 @@ Circuit Breaker (CB) policies are used when other applications/services/componen | `maxRequests` | The maximum number of requests allowed to pass through when the CB is half-open (recovering from failure). Defaults to `1`. | | `interval` | The cyclical period of time used by the CB to clear its internal counts. If set to 0 seconds, this never clears. Defaults to `0s`. | | `timeout` | The period of the open state (directly after failure) until the CB switches to half-open. Defaults to `60s`. | -| `trip` | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) statement that is evaluated by the CB. When the statement evaluates to true, the CB trips and becomes open. Defaults to `consecutiveFailures > 5`. | +| `trip` | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) statement that is evaluated by the CB. When the statement evaluates to true, the CB trips and becomes open. Defaults to `consecutiveFailures > 5`. Other possible values are `requests` and `totalFailures` where `requests` represents the number of either successful or failed calls before the circuit opens and `totalFailures` represents the total (not necessarily consecutive) number of failed attempts before the circuit opens. Example: `requests > 5` and `totalFailures >3`.| Example: From 263db693ecd2f4e16e32a32c2d40cb833e0ce966 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Fri, 13 Dec 2024 12:18:39 -0500 Subject: [PATCH 2/6] create new errors topic Signed-off-by: Hannah Hunter --- .../debugging/_index.md | 2 +- .../develop-components/_index.md | 2 +- .../error-codes/_index.md | 8 +++++++ .../error-codes/error-codes-reference.md} | 22 ++++++++----------- .../error-codes/errors-overview.md | 13 +++++++++++ .../error-codes/grpc-error-codes.md} | 14 +++++------- .../error-codes/http-error-codes.md | 21 ++++++++++++++++++ .../integrations/_index.md | 2 +- .../local-development/_index.md | 2 +- .../en/developing-applications/sdks/_index.md | 2 +- 10 files changed, 62 insertions(+), 26 deletions(-) create mode 100644 daprdocs/content/en/developing-applications/error-codes/_index.md rename daprdocs/content/en/{reference/api/error_codes.md => developing-applications/error-codes/error-codes-reference.md} (95%) create mode 100644 daprdocs/content/en/developing-applications/error-codes/errors-overview.md rename daprdocs/content/en/{reference/errors/_index.md => developing-applications/error-codes/grpc-error-codes.md} (93%) create mode 100644 daprdocs/content/en/developing-applications/error-codes/http-error-codes.md diff --git a/daprdocs/content/en/developing-applications/debugging/_index.md b/daprdocs/content/en/developing-applications/debugging/_index.md index bb9d76df1..d6d77e77d 100644 --- a/daprdocs/content/en/developing-applications/debugging/_index.md +++ b/daprdocs/content/en/developing-applications/debugging/_index.md @@ -2,6 +2,6 @@ type: docs title: "Debugging Dapr applications and the Dapr control plane" linkTitle: "Debugging" -weight: 50 +weight: 60 description: "Guides on how to debug Dapr applications and the Dapr control plane" --- \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/develop-components/_index.md b/daprdocs/content/en/developing-applications/develop-components/_index.md index cb9f7e8a8..970744958 100644 --- a/daprdocs/content/en/developing-applications/develop-components/_index.md +++ b/daprdocs/content/en/developing-applications/develop-components/_index.md @@ -2,6 +2,6 @@ type: docs title: "Components" linkTitle: "Components" -weight: 30 +weight: 40 description: "Learn more about developing Dapr's pluggable and middleware components" --- diff --git a/daprdocs/content/en/developing-applications/error-codes/_index.md b/daprdocs/content/en/developing-applications/error-codes/_index.md new file mode 100644 index 000000000..f693722f5 --- /dev/null +++ b/daprdocs/content/en/developing-applications/error-codes/_index.md @@ -0,0 +1,8 @@ +--- +type: docs +title: "Error codes" +linkTitle: "Error codes" +weight: 20 +description: "Error codes and messages you may encounter while using Dapr" +--- + diff --git a/daprdocs/content/en/reference/api/error_codes.md b/daprdocs/content/en/developing-applications/error-codes/error-codes-reference.md similarity index 95% rename from daprdocs/content/en/reference/api/error_codes.md rename to daprdocs/content/en/developing-applications/error-codes/error-codes-reference.md index c098521cc..314bf67c4 100644 --- a/daprdocs/content/en/reference/api/error_codes.md +++ b/daprdocs/content/en/developing-applications/error-codes/error-codes-reference.md @@ -1,20 +1,11 @@ --- type: docs -title: "Error codes returned by APIs" -linkTitle: "Error codes" -description: "Detailed reference of the Dapr API error codes" -weight: 1400 +title: "Error codes reference guide" +linkTitle: "Reference" +description: "List of gRPC and HTTP error codes in Dapr and their descriptions" +weight: 20 --- -For http calls made to Dapr runtime, when an error is encountered, an error json is returned in http response body. The json contains an error code and an descriptive error message, e.g. - -``` -{ - "errorCode": "ERR_STATE_GET", - "message": "Requested state key does not exist in state store." -} -``` - The following tables list the error codes returned by Dapr runtime: ### Actors API @@ -154,3 +145,8 @@ The following tables list the error codes returned by Dapr runtime: | ERR_MALFORMED_REQUEST | Error with a malformed request. | | ERR_MALFORMED_REQUEST_DATA | Error request data is malformed. | | ERR_MALFORMED_RESPONSE | Error response data is malformed. | + +## Next steps + +- [Handling HTTP error codes]({{< ref http-error-codes.md >}}) +- [Handling gRPC error codes]({{< ref grpc-error-codes.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/error-codes/errors-overview.md b/daprdocs/content/en/developing-applications/error-codes/errors-overview.md new file mode 100644 index 000000000..5f34aff4d --- /dev/null +++ b/daprdocs/content/en/developing-applications/error-codes/errors-overview.md @@ -0,0 +1,13 @@ +--- +type: docs +title: "Errors overview" +linkTitle: "Overview" +weight: 10 +description: "Overview of Dapr errors" +--- + + + +## Next step + +{{< button text="Error code reference" page="error-codes-reference" >}} diff --git a/daprdocs/content/en/reference/errors/_index.md b/daprdocs/content/en/developing-applications/error-codes/grpc-error-codes.md similarity index 93% rename from daprdocs/content/en/reference/errors/_index.md rename to daprdocs/content/en/developing-applications/error-codes/grpc-error-codes.md index 35f685f74..1d343cce5 100644 --- a/daprdocs/content/en/reference/errors/_index.md +++ b/daprdocs/content/en/developing-applications/error-codes/grpc-error-codes.md @@ -1,20 +1,18 @@ --- type: docs -title: Dapr errors -linkTitle: "Dapr errors" -weight: 700 -description: "Information on Dapr errors and how to handle them" +title: Handling gRPC error codes +linkTitle: "gRPC" +weight: 40 +description: "Information on Dapr gRPC errors and how to handle them" --- -## Error handling: Understanding errors model and reporting - Initially, errors followed the [Standard gRPC error model](https://grpc.io/docs/guides/error/#standard-error-model). However, to provide more detailed and informative error messages, an enhanced error model has been defined which aligns with the gRPC [Richer error model](https://grpc.io/docs/guides/error/#richer-error-model). {{% alert title="Note" color="primary" %}} Not all Dapr errors have been converted to the richer gRPC error model. {{% /alert %}} -### Standard gRPC Error Model +## Standard gRPC Error Model The [Standard gRPC error model](https://grpc.io/docs/guides/error/#standard-error-model) is an approach to error reporting in gRPC. Each error response includes an error code and an error message. The error codes are standardized and reflect common error conditions. @@ -25,7 +23,7 @@ ERROR: Message: input key/keyPrefix 'bad||keyname' can't contain '||' ``` -### Richer gRPC Error Model +## Richer gRPC Error Model The [Richer gRPC error model](https://grpc.io/docs/guides/error/#richer-error-model) extends the standard error model by providing additional context and details about the error. This model includes the standard error `code` and `message`, along with a `details` section that can contain various types of information, such as `ErrorInfo`, `ResourceInfo`, and `BadRequest` details. diff --git a/daprdocs/content/en/developing-applications/error-codes/http-error-codes.md b/daprdocs/content/en/developing-applications/error-codes/http-error-codes.md new file mode 100644 index 000000000..c05a0dac8 --- /dev/null +++ b/daprdocs/content/en/developing-applications/error-codes/http-error-codes.md @@ -0,0 +1,21 @@ +--- +type: docs +title: "Handling HTTP error codes" +linkTitle: "HTTP" +description: "Detailed reference of the Dapr HTTP error codes and how to handle them" +weight: 30 +--- + +For http calls made to Dapr runtime, when an error is encountered, an error json is returned in http response body. The json contains an error code and an descriptive error message, e.g. + +``` +{ + "errorCode": "ERR_STATE_GET", + "message": "Requested state key does not exist in state store." +} +``` + +## Related + +- [Error code reference list]({{< ref error-codes-reference.md >}}) +- [Handling gRPC error codes]({{< ref grpc-error-codes.md >}}) \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/integrations/_index.md b/daprdocs/content/en/developing-applications/integrations/_index.md index a884aeb5c..b988581b7 100644 --- a/daprdocs/content/en/developing-applications/integrations/_index.md +++ b/daprdocs/content/en/developing-applications/integrations/_index.md @@ -2,6 +2,6 @@ type: docs title: "Integrations" linkTitle: "Integrations" -weight: 60 +weight: 70 description: "Dapr integrations with other technologies" --- \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/local-development/_index.md b/daprdocs/content/en/developing-applications/local-development/_index.md index b06587df5..8ffc396d4 100644 --- a/daprdocs/content/en/developing-applications/local-development/_index.md +++ b/daprdocs/content/en/developing-applications/local-development/_index.md @@ -2,6 +2,6 @@ type: docs title: "Local development" linkTitle: "Local development" -weight: 40 +weight: 50 description: "Capabilities for developing Dapr applications locally" --- \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/sdks/_index.md b/daprdocs/content/en/developing-applications/sdks/_index.md index 4f56c0513..5434d497b 100644 --- a/daprdocs/content/en/developing-applications/sdks/_index.md +++ b/daprdocs/content/en/developing-applications/sdks/_index.md @@ -2,7 +2,7 @@ type: docs title: "Dapr Software Development Kits (SDKs)" linkTitle: "SDKs" -weight: 20 +weight: 30 description: "Use your favorite languages with Dapr" no_list: true --- From 78f427d95d6844b52f6c2d29a9446ae98d6c7e13 Mon Sep 17 00:00:00 2001 From: Hannah Hunter Date: Fri, 13 Dec 2024 15:13:44 -0500 Subject: [PATCH 3/6] overview draft Signed-off-by: Hannah Hunter --- .../error-codes/errors-overview.md | 51 ++++++++++++++++++- .../configuration/configuration-overview.md | 5 +- .../observability/metrics/metrics-overview.md | 2 +- .../resource-specs/configuration-schema.md | 1 + 4 files changed, 56 insertions(+), 3 deletions(-) diff --git a/daprdocs/content/en/developing-applications/error-codes/errors-overview.md b/daprdocs/content/en/developing-applications/error-codes/errors-overview.md index 5f34aff4d..f007a411a 100644 --- a/daprdocs/content/en/developing-applications/error-codes/errors-overview.md +++ b/daprdocs/content/en/developing-applications/error-codes/errors-overview.md @@ -6,8 +6,57 @@ weight: 10 description: "Overview of Dapr errors" --- +An error code is a numeric or alphamueric code that indicates the nature of an error and, when possible, why it occured. +Dapr error codes are standardized strings for over 80+ common errors across HTTP and gRPC requests when using the Dapr APIs. These codes are both: +- Returned in the JSON response body of the request +- When enabled, logged in debug-level logs in the runtime. + - If you're running in Kubernetes, error codes are logged in the sidecar. + - If you're running in self-hosted, you can enable and run debug logs. + +## Error format + +Dapr error codes consist of a prefix, a category, and shorthand of the error itself. For example: + +| Prefix | Category | Error shorthand | +| ------ | -------- | --------------- | +| ERR_ | PUBSUB_ | NOT_FOUND | + +Some of the most common errors returned include: + +- ERR_ACTOR_TIMER_CREATE +- ERR_PURGE_WORKFLOW +- ERR_STATE_STORE_NOT_FOUND +- ERR_HEALTH_NOT_READY + +> **Note:** [See a full list of error codes in Dapr.]({{< ref error-codes-reference.md >}}) + +An error returned for a state store not found might look like the following: + +```json +{ + "error": "Bad Request", + "error_msg": "{\"errorCode\":\"ERR_STATE_STORE_NOT_FOUND\",\"message\":\"state store is not found\",\"details\":[{\"@type\":\"type.googleapis.com/google.rpc.ErrorInfo\",\"domain\":\"dapr.io\",\"metadata\":{\"appID\":\"nodeapp\"},\"reason\":\"DAPR_STATE_NOT_FOUND\"}]}", + "status": 400 +} +``` + +The returned error includes: +- The error code: `ERR_STATE_STORE_NOT_FOUND` +- The error message describing the issue: `state store is not found` +- The app ID in which the error is occuring: `nodeapp` +- The reason for the error: `DAPR_STATE_NOT_FOUND` + +## Dapr error code metrics + +Metrics help users see when exactly errors are occuring from within the runtime. Error code metrics are collected using the `error_code_total` endpoint. This endpoint is disabled by default. You can [enable it using the `recordErrorCodes` field in your configuration file]({{< ref "metrics-overview.md#configuring-metrics-for-error-codes" >}}). + +## Demo + +Watch a demo presented during [Diagrid's Dapr v1.15 celebration](https://www.diagrid.io/videos/dapr-1-15-deep-dive) to see how to enable error code metrics and handle error codes returned in the runtime. + + ## Next step -{{< button text="Error code reference" page="error-codes-reference" >}} +{{< button text="See a list of all Dapr error codes" page="error-codes-reference" >}} \ No newline at end of file diff --git a/daprdocs/content/en/operations/configuration/configuration-overview.md b/daprdocs/content/en/operations/configuration/configuration-overview.md index 7225fc11f..5a528a224 100644 --- a/daprdocs/content/en/operations/configuration/configuration-overview.md +++ b/daprdocs/content/en/operations/configuration/configuration-overview.md @@ -145,9 +145,12 @@ metrics: - /payments/{paymentID}/refund - /payments/{paymentID}/details excludeVerbs: false + recordErrorCodes: true ``` -In the examples above, the path filter `/orders/{orderID}/items/{itemID}` would return _a single metric count_ matching all the `orderID`s and all the `itemID`s, rather than multiple metrics for each `itemID`. For more information, see [HTTP metrics path matching]({{< ref "metrics-overview.md#http-metrics-path-matching" >}}) +In the examples above, the path filter `/orders/{orderID}/items/{itemID}` would return _a single metric count_ matching all the `orderID`s and all the `itemID`s, rather than multiple metrics for each `itemID`. For more information, see [HTTP metrics path matching]({{< ref "metrics-overview.md#http-metrics-path-matching" >}}). + +The above example also enables [recording error code metrics]({{< ref "metrics-overview.md#configuring-metrics-for-error-codes" >}}), which is disabled by default. The following table lists the properties for metrics: diff --git a/daprdocs/content/en/operations/observability/metrics/metrics-overview.md b/daprdocs/content/en/operations/observability/metrics/metrics-overview.md index 23fea29e6..1df663ab7 100644 --- a/daprdocs/content/en/operations/observability/metrics/metrics-overview.md +++ b/daprdocs/content/en/operations/observability/metrics/metrics-overview.md @@ -72,7 +72,7 @@ spec: ## Configuring metrics for error codes -You can enable additional metrics for [Dapr API error codes](https://docs.dapr.io/reference/api/error_codes/) by setting `spec.metrics.recordErrorCodes` to `true`. Dapr APIs which communicate back to their caller may return standardized error codes. As described in the [Dapr development docs](https://github.com/dapr/dapr/blob/master/docs/development/dapr-metrics.md), a new metric called `error_code_total` is recorded, which allows monitoring of error codes triggered by application, code, and category. See [the `errorcodes` package](https://github.com/dapr/dapr/blob/master/pkg/messages/errorcodes/errorcodes.go) for specific codes and categories. +You can enable additional metrics for [Dapr API error codes](https://docs.dapr.io/reference/api/error_codes/) by setting `spec.metrics.recordErrorCodes` to `true`. Dapr APIs which communicate back to their caller may return standardized error codes. [A new metric called `error_code_total` is recorded]({{< ref errors-overview.md >}}), which allows monitoring of error codes triggered by application, code, and category. See [the `errorcodes` package](https://github.com/dapr/dapr/blob/master/pkg/messages/errorcodes/errorcodes.go) for specific codes and categories. Example configuration: ```yaml diff --git a/daprdocs/content/en/reference/resource-specs/configuration-schema.md b/daprdocs/content/en/reference/resource-specs/configuration-schema.md index b52228c16..e5caac792 100644 --- a/daprdocs/content/en/reference/resource-specs/configuration-schema.md +++ b/daprdocs/content/en/reference/resource-specs/configuration-schema.md @@ -36,6 +36,7 @@ spec: labels: - name: regex: {} + recordErrorCodes: latencyDistributionBuckets: - - From abc1f553fcbc8e56b23f734870eae82432267fe5 Mon Sep 17 00:00:00 2001 From: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Date: Thu, 19 Dec 2024 16:44:39 -0500 Subject: [PATCH 4/6] Update daprdocs/content/en/developing-applications/error-codes/errors-overview.md Co-authored-by: Mark Fussell Signed-off-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> --- .../en/developing-applications/error-codes/errors-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/error-codes/errors-overview.md b/daprdocs/content/en/developing-applications/error-codes/errors-overview.md index f007a411a..7b654b447 100644 --- a/daprdocs/content/en/developing-applications/error-codes/errors-overview.md +++ b/daprdocs/content/en/developing-applications/error-codes/errors-overview.md @@ -9,7 +9,7 @@ description: "Overview of Dapr errors" An error code is a numeric or alphamueric code that indicates the nature of an error and, when possible, why it occured. Dapr error codes are standardized strings for over 80+ common errors across HTTP and gRPC requests when using the Dapr APIs. These codes are both: -- Returned in the JSON response body of the request +- Returned in the JSON response body of the request. - When enabled, logged in debug-level logs in the runtime. - If you're running in Kubernetes, error codes are logged in the sidecar. - If you're running in self-hosted, you can enable and run debug logs. From a5c2936b58a2287bdb7eac515f2c88223b07c993 Mon Sep 17 00:00:00 2001 From: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Date: Thu, 19 Dec 2024 16:44:46 -0500 Subject: [PATCH 5/6] Update daprdocs/content/en/developing-applications/error-codes/errors-overview.md Co-authored-by: Mark Fussell Signed-off-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> --- .../en/developing-applications/error-codes/errors-overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/error-codes/errors-overview.md b/daprdocs/content/en/developing-applications/error-codes/errors-overview.md index 7b654b447..762413fb7 100644 --- a/daprdocs/content/en/developing-applications/error-codes/errors-overview.md +++ b/daprdocs/content/en/developing-applications/error-codes/errors-overview.md @@ -49,7 +49,7 @@ The returned error includes: ## Dapr error code metrics -Metrics help users see when exactly errors are occuring from within the runtime. Error code metrics are collected using the `error_code_total` endpoint. This endpoint is disabled by default. You can [enable it using the `recordErrorCodes` field in your configuration file]({{< ref "metrics-overview.md#configuring-metrics-for-error-codes" >}}). +Metrics help you see when exactly errors are occuring from within the runtime. Error code metrics are collected using the `error_code_total` endpoint. This endpoint is disabled by default. You can [enable it using the `recordErrorCodes` field in your configuration file]({{< ref "metrics-overview.md#configuring-metrics-for-error-codes" >}}). ## Demo From 9006404987ef008014e03da1b873f75e37054225 Mon Sep 17 00:00:00 2001 From: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> Date: Thu, 19 Dec 2024 16:44:55 -0500 Subject: [PATCH 6/6] Update daprdocs/content/en/developing-applications/error-codes/http-error-codes.md Co-authored-by: Mark Fussell Signed-off-by: Hannah Hunter <94493363+hhunter-ms@users.noreply.github.com> --- .../en/developing-applications/error-codes/http-error-codes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/daprdocs/content/en/developing-applications/error-codes/http-error-codes.md b/daprdocs/content/en/developing-applications/error-codes/http-error-codes.md index c05a0dac8..1b069ebaf 100644 --- a/daprdocs/content/en/developing-applications/error-codes/http-error-codes.md +++ b/daprdocs/content/en/developing-applications/error-codes/http-error-codes.md @@ -6,7 +6,7 @@ description: "Detailed reference of the Dapr HTTP error codes and how to handle weight: 30 --- -For http calls made to Dapr runtime, when an error is encountered, an error json is returned in http response body. The json contains an error code and an descriptive error message, e.g. +For HTTP calls made to Dapr runtime, when an error is encountered, an error JSON is returned in response body. The JSON contains an error code and an descriptive error message. ``` {