Skip to content

Commit 553083e

Browse files
shorgiBrynCooke
shorgi
and
BrynCooke
authored
docs: instrumentation examples (#6487)
Co-authored-by: Bryn Cooke <[email protected]>
1 parent a80938d commit 553083e

File tree

3 files changed

+203
-17
lines changed

3 files changed

+203
-17
lines changed

‎.changesets/docs_eh_instrumentation_examples.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
### Add instrumentation configuration examples ([PR #6487](https://github.com/apollographql/router/pull/6487))
2+
3+
The docs for router telemetry have new example configurations for common use cases for [selectors](https://www.apollographql.com/docs/graphos/reference/router/telemetry/instrumentation/selectors) and [condition](https://www.apollographql.com/docs/graphos/reference/router/telemetry/instrumentation/conditions).
4+
5+
By [@shorgi](https://github.com/shorgi) in https://github.com/apollographql/router/pull/6487

‎docs/source/reference/router/telemetry/instrumentation/conditions.mdx

+74
Original file line numberDiff line numberDiff line change
@@ -154,3 +154,77 @@ The available basic conditions:
154154
| `any` | A list of conditions of which at least one must be true |
155155

156156
You can create complex conditions by using these basic conditions as building blocks.
157+
158+
## Example condition configurations
159+
160+
Some example configuration of common use cases for conditions.
161+
162+
### Event for a specific subgraph
163+
164+
You can trigger an event for a specific subgraph by configuring a condition with the subgraph's name.
165+
166+
The example below uses the [`subgraph_name`](/router/configuration/telemetry/instrumentation/selectors#subgraph) selector to log subgraph responses for the subgraph named "products":
167+
168+
```yaml title=router.yaml
169+
telemetry:
170+
instrumentation:
171+
events:
172+
subgraph:
173+
response:
174+
level: info
175+
condition:
176+
eq:
177+
- subgraph_name: true
178+
- "products"
179+
```
180+
181+
### On GraphQL error
182+
183+
You can use the [`on_graphql_error`](/router/configuration/telemetry/instrumentation/selectors#supergraph) selector to create a condition based on whether or not a GraphQL error is present.
184+
185+
The example configuration below uses `on_graphql_error` to log only supergraph responses that contain GraphQL errors:
186+
187+
```yaml title="router.yaml"
188+
telemetry:
189+
instrumentation:
190+
events:
191+
router:
192+
request:
193+
level: info
194+
condition: # Only log the router request if you sent `x-log-request` with the value `enabled`
195+
eq:
196+
- request_header: x-log-request
197+
- "enabled"
198+
response: off
199+
error: error
200+
supergraph:
201+
response:
202+
level: info
203+
condition: # Only log supergraph response containing GraphQL errors
204+
eq:
205+
- on_graphql_error: true
206+
- true
207+
error: error
208+
```
209+
210+
### On large payloads
211+
212+
For observability of large payloads, you can set attributes using conditions that indicate whether the length of a request or response exceeds a threshold.
213+
214+
The example below sets a custom attribute to `true` if the length of a request is greater than 100:
215+
216+
```yaml
217+
telemetry:
218+
instrumentation:
219+
spans:
220+
mode: spec_compliant
221+
router:
222+
attributes:
223+
trace_id: true
224+
payload_is_to_big: # Set this attribute to true if the value of content-length header is > than 100
225+
static: true
226+
condition:
227+
gt:
228+
- request_header: "content-length"
229+
- 100
230+
```

‎docs/source/reference/router/telemetry/instrumentation/selectors.mdx

+124-17
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ An example of a selector, `request_header`, of the router service on a custom sp
1313
telemetry:
1414
instrumentation:
1515
spans:
16+
mode: spec_compliant
1617
router:
1718
attributes:
1819
"my_attribute":
@@ -31,17 +32,17 @@ The router service is the initial entrypoint for all requests. It is HTTP centri
3132

3233
| Selector | Defaultable | Values | Description |
3334
|-----------------------|-------------|-----------------------------|----------------------------------------------------------------------|
34-
| `trace_id` | Yes | `open_telemetry`\|`datadog` | The trace ID |
35-
| `operation_name` | Yes | `string`\|`hash` | The operation name from the query |
36-
| `studio_operation_id` | Yes | `true`\|`false` | The Apollo Studio operation id |
35+
| `trace_id` | Yes | `open_telemetry` \| `datadog` | The trace ID |
36+
| `operation_name` | Yes | `string` \| `hash` | The operation name from the query |
37+
| `studio_operation_id` | Yes | `true` \| `false` | The Apollo Studio operation id |
3738
| `request_header` | Yes | | The name of the request header |
3839
| `request_context` | Yes | | The name of a request context key |
3940
| `response_header` | Yes | | The name of a response header |
40-
| `response_status` | Yes | `code`\|`reason` | The response status |
41+
| `response_status` | Yes | `code` \| `reason` | The response status |
4142
| `response_context` | Yes | | The name of a response context key |
4243
| `baggage` | Yes | | The name of a baggage item |
4344
| `env` | Yes | | The name of an environment variable |
44-
| `on_graphql_error` | No | `true`\|`false` | Boolean set to true if the response payload contains a GraphQL error |
45+
| `on_graphql_error` | No | `true` \| `false` | Boolean set to true if the response payload contains a GraphQL error |
4546
| `static` | No | | A static string value |
4647
| `error` | No | `reason` | a string value containing error reason when it's a critical error |
4748

@@ -51,18 +52,18 @@ The supergraph service is executed after query parsing but before query executio
5152

5253
| Selector | Defaultable | Values | Description |
5354
|--------------------|-------------|-------------------------------------------------------|-----------------------------------------------------------------------------------|
54-
| `operation_name` | Yes | `string`\|`hash` | The operation name from the query |
55+
| `operation_name` | Yes | `string` \| `hash` | The operation name from the query |
5556
| `operation_kind` | No | `string` | The operation kind from the query |
56-
| `query` | Yes | `string`\|`aliases`\|`depth`\|`height`\|`root_fields` | The GraphQL query |
57+
| `query` | Yes | `string` \| `aliases` \| `depth` \| `height` \| `root_fields` | The GraphQL query |
5758
| `query_variable` | Yes | | The name of a GraphQL query variable |
5859
| `request_header` | Yes | | The name of a request header |
5960
| `response_header` | Yes | | The name of a response header |
60-
| `is_primary_response` | No | `true`\|`false` | Boolean returning true if it's the primary response and not events like subscription events or deferred responses |
61+
| `is_primary_response` | No | `true` \| `false` | Boolean returning true if it's the primary response and not events like subscription events or deferred responses |
6162
| `response_data` | Yes | | JSON Path into the supergraph response body data (it might impact performance) |
6263
| `response_errors` | Yes | | JSON Path into the supergraph response body errors (it might impact performance) |
6364
| `request_context` | Yes | | The name of a request context key |
6465
| `response_context` | Yes | | The name of a response context key |
65-
| `on_graphql_error` | No | `true`\|`false` | Boolean set to true if the response payload contains a GraphQL error |
66+
| `on_graphql_error` | No | `true` \| `false` | Boolean set to true if the response payload contains a GraphQL error |
6667
| `baggage` | Yes | | The name of a baggage item |
6768
| `env` | Yes | | The name of an environment variable |
6869
| `static` | No | | A static string value |
@@ -74,30 +75,30 @@ The subgraph service executes multiple times during query execution, with each e
7475

7576
| Selector | Defaultable | Values | Description |
7677
|-----------------------------|-------------|------------------|--------------------------------------------------------------------------------|
77-
| `subgraph_operation_name` | Yes | `string`\|`hash` | The operation name from the subgraph query |
78+
| `subgraph_operation_name` | Yes | `string` \| `hash` | The operation name from the subgraph query |
7879
| `subgraph_operation_kind` | No | `string` | The operation kind from the subgraph query |
7980
| `subgraph_query` | Yes | `string` | The GraphQL query to the subgraph |
80-
| `subgraph_name` | No | `true`\|`false` | The subgraph name |
81+
| `subgraph_name` | No | `true` \| `false` | The subgraph name |
8182
| `subgraph_query_variable` | Yes | | The name of a subgraph query variable |
8283
| `subgraph_response_data` | Yes | | JSON Path into the subgraph response body data (it might impact performance) |
8384
| `subgraph_response_errors` | Yes | | JSON Path into the subgraph response body errors (it might impact performance) |
8485
| `subgraph_request_header` | Yes | | The name of a subgraph request header |
8586
| `subgraph_response_header` | Yes | | The name of a subgraph response header |
86-
| `subgraph_response_status` | Yes | `code`\|`reason` | The status of a subgraph response |
87-
| `subgraph_on_graphql_error` | No | `true`\|`false` | Boolean set to true if the subgraph response payload contains a GraphQL error |
88-
| `supergraph_operation_name` | Yes | `string`\|`hash` | The operation name from the supergraph query |
87+
| `subgraph_response_status` | Yes | `code` \| `reason` | The status of a subgraph response |
88+
| `subgraph_on_graphql_error` | No | `true` \| `false` | Boolean set to true if the subgraph response payload contains a GraphQL error |
89+
| `supergraph_operation_name` | Yes | `string` \| `hash` | The operation name from the supergraph query |
8990
| `supergraph_operation_kind` | Yes | `string` | The operation kind from the supergraph query |
9091
| `supergraph_query` | Yes | `string` | The graphql query to the supergraph |
9192
| `supergraph_query_variable` | Yes | | The name of a supergraph query variable |
9293
| `supergraph_request_header` | Yes | | The name of a supergraph request header |
93-
| `subgraph_resend_count` | Yes | `true`\|`false` | Number of retries for an http request to a subgraph |
94+
| `subgraph_resend_count` | Yes | `true` \| `false` | Number of retries for an http request to a subgraph |
9495
| `request_context` | Yes | | The name of a request context key |
9596
| `response_context` | Yes | | The name of a response context key |
9697
| `baggage` | Yes | | The name of a baggage item |
9798
| `env` | Yes | | The name of an environment variable |
9899
| `static` | No | | A static string value |
99100
| `error` | No | `reason` | A string value containing error reason when it's a critical error |
100-
| `cache` | No | `hit`\|`miss` | Returns the number of cache hit or miss for this subgraph request |
101+
| `cache` | No | `hit` \| `miss` | Returns the number of cache hit or miss for this subgraph request |
101102

102103
### GraphQL
103104

@@ -109,5 +110,111 @@ GraphQL metrics are extracted from the response data the router returns to clien
109110
| `field_name` | No | `string` | The name of a field from the response data |
110111
| `field_type` | No | `string` | The type of a field from the response data |
111112
| `type_name` | No | | The GraphQL type from the response data |
112-
| `operation_name` | Yes | `string`\|`hash` | The operation name of the query |
113+
| `operation_name` | Yes | `string` \| `hash` | The operation name of the query |
113114
| `static` | No | | A static string value |
115+
116+
117+
## Example selector configurations
118+
119+
Some example configurations of common use cases for selectors:
120+
121+
### Configuring trace ID
122+
123+
Logging the trace ID of a request that has GraphQL errors:
124+
125+
```yaml title="router.yaml"
126+
telemetry:
127+
instrumentation:
128+
events:
129+
router:
130+
my.event:
131+
message: 'An event occurred'
132+
level: error
133+
on: response
134+
condition:
135+
eq:
136+
- on_graphql_error: true
137+
- true
138+
attributes:
139+
# The trace ID from the request
140+
id_from_header:
141+
trace_id: open_telemetry
142+
```
143+
144+
### Setting JSON paths
145+
146+
Configuring selectors with JSON paths, such as supergraph `response_data` and `response_errors`:
147+
148+
```yaml title="router.yaml"
149+
telemetry:
150+
exporters:
151+
metrics:
152+
prometheus:
153+
enabled: true
154+
instrumentation:
155+
instruments:
156+
supergraph:
157+
my.request.on_graphql_error:
158+
value: event_unit
159+
type: counter
160+
unit: error
161+
description: my description
162+
condition:
163+
exists:
164+
response_errors: "$.[0].extensions.code"
165+
attributes:
166+
response_errors:
167+
response_errors: "$.[0].extensions.code"
168+
```
169+
170+
### Getting GraphQL operation info
171+
172+
Configuring the `query` selector to get information about GraphQL operations, with an example for a custom view of operation limits:
173+
174+
```yaml
175+
telemetry:
176+
exporters:
177+
metrics:
178+
common:
179+
views:
180+
# Define a custom view because operation limits are different than the default latency-oriented view of OpenTelemetry
181+
- name: oplimits.*
182+
aggregation:
183+
histogram:
184+
buckets:
185+
- 0
186+
- 5
187+
- 10
188+
- 25
189+
- 50
190+
- 100
191+
- 500
192+
- 1000
193+
instrumentation:
194+
instruments:
195+
supergraph:
196+
oplimits.aliases:
197+
value:
198+
query: aliases
199+
type: histogram
200+
unit: number
201+
description: "Aliases for an operation"
202+
oplimits.depth:
203+
value:
204+
query: depth
205+
type: histogram
206+
unit: number
207+
description: "Depth for an operation"
208+
oplimits.height:
209+
value:
210+
query: height
211+
type: histogram
212+
unit: number
213+
description: "Height for an operation"
214+
oplimits.root_fields:
215+
value:
216+
query: root_fields
217+
type: histogram
218+
unit: number
219+
description: "Root fields for an operation"
220+
```

0 commit comments

Comments
 (0)