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: - -