From 125eb19c9aed78e7838f0aa05e3f1242b144d804 Mon Sep 17 00:00:00 2001 From: Jake Engelberg Date: Wed, 6 Nov 2024 18:20:23 -0500 Subject: [PATCH 1/4] add exhaustive list of error codes and description of metric flag Signed-off-by: Jake Engelberg --- .../observability/metrics/metrics-overview.md | 16 ++ .../content/en/reference/api/error_codes.md | 173 ++++++++++++++---- 2 files changed, 156 insertions(+), 33 deletions(-) diff --git a/daprdocs/content/en/operations/observability/metrics/metrics-overview.md b/daprdocs/content/en/operations/observability/metrics/metrics-overview.md index 5f07bb325f9..deb7882cb25 100644 --- a/daprdocs/content/en/operations/observability/metrics/metrics-overview.md +++ b/daprdocs/content/en/operations/observability/metrics/metrics-overview.md @@ -70,6 +70,22 @@ spec: enabled: false ``` +## Configuring metrics for error codes + +You can enable additional metrics for [Dapr API error codes](https://github.com/dapr/dapr/blob/master/docs/reference/api/error_codes/) by setting `spec.metrics.recordErrorCodes` to `true`. See the specific metrics described in the [Dapr development docs](https://github.com/dapr/dapr/blob/master/docs/development/dapr-metrics.md). + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: tracing + namespace: default +spec: + metrics: + enabled: true + recordErrorCodes: true +``` + ## Optimizing HTTP metrics reporting with path matching When invoking Dapr using HTTP, metrics are created for each requested method by default. This can result in a high number of metrics, known as high cardinality, which can impact memory usage and CPU. diff --git a/daprdocs/content/en/reference/api/error_codes.md b/daprdocs/content/en/reference/api/error_codes.md index 19d3b8cc36c..2e18882aa07 100644 --- a/daprdocs/content/en/reference/api/error_codes.md +++ b/daprdocs/content/en/reference/api/error_codes.md @@ -7,6 +7,7 @@ weight: 1400 --- 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", @@ -14,36 +15,142 @@ For http calls made to Dapr runtime, when an error is encountered, an error json } ``` -Following table lists the error codes returned by Dapr runtime: - -| Error Code | Description | -|-----------------------------------|-------------| -| ERR_ACTOR_INSTANCE_MISSING | Error getting an actor instance. This means that actor is now hosted in some other service replica. -| ERR_ACTOR_RUNTIME_NOT_FOUND | Error getting the actor instance. -| ERR_ACTOR_REMINDER_CREATE | Error creating a reminder for an actor. -| ERR_ACTOR_REMINDER_DELETE | Error deleting a reminder for an actor. -| ERR_ACTOR_TIMER_CREATE | Error creating a timer for an actor. -| ERR_ACTOR_TIMER_DELETE | Error deleting a timer for an actor. -| ERR_ACTOR_REMINDER_GET | Error getting a reminder for an actor. -| ERR_ACTOR_INVOKE_METHOD | Error invoking a method on an actor. -| ERR_ACTOR_STATE_DELETE | Error deleting the state for an actor. -| ERR_ACTOR_STATE_GET | Error getting the state for an actor. -| ERR_ACTOR_STATE_TRANSACTION_SAVE | Error storing actor state transactionally. -| ERR_PUBSUB_NOT_FOUND | Error referencing the Pub/Sub component in Dapr runtime. -| ERR_PUBSUB_PUBLISH_MESSAGE | Error publishing a message. -| ERR_PUBSUB_FORBIDDEN | Error message forbidden by access controls. -| ERR_PUBSUB_CLOUD_EVENTS_SER | Error serializing Pub/Sub event envelope. -| ERR_STATE_STORE_NOT_FOUND | Error referencing a state store not found. -| ERR_STATE_STORES_NOT_CONFIGURED | Error no state stores configured. -| ERR_NOT_SUPPORTED_STATE_OPERATION | Error transaction requested on a state store with no transaction support. -| ERR_STATE_GET | Error getting a state for state store. -| ERR_STATE_DELETE | Error deleting a state from state store. -| ERR_STATE_SAVE | Error saving a state in state store. -| ERR_INVOKE_OUTPUT_BINDING | Error invoking an output binding. -| ERR_MALFORMED_REQUEST | Error with a malformed request. -| ERR_DIRECT_INVOKE | Error in direct invocation. -| ERR_DESERIALIZE_HTTP_BODY | Error deserializing an HTTP request body. -| ERR_SECRET_STORES_NOT_CONFIGURED | Error that no secret store is configured. -| ERR_SECRET_STORE_NOT_FOUND | Error that specified secret store is not found. -| ERR_HEALTH_NOT_READY | Error that Dapr is not ready. -| ERR_METADATA_GET | Error parsing the Metadata information. +The following tables list the error codes returned by Dapr runtime: + +### Actors (Building Block) + +| Error Code | Description | +| -------------------------------- | ------------------------------------------ | +| ERR_ACTOR_INSTANCE_MISSING | Error when an actor instance is missing. | +| ERR_ACTOR_RUNTIME_NOT_FOUND | Error the actor instance. | +| ERR_ACTOR_REMINDER_CREATE | Error creating a reminder for an actor. | +| ERR_ACTOR_REMINDER_DELETE | Error deleting a reminder for an actor. | +| ERR_ACTOR_TIMER_CREATE | Error creating a timer for an actor. | +| ERR_ACTOR_TIMER_DELETE | Error deleting a timer for an actor. | +| ERR_ACTOR_REMINDER_GET | Error getting a reminder for an actor. | +| ERR_ACTOR_INVOKE_METHOD | Error invoking a method on an actor. | +| ERR_ACTOR_STATE_DELETE | Error deleting the state for an actor. | +| ERR_ACTOR_STATE_GET | Error getting the state for an actor. | +| ERR_ACTOR_STATE_TRANSACTION_SAVE | Error storing actor state transactionally. | +| ERR_ACTOR_REMINDER_NON_HOSTED | Error setting reminder for an actor. | + +### Workflows (Building Block) + +| Error Code | Description | +| -------------------------------- | ----------------------------------------------------------- | +| ERR_GET_WORKFLOW | Error getting workflow. | +| ERR_START_WORKFLOW | Error starting the workflow. | +| ERR_PAUSE_WORKFLOW | Error pausing the workflow. | +| ERR_RESUME_WORKFLOW | Error resuming the workflow. | +| ERR_TERMINATE_WORKFLOW | Error terminating the workflow. | +| ERR_PURGE_WORKFLOW | Error purging workflow. | +| ERR_RAISE_EVENT_WORKFLOW | Error raising an event within the workflow. | +| ERR_WORKFLOW_COMPONENT_MISSING | Error when a workflow component is missing a configuration. | +| ERR_WORKFLOW_COMPONENT_NOT_FOUND | Error when a workflow component is not found. | +| ERR_WORKFLOW_EVENT_NAME_MISSING | Error when the event name for a workflow is missing. | +| ERR_WORKFLOW_NAME_MISSING | Error when the workflow name is missing. | +| ERR_INSTANCE_ID_INVALID | Error invalid workflow instance ID provided. | +| ERR_INSTANCE_ID_NOT_FOUND | Error workflow instance ID not found. | +| ERR_INSTANCE_ID_PROVIDED_MISSING | Error workflow instance ID was provided but missing. | +| ERR_INSTANCE_ID_TOO_LONG | Error workflow instance ID exceeds allowable length. | + +### State Management (Building Block) + +| Error Code | Description | +| ------------------------------------- | ------------------------------------------------------------------------- | +| ERR_STATE_STORE_NOT_FOUND | Error referencing a state store not found. | +| ERR_STATE_STORES_NOT_CONFIGURED | Error no state stores configured. | +| ERR_NOT_SUPPORTED_STATE_OPERATION | Error transaction requested on a state store with no transaction support. | +| ERR_STATE_GET | Error getting a state for state store. | +| ERR_STATE_DELETE | Error deleting a state from state store. | +| ERR_STATE_SAVE | Error saving a state in state store. | +| ERR_STATE_TRANSACTION | Error encountered during state transaction. | +| ERR_STATE_BULK_GET | Error performing bulk retrieval of state entries. | +| ERR_STATE_QUERY | Error querying the state store. | +| ERR_STATE_STORE_NOT_CONFIGURED | Error state store is not configured. | +| ERR_STATE_STORE_NOT_SUPPORTED | Error state store is not supported. | +| ERR_STATE_STORE_TOO_MANY_TRANSACTIONS | Error exceeded maximum allowable transactions. | + +### Configuration (Building Block) + +| Error Code | Description | +| -------------------------------------- | -------------------------------------------- | +| ERR_CONFIGURATION_GET | Error retrieving configuration. | +| ERR_CONFIGURATION_STORE_NOT_CONFIGURED | Error configuration store is not configured. | +| ERR_CONFIGURATION_STORE_NOT_FOUND | Error configuration store not found. | +| ERR_CONFIGURATION_SUBSCRIBE | Error subscribing to a configuration. | +| ERR_CONFIGURATION_UNSUBSCRIBE | Error unsubscribing from a configuration. | + +### Crypto (Building Block) + +| Error Code | Description | +| ----------------------------------- | ------------------------------------------ | +| ERR_CRYPTO | General crypto building block error. | +| ERR_CRYPTO_KEY | Error related to a crypto key. | +| ERR_CRYPTO_PROVIDER_NOT_FOUND | Error specified crypto provider not found. | +| ERR_CRYPTO_PROVIDERS_NOT_CONFIGURED | Error no crypto providers configured. | + +### Secrets (Building Block) + +| Error Code | Description | +| -------------------------------- | ---------------------------------------------------- | +| ERR_SECRET_STORES_NOT_CONFIGURED | Error that no secret store is configured. | +| ERR_SECRET_STORE_NOT_FOUND | Error that specified secret store is not found. | +| ERR_SECRET_GET | Error retrieving the specified secret. | +| ERR_PERMISSION_DENIED | Error access denied due to insufficient permissions. | + +### Pub/Sub (Building Block) + +| Error Code | Description | +| --------------------------- | -------------------------------------------------------- | +| ERR_PUBSUB_NOT_FOUND | Error referencing the Pub/Sub component in Dapr runtime. | +| ERR_PUBSUB_PUBLISH_MESSAGE | Error publishing a message. | +| ERR_PUBSUB_FORBIDDEN | Error message forbidden by access controls. | +| ERR_PUBSUB_CLOUD_EVENTS_SER | Error serializing Pub/Sub event envelope. | +| ERR_PUBSUB_EMPTY | Error empty Pub/Sub. | +| ERR_PUBSUB_NOT_CONFIGURED | Error Pub/Sub component is not configured. | +| ERR_PUBSUB_REQUEST_METADATA | Error with metadata in Pub/Sub request. | +| ERR_PUBSUB_EVENTS_SER | Error serializing Pub/Sub events. | +| ERR_PUBLISH_OUTBOX | Error publishing message to the outbox. | +| ERR_TOPIC_NAME_EMPTY | Error topic name for Pub/Sub message is empty. | + +### Conversation (Building Block) + +| Error Code | Description | +| ------------------------------- | ----------------------------------------------- | +| ERR_INVOKE_OUTPUT_BINDING | Error invoking an output binding. | +| ERR_DIRECT_INVOKE | Error in direct invocation. | +| ERR_CONVERSATION_INVALID_PARMS | Error invalid parameters for conversation. | +| ERR_CONVERSATION_INVOKE | Error invoking the conversation. | +| ERR_CONVERSATION_MISSING_INPUTS | Error missing required inputs for conversation. | +| ERR_CONVERSATION_NOT_FOUND | Error conversation not found. | + +### Distributed Lock (Building Block) + +| Error Code | Description | +| ----------------------------- | ----------------------------------- | +| ERR_TRY_LOCK | Error attempting to acquire a lock. | +| ERR_UNLOCK | Error attempting to release a lock. | +| ERR_LOCK_STORE_NOT_CONFIGURED | Error lock store is not configured. | +| ERR_LOCK_STORE_NOT_FOUND | Error lock store not found. | + +### Healthz + +| Error Code | Description | +| ----------------------------- | --------------------------------------------------------------- | +| ERR_HEALTH_NOT_READY | Error that Dapr is not ready. | +| ERR_HEALTH_APPID_NOT_MATCH | Error the app-id does not match expected value in health check. | +| ERR_OUTBOUND_HEALTH_NOT_READY | Error outbound connection health is not ready. | + +### Common + +| Error Code | Description | +| -------------------------- | ------------------------------------------------ | +| ERR_API_UNIMPLEMENTED | Error API is not implemented. | +| ERR_APP_CHANNEL_NIL | Error application channel is nil. | +| ERR_BAD_REQUEST | Error client request is badly formed or invalid. | +| ERR_BODY_READ | Error reading body. | +| ERR_INTERNAL | Internal server error encountered. | +| 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. | From 88a0d66d4424fb78baa6784505ba076a12059a91 Mon Sep 17 00:00:00 2001 From: Jake Engelberg Date: Sun, 1 Dec 2024 15:51:37 -0500 Subject: [PATCH 2/4] match final implementation Signed-off-by: Jake Engelberg --- .../observability/metrics/metrics-overview.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/daprdocs/content/en/operations/observability/metrics/metrics-overview.md b/daprdocs/content/en/operations/observability/metrics/metrics-overview.md index deb7882cb25..25d8075e74a 100644 --- a/daprdocs/content/en/operations/observability/metrics/metrics-overview.md +++ b/daprdocs/content/en/operations/observability/metrics/metrics-overview.md @@ -72,8 +72,9 @@ spec: ## Configuring metrics for error codes -You can enable additional metrics for [Dapr API error codes](https://github.com/dapr/dapr/blob/master/docs/reference/api/error_codes/) by setting `spec.metrics.recordErrorCodes` to `true`. See the specific metrics described in the [Dapr development docs](https://github.com/dapr/dapr/blob/master/docs/development/dapr-metrics.md). +You can enable additional metrics for [Dapr API error codes](https://github.com/dapr/dapr/blob/master/docs/reference/api/error_codes/) by setting `spec.metrics.recordErrorCodes` to `true`. Dapr APIs which communicate back to its 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` will be recorded, which will allow monitoring of error codes triggered by application, code, and category. See [package errorcodes](https://github.com/dapr/dapr/blob/master/pkg/messages/errorcodes/errorcodes.go) for specific codes and categories. +Example configuration: ```yaml apiVersion: dapr.io/v1alpha1 kind: Configuration @@ -86,6 +87,21 @@ spec: recordErrorCodes: true ``` +Example metric: +```json +{ + app_id="publisher-app", + category="state", + dapr_io_enabled="true", + error_code="ERR_STATE_STORE_NOT_CONFIGURED", + instance="10.244.1.64:9090", + job="kubernetes-service-endpoints", + namespace="my-app", + node="my-node", + service="publisher-app-dapr" +} +``` + ## Optimizing HTTP metrics reporting with path matching When invoking Dapr using HTTP, metrics are created for each requested method by default. This can result in a high number of metrics, known as high cardinality, which can impact memory usage and CPU. From a44a96af104afe65f31518796b32bc28a1368135 Mon Sep 17 00:00:00 2001 From: Jake Engelberg Date: Tue, 3 Dec 2024 11:16:11 -0500 Subject: [PATCH 3/4] fix link, apply suggestion Signed-off-by: Jake Engelberg --- .../observability/metrics/metrics-overview.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/daprdocs/content/en/operations/observability/metrics/metrics-overview.md b/daprdocs/content/en/operations/observability/metrics/metrics-overview.md index 25d8075e74a..23fea29e6db 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://github.com/dapr/dapr/blob/master/docs/reference/api/error_codes/) by setting `spec.metrics.recordErrorCodes` to `true`. Dapr APIs which communicate back to its 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` will be recorded, which will allow monitoring of error codes triggered by application, code, and category. See [package errorcodes](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. 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. Example configuration: ```yaml @@ -90,15 +90,15 @@ spec: Example metric: ```json { - app_id="publisher-app", - category="state", - dapr_io_enabled="true", - error_code="ERR_STATE_STORE_NOT_CONFIGURED", - instance="10.244.1.64:9090", - job="kubernetes-service-endpoints", - namespace="my-app", - node="my-node", - service="publisher-app-dapr" + "app_id": "publisher-app", + "category": "state", + "dapr_io_enabled": "true", + "error_code": "ERR_STATE_STORE_NOT_CONFIGURED", + "instance": "10.244.1.64:9090", + "job": "kubernetes-service-endpoints", + "namespace": "my-app", + "node": "my-node", + "service": "publisher-app-dapr" } ``` From a3ebf07b94647a9e3777d3a37ad652469b69fad7 Mon Sep 17 00:00:00 2001 From: Jake Engelberg <152900222+jake-engelberg@users.noreply.github.com> Date: Fri, 13 Dec 2024 10:39:53 -0500 Subject: [PATCH 4/4] Building Block -> API Co-authored-by: Mark Fussell Signed-off-by: Jake Engelberg <152900222+jake-engelberg@users.noreply.github.com> --- .../content/en/reference/api/error_codes.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/daprdocs/content/en/reference/api/error_codes.md b/daprdocs/content/en/reference/api/error_codes.md index 2e18882aa07..c098521ccb5 100644 --- a/daprdocs/content/en/reference/api/error_codes.md +++ b/daprdocs/content/en/reference/api/error_codes.md @@ -17,7 +17,7 @@ For http calls made to Dapr runtime, when an error is encountered, an error json The following tables list the error codes returned by Dapr runtime: -### Actors (Building Block) +### Actors API | Error Code | Description | | -------------------------------- | ------------------------------------------ | @@ -34,7 +34,7 @@ The following tables list the error codes returned by Dapr runtime: | ERR_ACTOR_STATE_TRANSACTION_SAVE | Error storing actor state transactionally. | | ERR_ACTOR_REMINDER_NON_HOSTED | Error setting reminder for an actor. | -### Workflows (Building Block) +### Workflows API | Error Code | Description | | -------------------------------- | ----------------------------------------------------------- | @@ -54,7 +54,7 @@ The following tables list the error codes returned by Dapr runtime: | ERR_INSTANCE_ID_PROVIDED_MISSING | Error workflow instance ID was provided but missing. | | ERR_INSTANCE_ID_TOO_LONG | Error workflow instance ID exceeds allowable length. | -### State Management (Building Block) +### State Management API | Error Code | Description | | ------------------------------------- | ------------------------------------------------------------------------- | @@ -71,7 +71,7 @@ The following tables list the error codes returned by Dapr runtime: | ERR_STATE_STORE_NOT_SUPPORTED | Error state store is not supported. | | ERR_STATE_STORE_TOO_MANY_TRANSACTIONS | Error exceeded maximum allowable transactions. | -### Configuration (Building Block) +### Configuration API | Error Code | Description | | -------------------------------------- | -------------------------------------------- | @@ -81,7 +81,7 @@ The following tables list the error codes returned by Dapr runtime: | ERR_CONFIGURATION_SUBSCRIBE | Error subscribing to a configuration. | | ERR_CONFIGURATION_UNSUBSCRIBE | Error unsubscribing from a configuration. | -### Crypto (Building Block) +### Crypto API | Error Code | Description | | ----------------------------------- | ------------------------------------------ | @@ -90,7 +90,7 @@ The following tables list the error codes returned by Dapr runtime: | ERR_CRYPTO_PROVIDER_NOT_FOUND | Error specified crypto provider not found. | | ERR_CRYPTO_PROVIDERS_NOT_CONFIGURED | Error no crypto providers configured. | -### Secrets (Building Block) +### Secrets API | Error Code | Description | | -------------------------------- | ---------------------------------------------------- | @@ -99,7 +99,7 @@ The following tables list the error codes returned by Dapr runtime: | ERR_SECRET_GET | Error retrieving the specified secret. | | ERR_PERMISSION_DENIED | Error access denied due to insufficient permissions. | -### Pub/Sub (Building Block) +### Pub/Sub API | Error Code | Description | | --------------------------- | -------------------------------------------------------- | @@ -114,7 +114,7 @@ The following tables list the error codes returned by Dapr runtime: | ERR_PUBLISH_OUTBOX | Error publishing message to the outbox. | | ERR_TOPIC_NAME_EMPTY | Error topic name for Pub/Sub message is empty. | -### Conversation (Building Block) +### Conversation API | Error Code | Description | | ------------------------------- | ----------------------------------------------- | @@ -125,7 +125,7 @@ The following tables list the error codes returned by Dapr runtime: | ERR_CONVERSATION_MISSING_INPUTS | Error missing required inputs for conversation. | | ERR_CONVERSATION_NOT_FOUND | Error conversation not found. | -### Distributed Lock (Building Block) +### Distributed Lock API | Error Code | Description | | ----------------------------- | ----------------------------------- |