docs: document http_client span attribute limitations - #8967
Style Review Completed
The pull request has 5 style issues.
Duration: 2990ms
PR URL: #8967
Review Log: View detailed log
Review Comments: The AI has posted 5 inline comments with suggestions
Summary of changes:
This pull request updates the documentation to align with several style guide requirements. Structural changes include ensuring proper spacing around tags and admonition components for correct rendering. Text formatting improvements involve replacing vague link text with descriptive titles and removing non-standard bold emphasis. Framing and products-and-features updates remove personal possessives like "your" in favor of a neutral or imperative tone. Voice adjustments replace robotic or passive phrasing with authoritative, reader-centric guidance. Finally, word and symbol usage was refined to include natural contractions and clear directional references.
Annotations
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>
```
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>
```
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).
```
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.
```
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:
```