Skip to content

feat: utf8 tracing sanitization documentaiton #253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SkArchon merged 1 commit into from
Feb 24, 2026
Merged

feat: utf8 tracing sanitization documentaiton #253

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/router/configuration.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -501,6 +501,8 @@ telemetry:
| TRACING_EXPORT_GRAPHQL_VARIABLES | export_graphql_variables | <Icon icon="square" /> | Export GraphQL variables as span attribute. Variables may contain sensitive data. | false |
| TRACING_OPERATION_CONTENT_ATTRIBUTES | operation_content_attributes | <Icon icon="square" /> | Enable the addition of GraphQL operation body content as trace attributes. When enabled, original operation content will be added to the trace span for parse and normalized operation content will be added to the trace span for normalize. The default value is false. | false |
| | with_new_root | <Icon icon="square" /> | Starts the root span always at the router. | false |
| TRACING_SANITIZE_UTF8_ENABLED | sanitize_utf8.enabled | <Icon icon="square" /> | Enable sanitization of invalid UTF-8 sequences in span attribute values. Invalid bytes are replaced with the Unicode replacement character (U+FFFD). See [Sanitize UTF-8](/router/open-telemetry#sanitize-utf-8). | false |
| TRACING_SANITIZE_UTF8_LOG_SANITIZATIONS | sanitize_utf8.log_sanitizations | <Icon icon="square" /> | When enabled, logs a warning for each span attribute that contains invalid UTF-8 and is sanitized. | false |

### Example YAML config:

Expand All @@ -521,6 +523,9 @@ telemetry:
export_graphql_variables: false
operation_content_attributes: false
with_new_root: false
sanitize_utf8:
enabled: false
log_sanitizations: false
```

### Exporters
Expand Down
25 changes: 25 additions & 0 deletions docs/router/open-telemetry.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,6 +177,31 @@ telemetry:
header_name: "my-trace-id" # default: "x-wg-trace-id"
```

### Sanitize UTF-8

OTLP uses Protocol Buffers for serialization, and protobuf's `string` type requires valid UTF-8. When subgraphs or upstream services return responses containing invalid UTF-8 byte sequences (e.g., from binary data or legacy encodings), these invalid bytes can end up in span attributes, causing the protobuf marshaler to fail with errors like `"string field contains invalid UTF-8"`. This results in the entire span export failing and trace data being silently dropped.

Enabling `sanitize_utf8` replaces any invalid UTF-8 sequences in string span attributes with the Unicode replacement character (`U+FFFD`). This ensures that traces are always exported successfully, even when upstream data contains encoding issues.

<Info>
This feature is disabled by default. Enable it if you observe missing traces caused by OTEL export errors related to invalid UTF-8 in string fields.
</Info>

<CodeGroup>
```bash config.yaml
telemetry:
tracing:
sanitize_utf8:
enabled: true
# Optional: log a warning for each sanitized attribute (useful for debugging)
log_sanitizations: false
```
</CodeGroup>

<Note>
In addition to span attributes, the router also sanitizes invalid UTF-8 in span status descriptions (e.g., error messages). This happens automatically and does not require any configuration.
</Note>

## FAQ

<AccordionGroup>
Expand Down