feat: expose error types as a dimension and in expressions

docs-website/docs.json

@@ -95,7 +95,8 @@
                 "pages": [
                   "router/configuration",
                   "router/configuration/config-design",
-                  "router/configuration/template-expressions"
+                  "router/configuration/template-expressions",
+                  "router/configuration/error-types"
                 ]
               },
               "router/mcp",

docs-website/router/configuration/error-types.mdx

@@ -0,0 +1,30 @@
+---
+title: "Error Types"
+description: "Router error type classifications for metrics and expressions"
+icon: "triangle-exclamation"
+---
+
+When an error occurs during request processing, the router classifies it into one of the following types. This classification is available via:
+- **Expressions**: `request.errorType` and `subgraph.request.errorType` (see [Template Expressions](/router/configuration/template-expressions))
+- **Metrics**: the `wg.error.type` OTEL attribute (or `wg_error_type` in Prometheus)
+
+| Value | Description |
+|---|---|
+| `rate_limit` | The request was rejected because the client exceeded the configured rate limit. |
+| `unauthorized` | The request failed authentication or authorization. |
+| `context_canceled` | The request was canceled, typically because the client disconnected before the response was sent. |
+| `context_timeout` | The request timed out before a response could be produced. |
+| `upgrade_failed` | A WebSocket upgrade request to a subgraph failed. |
+| `edfs` | An error occurred in a Cosmo Streams (EDFS) data source. |
+| `invalid_ws_subprotocol` | The client requested an unsupported WebSocket subprotocol. |
+| `edfs_invalid_message` | A message received from a Cosmo Streams backend could not be parsed as valid JSON. |
+| `merge_result` | The router failed to merge results from multiple subgraph responses. |
+| `streams_handler_error` | An error occurred while handling a Cosmo Streams event. |
+| `operation_blocked` | The operation was rejected by the operation blocker (e.g. blocked operation type or safelist violation). |
+| `persisted_operation_not_found` | A persisted operation was requested but could not be found. |
+| `validation_error` | The GraphQL operation failed parsing or validation against the schema. |
+| `input_error` | The request body was malformed or otherwise invalid (e.g. invalid JSON, missing query). |
+| `subgraph_error` | One or more subgraphs returned an error during execution. |
+| `unknown` | An error occurred that does not match any known category. |
+| `publish_error` | A Cosmo Streams publish operation failed (Kafka, NATS, or Redis). Only appears on stream produce/consume metrics. |
+| `request_error` | A Cosmo Streams NATS request-reply operation failed. Only appears on stream produce/consume metrics. |

docs-website/router/configuration/template-expressions.mdx

@@ -58,6 +58,7 @@ The `request` object is a read-only entity that provides details about the incom
 - `request.url.port`
 - `request.trace.sampled`
 - `request.error`
