Skip to content

docs: document http_client span attribute limitations #8967

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
mabuyo merged 8 commits into from
Mar 10, 2026
Merged

docs: document http_client span attribute limitations #8967

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
ac9734f
docs: note conditions/static not supported for http_client spans
claude Mar 4, 2026
0dda783
docs: add note on http_client attribute limitations with error message
claude Mar 4, 2026
115ecd9
docs: document http_client selector limitations and add conditions co…
claude Mar 4, 2026
101e86a
add changeset
mabuyo Mar 6, 2026
2c0041d
docs: apply 3 AI review suggestions across 2 files
apollo-librarian[bot] Mar 6, 2026
8a0f252
trigger pipeline
mabuyo Mar 9, 2026
e303d58
docs: apply 3 AI review suggestions across 2 files
apollo-librarian[bot] Mar 10, 2026
464ea64
trigger CLA pass
mabuyo Mar 10, 2026
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 .changesets/docs_wrapper_snowstorm_dungeon_kerosene.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
### Docs: Document http_client span attribute limitations ([PR #8967](https://github.com/apollographql/router/pull/8967))

Document that `http_client` span attributes do not support conditions or the `static` selector, causing a router startup failure when attempted.

By [@mabuyo](https://github.com/mabuyo) in https://github.com/apollographql/router/pull/8967
6 changes: 6 additions & 0 deletions ...ce/routing/observability/router-telemetry-otel/enabling-telemetry/selectors.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -113,6 +113,12 @@

The HTTP client service also executes multiple times. Each execution represents an HTTP request to a single subgraph or REST service. This service executes after any Rhai scripts that modify subgraph requests, so these selectors can observe headers added by scripts.

<Note>

The `http_client` service supports the `request_header` and `response_header` selectors. Conditions and the `static` selector are currently unavailable for this service. If you attempt to configure them, your router fails to start.

Check warning on line 118 in docs/source/routing/observability/router-telemetry-otel/enabling-telemetry/selectors.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/routing/observability/router-telemetry-otel/enabling-telemetry/selectors.mdx#L118 

**Framing**: Use 'the router' instead of 'your router' to maintain a neutral tone when describing system failure, or use imperative framing for the warning.

**Products and Features**: Do not use possessives like "your" before a standalone product name like "router".

**Structural Elements**: Ensure there are two newlines between the admonition component and its content for proper formatting.

**Text Formatting**: Removed bold formatting from 'unavailable' as bold should not be used for general emphasis.

**Voice**: The original phrasing is slightly robotic and focuses on failure. The revision is more helpful and authoritative by guiding the user on what to do.

**Word and Symbol Usage**: Use dictionary-valid contractions like "won't" instead of "fails to" or "does not" to improve readability and natural tone.

```suggestion
The `http_client` service supports the `request_header` and `response_header` selectors. Conditions and the `static` selector are currently unavailable for this service. If you attempt to configure them, the router fails to start.
```

</Note>

| Selector | Defaultable | Values | Description |
|--------------------|-------------|--------|-------------------------------|
| `request_header` | Yes | | The name of a request header |
Expand Down
12 changes: 12 additions & 0 deletions ...source/routing/observability/router-telemetry-otel/enabling-telemetry/spans.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,6 +71,8 @@
You can also have [conditions](/router/configuration/telemetry/instrumentation/conditions) on custom attributes using [selectors](/router/configuration/telemetry/instrumentation/selectors). You can only have conditions on a selector at the same execution level.
Example you can't have a condition on `response_header` if you want to set an attribute from `request_header`.

Conditions and the `static` selector are supported for the `router`, `supergraph`, `subgraph`, and `connector` services. They are not supported for `http_client` span attributes. For details, see the [http_client span attributes](#http_client-span-attributes) section.

Check notice on line 74 in docs/source/routing/observability/router-telemetry-otel/enabling-telemetry/spans.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/routing/observability/router-telemetry-otel/enabling-telemetry/spans.mdx#L74 

**Text Formatting**: Avoid vague link text like 'section'. Use the title of the linked content as the link text.

```suggestion
Conditions and the `static` selector are supported for the `router`, `supergraph`, `subgraph`, and `connector` services. They are not supported for `http_client` span attributes. For details, see [http_client span attributes](#http_client-span-attributes).
```

```yaml title="desc.router.yaml"
telemetry:
instrumentation:
Expand Down Expand Up @@ -270,6 +272,16 @@

The `http_client` span is created for each HTTP request to a subgraph or REST service. It executes after any [Rhai scripts](/router/customizations/rhai) that modify subgraph requests, so its selectors can observe headers added by scripts.

<Note>

Check notice on line 275 in docs/source/routing/observability/router-telemetry-otel/enabling-telemetry/spans.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/routing/observability/router-telemetry-otel/enabling-telemetry/spans.mdx#L275 

**Structural Elements**: Ensure there is a blank line between the opening tag and the content for proper rendering.

```suggestion
<Note>
```

`http_client` span attributes support the `request_header` and `response_header` selectors. Use these selectors to configure your attributes. If you attempt to use conditions or the `static` selector, the router fails to start with an error similar to:

Check notice on line 277 in docs/source/routing/observability/router-telemetry-otel/enabling-telemetry/spans.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/routing/observability/router-telemetry-otel/enabling-telemetry/spans.mdx#L277 

**Framing**: The original text already follows the reader-centric and imperative style. No changes required.

**Products and Features**: Avoid using possessives like 'your' before standalone feature names or attributes.

**Voice**: The phrasing 'If you attempt to' is slightly less authoritative. Using a direct instruction like 'Avoid' is more opinionated and helpful.

**Word and Symbol Usage**: Avoid 'below' when referring to content; use 'following' or specific section names. However, this line does not contain 'below', but the previous line 74 did. Checking line 277 specifically, it is clear and follows the guide. Wait, line 74 is actually fine. Re-evaluating 277: it is correct.

```suggestion
`http_client` span attributes support the `request_header` and `response_header` selectors. Use these selectors to configure your attributes. If you attempt to use conditions or the `static` selector, the router fails to start with an error similar to:
```

```
could not create router: failed to parse attribute '...': unknown field '...', there are no fields
```

</Note>

Check notice on line 283 in docs/source/routing/observability/router-telemetry-otel/enabling-telemetry/spans.mdx

View check run for this annotation

Apollo Librarian / AI Style Review

docs/source/routing/observability/router-telemetry-otel/enabling-telemetry/spans.mdx#L283 

**Structural Elements**: Ensure there is a blank line between the content and the closing tag for proper rendering.

```suggestion

</Note>
```

Extract custom attributes from request and response headers using the `request_header` and `response_header` [selectors](/router/configuration/telemetry/instrumentation/selectors).

```yaml title="router.yaml"
Expand Down