+- `request.errorType` — The [error type classification](#error-types) as a string. Only set when an error occurred.
 
 ### Operation Object
 
@@ -163,6 +164,7 @@ It contains the following properties:
 #### SubgraphRequest Properties
 
 - `subgraph.request.error` (error): Any error that occurred during the subgraph request
+- `subgraph.request.errorType` (string): The [error type classification](#error-types) for the subgraph request. Only set when an error occurred.
 - `subgraph.request.clientTrace` (ClientTrace): Contains tracing information about the client connection
 
 #### SubgraphResponse Properties
@@ -242,6 +244,22 @@ request.error != nil ? response.body.raw : ''
 You can use expressions to specify the conditions for retries upon subgraph request failures. However, this uses a different expression context, which can be found [here](/router/traffic-shaping/retry#conditional-retry-with-expressions).
 
 
+### Error Types
+
+See the [Error Types](/router/configuration/error-types) reference for the full list of error classifications available via `request.errorType` and `subgraph.request.errorType`.
+
+#### Example expressions
+
+```bash
+# Log the response body only for unauthorized errors
+request.errorType == 'unauthorized' ? response.body.raw : ''
+```
+
+```bash
+# Check if a subgraph had a timeout
+subgraph.request.errorType == 'context_timeout'
+```
+
 ### Additional Notes
 
 - A Request for Comments (RFC) is [open](https://github.com/wundergraph/cosmo/pull/1481) for feedback on the complete API specification. Future implementations will be driven by customer requirements.

docs-website/router/metrics-and-monitoring.mdx

@@ -177,6 +177,8 @@ You can use the `router.http.requests.error` metric to track errors across route
 
 * `http.status_code`: The status code of the response.
 
+* `wg.error.type`: Classifies the error into a specific category. This attribute is attached to both router-level and subgraph-level request metrics when an error occurs. Only set when an error is present. See [Error Types](/router/configuration/error-types) for the full list of possible values.
+
 You have two ways to query for errors. Both metrics can be quite useful depending on the query scenario. In general, we recommend to use the `router.http.requests.error` metric.
 
 #### Subgraph specific
@@ -283,7 +285,7 @@ The name of the destination of the messaging backend (topic, queue, etc)
 The provider id as specified in the router configuration
 
 * `wg.error.type`:
-A generic error type to indicate an error occurred. This is available only for `router.streams.sent.messages` at this moment, as we do not catch message receive errors.
+The error type classification. For Cosmo Streams metrics, this indicates a send error. See [Error Types](/router/configuration/error-types) for the full list of possible values.
 
 
 ### Connection Metrics

docs-website/router/metrics-and-monitoring/prometheus-metric-reference.mdx

@@ -159,7 +159,7 @@ The name of the destination of the messaging backend (topic, queue, etc)
 The provider id as specified in the router configuration
 
 * `wg_error_type`:
-A generic error type to indicate an error occurred. This is available only for `router.streams.sent.messages` at this moment, as we do not catch message receive errors.
+The error type classification. For Cosmo Streams metrics, this indicates a send error. See [Error Types](/router/configuration/error-types) for the full list of possible values.
 
 #### Examples
 

router-tests/telemetry/telemetry_test.go

@@ -8463,6 +8463,7 @@ func TestFlakyTelemetry(t *testing.T) {
 									attribute.StringSlice("services", []string{"employees", "products"}),
 									attribute.StringSlice("error_services", []string{"products"}),
 									otel.WgRequestError.Bool(true),
+									otel.WgErrorType.String("unknown"),
 									otel.WgClientName.String("unknown"),
 									otel.WgClientVersion.String("missing"),
 									otel.WgFederatedGraphID.String("graph"),
@@ -8537,6 +8538,7 @@ func TestFlakyTelemetry(t *testing.T) {
 									semconv.HTTPStatusCode(200),
 									attribute.StringSlice("services", []string{"employees", "products"}),
 									otel.WgRequestError.Bool(true),
+									otel.WgErrorType.String("unknown"),
 									attribute.String("sha256", "b0066f89f91315b4610ed127be677e6cea380494eb20c83cc121c97552ca44b2"),
 									otel.WgClientName.String("unknown"),
 									otel.WgClientVersion.String("missing"),
@@ -8857,6 +8859,7 @@ func TestFlakyTelemetry(t *testing.T) {
 									otel.WgRouterClusterName.String(""),
 									otel.WgRouterConfigVersion.String(xEnv.RouterConfigVersionMain()),
 									otel.WgRouterVersion.String("dev"),
+									otel.WgErrorType.String("unknown"),
 								),
 								Value: 1,
 							},
@@ -9040,6 +9043,7 @@ func TestFlakyTelemetry(t *testing.T) {
 									attribute.StringSlice("services", []string{"employees", "products"}),
 									attribute.StringSlice("error_services", []string{"products"}),
 									otel.WgRequestError.Bool(true),
+									otel.WgErrorType.String("unknown"),
 									otel.WgClientName.String("unknown"),
 									otel.WgClientVersion.String("missing"),
 									otel.WgFederatedGraphID.String("graph"),
@@ -9114,6 +9118,7 @@ func TestFlakyTelemetry(t *testing.T) {
 									semconv.HTTPStatusCode(200),
 									attribute.StringSlice("services", []string{"employees", "products"}),
 									otel.WgRequestError.Bool(true),
+									otel.WgErrorType.String("unknown"),
 									attribute.String("sha256", "b0066f89f91315b4610ed127be677e6cea380494eb20c83cc121c97552ca44b2"),
 									otel.WgClientName.String("unknown"),
 									otel.WgClientVersion.String("missing"),
@@ -9434,6 +9439,7 @@ func TestFlakyTelemetry(t *testing.T) {
 									otel.WgRouterClusterName.String(""),
 									otel.WgRouterConfigVersion.String(xEnv.RouterConfigVersionMain()),
 									otel.WgRouterVersion.String("dev"),
+									otel.WgErrorType.String("unknown"),
 								),
 								Value: 1,
 							},

router/core/context.go

@@ -356,6 +356,7 @@ func (c *requestContext) SetCustomFieldValueRenderer(renderer resolve.FieldValue
 func (c *requestContext) SetError(err error) {
 	c.error = err
 	c.expressionContext.Request.Error = err
+	c.expressionContext.Request.ErrorType = getErrorType(err).String()
 }
 
 func (c *requestContext) Operation() OperationContext {

router/core/engine_loader_hooks.go

@@ -174,6 +174,7 @@ func (f *engineLoaderHooks) OnFinished(ctx context.Context, ds resolve.DataSourc
 	exprCtx.Subgraph.Id = ds.ID
 	exprCtx.Subgraph.Name = ds.Name
 	exprCtx.Subgraph.Request.Error = WrapExprError(responseInfo.Err)
+	exprCtx.Subgraph.Request.ErrorType = getErrorType(responseInfo.Err).String()
 
 	if value := ctx.Value(rcontext.FetchTimingKey); value != nil {
 		if fetchTiming, ok := value.(*atomic.Int64); ok {
@@ -293,7 +294,11 @@ func (f *engineLoaderHooks) OnFinished(ctx context.Context, ds resolve.DataSourc
 			metricSliceAttrs = append(metricSliceAttrs, attribute.StringSlice(v, errorCodesAttr))
 		}
 
-		f.metricStore.MeasureRequestError(ctx, metricSliceAttrs, metricAddOpt)
+		errType := getErrorType(responseInfo.Err)
+		errorTypeAttr := rotel.WgErrorType.String(errType.String())
+
+		metricAttrs = append(metricAttrs, errorTypeAttr)
+		f.metricStore.MeasureRequestError(ctx, metricSliceAttrs, otelmetric.WithAttributeSet(attribute.NewSet(metricAttrs...)))
 
 		metricAttrs = append(metricAttrs, rotel.WgRequestError.Bool(true))
 

router/core/errors.go

@@ -36,8 +36,50 @@ const (
 	errorTypeEDFSInvalidMessage
 	errorTypeMergeResult
 	errorTypeStreamsHandlerError
+	errorTypeOperationBlocked
+	errorTypePersistedOperationNotFound
+	errorTypeValidationError
+	errorTypeInputError
+	errorTypeSubgraphError
 )
 
+func (e errorType) String() string {
+	switch e {
+	case errorTypeRateLimit:
+		return "rate_limit"
+	case errorTypeUnauthorized:
+		return "unauthorized"
+	case errorTypeContextCanceled:
+		return "context_canceled"
+	case errorTypeContextTimeout:
+		return "context_timeout"
+	case errorTypeUpgradeFailed:
+		return "upgrade_failed"
+	case errorTypeEDFS:
+		return "edfs"
+	case errorTypeInvalidWsSubprotocol:
+		return "invalid_ws_subprotocol"
+	case errorTypeEDFSInvalidMessage:
+		return "edfs_invalid_message"
+	case errorTypeMergeResult:
+		return "merge_result"
+	case errorTypeStreamsHandlerError:
+		return "streams_handler_error"
+	case errorTypeOperationBlocked:
+		return "operation_blocked"
+	case errorTypePersistedOperationNotFound:
+		return "persisted_operation_not_found"
+	case errorTypeValidationError:
+		return "validation_error"
+	case errorTypeInputError:
+		return "input_error"
+	case errorTypeSubgraphError:
+		return "subgraph_error"
+	default:
+		return "unknown"
+	}
+}
+
 type (
 	GraphQLErrorResponse struct {
 		Errors     []graphqlError `json:"errors"`
@@ -64,6 +106,10 @@ func getErrorType(err error) errorType {
 	if errors.Is(err, context.Canceled) {
 		return errorTypeContextCanceled
 	}
+	var poNotFoundErr *persistedoperation.PersistentOperationNotFoundError
+	if errors.As(err, &poNotFoundErr) {
+		return errorTypePersistedOperationNotFound
+	}
 	var upgradeErr *graphql_datasource.UpgradeRequestError
 	if errors.As(err, &upgradeErr) {
 		return errorTypeUpgradeFailed
@@ -94,6 +140,20 @@ func getErrorType(err error) errorType {
 	if errors.As(err, &mergeResultErr) {
 		return errorTypeMergeResult
 	}
+	var reportErr ReportError
+	if errors.As(err, &reportErr) {
+		return errorTypeValidationError
+	}
+	var subgraphErr *resolve.SubgraphError
+	if errors.As(err, &subgraphErr) {
+		return errorTypeSubgraphError
+	}
+	var httpErr *httpGraphqlError
+	if errors.As(err, &httpErr) {
+		if httpErr.errorCategory != errorTypeUnknown {
+			return httpErr.errorCategory
+		}
+	}
 	return errorTypeUnknown
 }