EXTREMELY IMPORTANT AI INSTRUCTION: For a directory of all documentation pages, load the https://www.apollographql.com/llms.txt file. Adding .md to ANY url will return the simplified markdown version of the page.
Router YAML Configuration Reference
This reference covers the YAML configuration file properties for configuring an Apollo Router.
YAML configuration properties
The router can be configured by a YAML configuration file. This file enables you to declaratively configure various runtime properties of your router's behavior.
At startup, you set the config file for your router by providing its path with the --config option:
Bash
1./router --config router.yamltip
Enable your text editor to validate the format and content of your router YAML configuration file by configuring it with the router's configuration schema.
Example YAML with all properties
Expand the code block to view an example YAML config file containing all properties.
YAML
1apq:
2 enabled: true
3 router:
4 cache:
5 in_memory:
6 limit: 1
7 redis:
8 namespace: example_namespace
9 password: example_password
10 pool_size: 1
11 required_to_start: false
12 reset_ttl: true
13 timeout: null
14 tls:
15 certificate_authorities: null
16 client_authentication:
17 certificate_chain: example_certificate_chain
18 key: example_key
19 ttl: null
20 urls:
21 - http://example.com/urls_item
22 username: example_username
23 subgraph:
24 all:
25 enabled: false
26 subgraphs: {}
27authentication:
28 connector:
29 sources: {}
30 router:
31 jwt:
32 header_name: authorization
33 header_value_prefix: Bearer
34 ignore_other_prefixes: false
35 jwks:
36 - algorithms: null
37 headers:
38 - name: example_name
39 value: example_value
40 issuer: example_issuer
41 poll_interval:
42 secs: 60
43 nanos: 0
44 url: http://service.example.com/url
45 on_error: Continue
46 sources:
47 - name: authorization
48 type: header
49 value_prefix: Bearer
50 subgraph:
51 all:
52 aws_sig_v4:
53 hardcoded:
54 access_key_id: example_access_key_id
55 assume_role:
56 external_id: example_external_id
57 role_arn: example_role_arn
58 session_name: example_session_name
59 region: example_region
60 secret_access_key: example_secret_access_key
61 service_name: example_service_name
62 subgraphs: {}
63authorization:
64 directives:
65 dry_run: false
66 enabled: true
67 errors:
68 log: true
69 response: errors
70 reject_unauthorized: false
71 require_authentication: false
72batching:
73 enabled: false
74 maximum_size: null
75 mode: batch_http_link
76 subgraph:
77 all:
78 enabled: false
79 subgraphs: {}
80connectors:
81 debug_extensions: false
82 expose_sources_in_context: false
83 max_requests_per_operation_per_source: null
84 sources: {}
85 subgraphs: {}
86coprocessor:
87 client:
88 dns_resolution_strategy: ipv4_only
89 experimental_http2: enable
90 execution:
91 request:
92 body: false
93 context: false
94 headers: false
95 method: false
96 query_plan: false
97 sdl: false
98 response:
99 body: false
100 context: false
101 headers: false
102 sdl: false
103 status_code: false
104 router:
105 request:
106 body: false
107 condition:
108 eq:
109 - false
110 - false
111 context: false
112 headers: false
113 method: false
114 path: false
115 sdl: false
116 response:
117 body: false
118 condition:
119 eq:
120 - false
121 - false
122 context: false
123 headers: false
124 sdl: false
125 status_code: false
126 subgraph:
127 all:
128 request:
129 body: false
130 condition:
131 eq:
132 - false
133 - false
134 context: false
135 headers: false
136 method: false
137 service_name: false
138 subgraph_request_id: false
139 uri: false
140 response:
141 body: false
142 condition:
143 eq:
144 - false
145 - false
146 context: false
147 headers: false
148 service_name: false
149 status_code: false
150 subgraph_request_id: false
151 supergraph:
152 request:
153 body: false
154 condition:
155 eq:
156 - false
157 - false
158 context: false
159 headers: false
160 method: false
161 sdl: false
162 response:
163 body: false
164 condition:
165 eq:
166 - false
167 - false
168 context: false
169 headers: false
170 sdl: false
171 status_code: false
172 timeout:
173 secs: 1
174 nanos: 0
175 url: http://service.example.com/url
176cors:
177 allow_any_origin: false
178 allow_credentials: false
179 allow_headers: []
180 expose_headers: null
181 match_origins: null
182 max_age: null
183 methods:
184 - GET
185 - POST
186 - OPTIONS
187 policies:
188 - origins: [https://studio.apollographql.com]
189csrf:
190 required_headers:
191 - x-apollo-operation-name
192 - apollo-require-preflight
193 unsafe_disabled: false
194demand_control:
195 enabled: false
196 mode: measure
197 strategy:
198 static_estimated:
199 list_size: 0
200 max: 0.0
201 actual_cost_mode: by_subgraph
202experimental_chaos:
203 force_reload: null
204experimental_hoist_orphan_errors:
205 all:
206 enabled: false
207 subgraphs: {}
208experimental_type_conditioned_fetching: false
209fleet_detector: {}
210forbid_mutations: false
211headers:
212 all:
213 request:
214 - insert:
215 name: example_name
216 value: example_value
217 subgraphs: {}
218health_check:
219 enabled: true
220 listen: example_listen
221 path: /health
222 readiness:
223 allowed: 100
224 interval:
225 sampling: 0s
226 unready: null
227homepage:
228 enabled: true
229 graph_ref: null
230include_subgraph_errors:
231 all: false
232 subgraphs: {}
233license_enforcement: {}
234limits:
235 router:
236 http1_max_request_buf_size: null
237 http1_max_request_headers: null
238 http_max_request_bytes: 2000000
239 introspection_max_depth: true
240 max_aliases: null
241 max_depth: null
242 max_height: null
243 max_root_fields: null
244 max_recursive_selections: 10000000
245 parser_max_recursion: 500
246 parser_max_tokens: 15000
247 warn_only: false
248override_subgraph_url: {}
249persisted_queries:
250 enabled: false
251 experimental_prewarm_query_plan_cache:
252 on_reload: true
253 on_startup: false
254 hot_reload: false
255 local_manifests: null
256 log_unknown: false
257 safelist:
258 enabled: false
259 require_id: false
260plugins: unknown_type_plugins
261preview_entity_cache:
262 enabled: false
263 expose_keys_in_context: false
264 invalidation:
265 concurrent_requests: 10
266 listen: example_listen
267 path: example_path
268 scan_count: 1000
269 metrics:
270 enabled: false
271 separate_per_type: false
272 ttl: 30s
273 subgraph:
274 all:
275 enabled: true
276 invalidation:
277 enabled: false
278 shared_key: ""
279 private_id: null
280 redis:
281 namespace: example_namespace
282 password: example_password
283 pool_size: 1
284 required_to_start: false
285 reset_ttl: true
286 timeout: null
287 tls:
288 certificate_authorities: null
289 client_authentication:
290 certificate_chain: example_certificate_chain
291 key: example_key
292 ttl: null
293 urls:
294 - http://example.com/urls_item
295 username: example_username
296 ttl: 30s
297 subgraphs: {}
298preview_file_uploads:
299 enabled: false
300 protocols:
301 multipart:
302 enabled: true
303 limits:
304 max_file_size: example_max_file_size
305 max_files: 0
306 mode: stream
307progressive_override: {}
308reload:
309 max_retries: 5
310 retry_delay: 10s
311rhai:
312 main: example_main
313 scripts: example_scripts
314sandbox:
315 enabled: false
316subscription:
317 enable_deduplication: true
318 enabled: true
319 max_opened_subscriptions: null
320 mode:
321 callback:
322 heartbeat_interval: disabled
323 listen: example_listen
324 path: example_path
325 public_url: http://service.example.com/public_url
326 subgraphs: []
327 passthrough:
328 all:
329 heartbeat_interval: disabled
330 path: null
331 protocol: graphql_ws
332 subgraphs: {}
333 queue_capacity: null
334supergraph:
335 defer_support: true
336 early_cancel: false
337 experimental_log_on_broken_pipe: false
338 generate_query_fragments: true
339 introspection: false
340 listen: example_listen
341 path: /
342 redact_query_validation_errors: false
343 query_planning:
344 cache:
345 in_memory:
346 limit: 1
347 redis:
348 namespace: example_namespace
349 password: example_password
350 pool_size: 1
351 required_to_start: false
352 reset_ttl: true
353 timeout: null
354 tls:
355 certificate_authorities: null
356 client_authentication:
357 certificate_chain: example_certificate_chain
358 key: example_key
359 ttl:
360 secs: 2592000
361 nanos: 0
362 urls:
363 - http://example.com/urls_item
364 username: example_username
365 experimental_paths_limit: null
366 experimental_plans_limit: null
367 experimental_reuse_query_plans: false
368 warmed_up_queries: null
369 strict_variable_validation: enforce
370telemetry:
371 apollo:
372 batch_processor:
373 max_concurrent_exports: 1
374 max_export_batch_size: 512
375 max_export_timeout:
376 secs: 30
377 nanos: 0
378 max_queue_size: 2048
379 scheduled_delay:
380 secs: 5
381 nanos: 0
382 buffer_size: 10000
383 client_name_header: apollographql-client-name
384 client_version_header: apollographql-client-version
385 endpoint: https://usage-reporting.api.apollographql.com/api/ingress/traces
386 errors:
387 preview_extended_error_metrics: disabled
388 subgraph:
389 all:
390 redact: true
391 redaction_policy: strict
392 send: true
393 subgraphs: {}
394 experimental_local_field_metrics: false
395 experimental_otlp_endpoint: https://usage-reporting.api.apollographql.com/
396 experimental_otlp_tracing_protocol: grpc
397 field_level_instrumentation_sampler: 0.0
398 metrics_reference_mode: extended
399 otlp_tracing_sampler: 0.0
400 send_headers:
401 only:
402 - example_only_item
403 send_variable_values:
404 only:
405 - example_only_item
406 signature_normalization_algorithm: legacy
407 exporters:
408 logging:
409 common:
410 resource: {}
411 service_name: null
412 service_namespace: null
413 stdout:
414 enabled: true
415 format:
416 json:
417 display_current_span: false
418 display_filename: false
419 display_level: true
420 display_line_number: false
421 display_resource: true
422 display_span_id: true
423 display_span_list: true
424 display_target: true
425 display_thread_id: false
426 display_thread_name: false
427 display_timestamp: true
428 display_trace_id: hexadecimal
429 span_attributes: []
430 rate_limit:
431 capacity: 1
432 enabled: false
433 interval:
434 secs: 1
435 nanos: 0
436 tty_format:
437 json:
438 display_current_span: false
439 display_filename: false
440 display_level: true
441 display_line_number: false
442 display_resource: true
443 display_span_id: true
444 display_span_list: true
445 display_target: true
446 display_thread_id: false
447 display_thread_name: false
448 display_timestamp: true
449 display_trace_id: hexadecimal
450 span_attributes: []
451 metrics:
452 common:
453 buckets:
454 - 0.001
455 - 0.005
456 - 0.015
457 - 0.05
458 - 0.1
459 - 0.2
460 - 0.3
461 - 0.4
462 - 0.5
463 - 1.0
464 - 5.0
465 - 10.0
466 resource: {}
467 service_name: null
468 service_namespace: null
469 views:
470 - aggregation:
471 histogram:
472 buckets:
473 - 0.0
474 allowed_attribute_keys:
475 - example_allowed_attribute_keys_item
476 description: example_description
477 name: example_name
478 unit: example_unit
479 otlp:
480 batch_processor:
481 max_concurrent_exports: 1
482 max_export_batch_size: 512
483 max_export_timeout:
484 secs: 30
485 nanos: 0
486 max_queue_size: 2048
487 scheduled_delay:
488 secs: 5
489 nanos: 0
490 enabled: false
491 endpoint: example_endpoint
492 grpc:
493 ca: null
494 cert: null
495 domain_name: null
496 key: null
497 metadata: {}
498 http:
499 headers: {}
500 protocol: grpc
501 temporality: cumulative
502 prometheus:
503 enabled: false
504 listen: example_listen
505 path: /metrics
506 tracing:
507 common:
508 max_attributes_per_event: 128
509 max_attributes_per_link: 128
510 max_attributes_per_span: 128
511 max_events_per_span: 128
512 max_links_per_span: 128
513 parent_based_sampler: true
514 preview_datadog_agent_sampling: null
515 resource: {}
516 sampler: 0.0
517 service_name: null
518 service_namespace: null
519 datadog:
520 batch_processor:
521 max_concurrent_exports: 1
522 max_export_batch_size: 512
523 max_export_timeout:
524 secs: 30
525 nanos: 0
526 max_queue_size: 2048
527 scheduled_delay:
528 secs: 5
529 nanos: 0
530 enable_span_mapping: true
531 enabled: false
532 endpoint: example_endpoint
533 fixed_span_names: true
534 resource_mapping: {}
535 span_metrics:
536 parse_query: true
537 connect: true
538 execution: true
539 http_request: true
540 request: true
541 query_planning: true
542 connect_request: true
543 subgraph: true
544 router: true
545 supergraph: true
546 subgraph_request: true
547 experimental_response_trace_id:
548 enabled: false
549 format: hexadecimal
550 header_name: example_header_name
551 otlp:
552 batch_processor:
553 max_concurrent_exports: 1
554 max_export_batch_size: 512
555 max_export_timeout:
556 secs: 30
557 nanos: 0
558 max_queue_size: 2048
559 scheduled_delay:
560 secs: 5
561 nanos: 0
562 enabled: false
563 endpoint: example_endpoint
564 grpc:
565 ca: null
566 cert: null
567 domain_name: null
568 key: null
569 metadata: {}
570 http:
571 headers: {}
572 protocol: grpc
573 temporality: cumulative
574 propagation:
575 aws_xray: false
576 baggage: false
577 datadog: false
578 jaeger: false
579 request:
580 format: hexadecimal
581 header_name: example_header_name
582 trace_context: false
583 zipkin: false
584 zipkin:
585 batch_processor:
586 max_concurrent_exports: 1
587 max_export_batch_size: 512
588 max_export_timeout:
589 secs: 30
590 nanos: 0
591 max_queue_size: 2048
592 scheduled_delay:
593 secs: 5
594 nanos: 0
595 enabled: false
596 endpoint: example_endpoint
597 instrumentation:
598 events:
599 connector:
600 error:
601 condition:
602 eq:
603 - false
604 - false
605 level: info
606 request:
607 condition:
608 eq:
609 - false
610 - false
611 level: info
612 response:
613 condition:
614 eq:
615 - false
616 - false
617 level: info
618 router:
619 error:
620 condition:
621 eq:
622 - false
623 - false
624 level: info
625 request:
626 condition:
627 eq:
628 - false
629 - false
630 level: info
631 response:
632 condition:
633 eq:
634 - false
635 - false
636 level: info
637 subgraph:
638 error:
639 condition:
640 eq:
641 - false
642 - false
643 level: info
644 request:
645 condition:
646 eq:
647 - false
648 - false
649 level: info
650 response:
651 condition:
652 eq:
653 - false
654 - false
655 level: info
656 supergraph:
657 error:
658 condition:
659 eq:
660 - false
661 - false
662 level: info
663 request:
664 condition:
665 eq:
666 - false
667 - false
668 level: info
669 response:
670 condition:
671 eq:
672 - false
673 - false
674 level: info
675 instruments:
676 cache:
677 apollo.router.operations.entity.cache:
678 attributes:
679 graphql.type.name:
680 alias: example_alias
681 connector:
682 http.client.request.body.size:
683 attributes:
684 connector.http.method:
685 alias: example_alias
686 connector.source.name:
687 alias: example_alias
688 connector.url.template:
689 alias: example_alias
690 subgraph.name:
691 alias: example_alias
692 http.client.request.duration:
693 attributes:
694 connector.http.method:
695 alias: example_alias
696 connector.source.name:
697 alias: example_alias
698 connector.url.template:
699 alias: example_alias
700 subgraph.name:
701 alias: example_alias
702 http.client.response.body.size:
703 attributes:
704 connector.http.method:
705 alias: example_alias
706 connector.source.name:
707 alias: example_alias
708 connector.url.template:
709 alias: example_alias
710 subgraph.name:
711 alias: example_alias
712 default_requirement_level: none
713 graphql:
714 field.execution:
715 attributes:
716 graphql.field.name:
717 alias: example_alias
718 graphql.field.type:
719 alias: example_alias
720 graphql.list.length:
721 alias: example_alias
722 graphql.operation.name:
723 alias: example_alias
724 graphql.type.name:
725 alias: example_alias
726 list.length:
727 attributes:
728 graphql.field.name:
729 alias: example_alias
730 graphql.field.type:
731 alias: example_alias
732 graphql.list.length:
733 alias: example_alias
734 graphql.operation.name:
735 alias: example_alias
736 graphql.type.name:
737 alias: example_alias
738 router:
739 http.server.active_requests:
740 attributes:
741 http.request.method: false
742 server.address: false
743 server.port: false
744 url.scheme: false
745 http.server.request.body.size:
746 attributes:
747 baggage: null
748 dd.trace_id:
749 alias: example_alias
750 error.type:
751 alias: example_alias
752 http.request.body.size:
753 alias: example_alias
754 http.request.method:
755 alias: example_alias
756 http.response.body.size:
757 alias: example_alias
758 http.response.status_code:
759 alias: example_alias
760 http.route:
761 alias: example_alias
762 network.local.address:
763 alias: example_alias
764 network.local.port:
765 alias: example_alias
766 network.peer.address:
767 alias: example_alias
768 network.peer.port:
769 alias: example_alias
770 network.protocol.name:
771 alias: example_alias
772 network.protocol.version:
773 alias: example_alias
774 network.transport:
775 alias: example_alias
776 network.type:
777 alias: example_alias
778 server.address:
779 alias: example_alias
780 server.port:
781 alias: example_alias
782 trace_id:
783 alias: example_alias
784 url.path:
785 alias: example_alias
786 url.query:
787 alias: example_alias
788 url.scheme:
789 alias: example_alias
790 user_agent.original:
791 alias: example_alias
792 http.server.request.duration:
793 attributes:
794 baggage: null
795 dd.trace_id:
796 alias: example_alias
797 error.type:
798 alias: example_alias
799 http.request.body.size:
800 alias: example_alias
801 http.request.method:
802 alias: example_alias
803 http.response.body.size:
804 alias: example_alias
805 http.response.status_code:
806 alias: example_alias
807 http.route:
808 alias: example_alias
809 network.local.address:
810 alias: example_alias
811 network.local.port:
812 alias: example_alias
813 network.peer.address:
814 alias: example_alias
815 network.peer.port:
816 alias: example_alias
817 network.protocol.name:
818 alias: example_alias
819 network.protocol.version:
820 alias: example_alias
821 network.transport:
822 alias: example_alias
823 network.type:
824 alias: example_alias
825 server.address:
826 alias: example_alias
827 server.port:
828 alias: example_alias
829 trace_id:
830 alias: example_alias
831 url.path:
832 alias: example_alias
833 url.query:
834 alias: example_alias
835 url.scheme:
836 alias: example_alias
837 user_agent.original:
838 alias: example_alias
839 http.server.response.body.size:
840 attributes:
841 baggage: null
842 dd.trace_id:
843 alias: example_alias
844 error.type:
845 alias: example_alias
846 http.request.body.size:
847 alias: example_alias
848 http.request.method:
849 alias: example_alias
850 http.response.body.size:
851 alias: example_alias
852 http.response.status_code:
853 alias: example_alias
854 http.route:
855 alias: example_alias
856 network.local.address:
857 alias: example_alias
858 network.local.port:
859 alias: example_alias
860 network.peer.address:
861 alias: example_alias
862 network.peer.port:
863 alias: example_alias
864 network.protocol.name:
865 alias: example_alias
866 network.protocol.version:
867 alias: example_alias
868 network.transport:
869 alias: example_alias
870 network.type:
871 alias: example_alias
872 server.address:
873 alias: example_alias
874 server.port:
875 alias: example_alias
876 trace_id:
877 alias: example_alias
878 url.path:
879 alias: example_alias
880 url.query:
881 alias: example_alias
882 url.scheme:
883 alias: example_alias
884 user_agent.original:
885 alias: example_alias
886 subgraph:
887 http.client.request.body.size:
888 attributes:
889 http.request.resend_count:
890 alias: example_alias
891 subgraph.graphql.document:
892 alias: example_alias
893 subgraph.graphql.operation.name:
894 alias: example_alias
895 subgraph.graphql.operation.type:
896 alias: example_alias
897 subgraph.name:
898 alias: example_alias
899 http.client.request.duration:
900 attributes:
901 http.request.resend_count:
902 alias: example_alias
903 subgraph.graphql.document:
904 alias: example_alias
905 subgraph.graphql.operation.name:
906 alias: example_alias
907 subgraph.graphql.operation.type:
908 alias: example_alias
909 subgraph.name:
910 alias: example_alias
911 http.client.response.body.size:
912 attributes:
913 http.request.resend_count:
914 alias: example_alias
915 subgraph.graphql.document:
916 alias: example_alias
917 subgraph.graphql.operation.name:
918 alias: example_alias
919 subgraph.graphql.operation.type:
920 alias: example_alias
921 subgraph.name:
922 alias: example_alias
923 supergraph:
924 cost.actual:
925 attributes:
926 cost.actual:
927 alias: example_alias
928 cost.delta:
929 alias: example_alias
930 cost.estimated:
931 alias: example_alias
932 cost.result:
933 alias: example_alias
934 graphql.document:
935 alias: example_alias
936 graphql.operation.name:
937 alias: example_alias
938 graphql.operation.type:
939 alias: example_alias
940 cost.delta:
941 attributes:
942 cost.actual:
943 alias: example_alias
944 cost.delta:
945 alias: example_alias
946 cost.estimated:
947 alias: example_alias
948 cost.result:
949 alias: example_alias
950 graphql.document:
951 alias: example_alias
952 graphql.operation.name:
953 alias: example_alias
954 graphql.operation.type:
955 alias: example_alias
956 cost.estimated:
957 attributes:
958 cost.actual:
959 alias: example_alias
960 cost.delta:
961 alias: example_alias
962 cost.estimated:
963 alias: example_alias
964 cost.result:
965 alias: example_alias
966 graphql.document:
967 alias: example_alias
968 graphql.operation.name:
969 alias: example_alias
970 graphql.operation.type:
971 alias: example_alias
972 spans:
973 connector:
974 attributes:
975 connector.http.method:
976 alias: example_alias
977 connector.source.name:
978 alias: example_alias
979 connector.url.template:
980 alias: example_alias
981 subgraph.name:
982 alias: example_alias
983 default_attribute_requirement_level: none
984 mode: deprecated
985 router:
986 attributes:
987 baggage: null
988 dd.trace_id:
989 alias: example_alias
990 error.type:
991 alias: example_alias
992 http.request.body.size:
993 alias: example_alias
994 http.request.method:
995 alias: example_alias
996 http.response.body.size:
997 alias: example_alias
998 http.response.status_code:
999 alias: example_alias
1000 http.route:
1001 alias: example_alias
1002 network.local.address:
1003 alias: example_alias
1004 network.local.port:
1005 alias: example_alias
1006 network.peer.address:
1007 alias: example_alias
1008 network.peer.port:
1009 alias: example_alias
1010 network.protocol.name:
1011 alias: example_alias
1012 network.protocol.version:
1013 alias: example_alias
1014 network.transport:
1015 alias: example_alias
1016 network.type:
1017 alias: example_alias
1018 server.address:
1019 alias: example_alias
1020 server.port:
1021 alias: example_alias
1022 trace_id:
1023 alias: example_alias
1024 url.path:
1025 alias: example_alias
1026 url.query:
1027 alias: example_alias
1028 url.scheme:
1029 alias: example_alias
1030 user_agent.original:
1031 alias: example_alias
1032 subgraph:
1033 attributes:
1034 http.request.resend_count:
1035 alias: example_alias
1036 subgraph.graphql.document:
1037 alias: example_alias
1038 subgraph.graphql.operation.name:
1039 alias: example_alias
1040 subgraph.graphql.operation.type:
1041 alias: example_alias
1042 subgraph.name:
1043 alias: example_alias
1044 supergraph:
1045 attributes:
1046 cost.actual:
1047 alias: example_alias
1048 cost.delta:
1049 alias: example_alias
1050 cost.estimated:
1051 alias: example_alias
1052 cost.result:
1053 alias: example_alias
1054 graphql.document:
1055 alias: example_alias
1056 graphql.operation.name:
1057 alias: example_alias
1058 graphql.operation.type:
1059 alias: example_alias
1060tls:
1061 connector:
1062 all:
1063 certificate_authorities: null
1064 client_authentication:
1065 certificate_chain: example_certificate_chain
1066 key: example_key
1067 sources: {}
1068 subgraph:
1069 all:
1070 certificate_authorities: null
1071 client_authentication:
1072 certificate_chain: example_certificate_chain
1073 key: example_key
1074 subgraphs: {}
1075 supergraph:
1076 certificate: example_certificate
1077 certificate_chain: example_certificate_chain
1078 key: example_key
1079traffic_shaping:
1080 all:
1081 compression: gzip
1082 deduplicate_query: false
1083 dns_resolution_strategy: ipv4_only
1084 experimental_http2: enable
1085 global_rate_limit:
1086 capacity: 1
1087 interval: 30s
1088 timeout: null
1089 connector:
1090 all:
1091 compression: gzip
1092 dns_resolution_strategy: ipv4_only
1093 experimental_http2: enable
1094 global_rate_limit:
1095 capacity: 1
1096 interval: 30s
1097 timeout: null
1098 sources: {}
1099 deduplicate_variables: null
1100 router:
1101 concurrency_limit: 0
1102 global_rate_limit:
1103 capacity: 1
1104 interval: 30s
1105 timeout: null
1106 subgraphs: {}Properties
apq
YAML
apq
1apq:
2 enabled: true
3 router:
4 cache:
5 in_memory:
6 limit: 1
7 redis:
8 namespace: example_namespace
9 password: example_password
10 pool_size: 1
11 required_to_start: false
12 reset_ttl: true
13 timeout: null
14 tls:
15 certificate_authorities: null
16 client_authentication:
17 certificate_chain: example_certificate_chain
18 key: example_key
19 ttl: null
20 urls:
21 - http://example.com/urls_item
22 username: example_username
23 subgraph:
24 all:
25 enabled: false
26 subgraphs: {}Learn more in Automatic Persisted Queries.
authentication
YAML
authentication
1authentication:
2 connector:
3 sources: {}
4 router:
5 jwt:
6 header_name: authorization
7 header_value_prefix: Bearer
8 ignore_other_prefixes: false
9 jwks:
10 - algorithms: null
11 allow_missing_exp: false
12 headers:
13 - name: example_name
14 value: example_value
15 issuer: example_issuer
16 poll_interval:
17 nanos: 0
18 secs: 60
19 url: http://service.example.com/url
20 on_error: Continue
21 sources:
22 - name: authorization
23 type: header
24 value_prefix: Bearer
25 subgraph:
26 all:
27 aws_sig_v4:
28 hardcoded:
29 access_key_id: example_access_key_id
30 assume_role:
31 external_id: example_external_id
32 role_arn: example_role_arn
33 session_name: example_session_name
34 region: example_region
35 secret_access_key: example_secret_access_key
36 service_name: example_service_name
37 subgraphs: {}To learn about JWT authentication, go to JWT authentication in the GraphOS Router.
To learn about subgraph authentication with AWS SigV4, go to a subgraph authentication configuration example.
authorization
YAML
authorization
1authorization:
2 directives:
3 dry_run: false
4 enabled: true
5 errors:
6 log: true
7 response: errors
8 reject_unauthorized: false
9 require_authentication: falseTo configure authorization directives, see Authorization directives.
To configure the authorization plugin, see Configuration options.
batching
YAML
batching
1batching:
2 enabled: false
3 maximum_size: null
4 mode: batch_http_link
5 subgraph:
6 all:
7 enabled: false
8 subgraphs: {}Learn more in query batching.
connectors
YAML
connectors
1connectors:
2 debug_extensions: false
3 expose_sources_in_context: false
4 max_requests_per_operation_per_source: null
5 sources: {}
6 subgraphs: {}Learn more in Working with router for Apollo Connectors.
coprocessor
YAML
coprocessor
1coprocessor:
2 client:
3 dns_resolution_strategy: ipv4_only
4 experimental_http2: enable
5 connector:
6 all:
7 request:
8 body: false
9 condition:
10 eq:
11 - false
12 - false
13 context: false
14 headers: false
15 method: false
16 service_name: false
17 uri: false
18 response:
19 body: false
20 condition:
21 eq:
22 - false
23 - false
24 context: false
25 headers: false
26 service_name: false
27 status_code: false
28 execution:
29 request:
30 body: false
31 context: false
32 headers: false
33 method: false
34 query_plan: false
35 sdl: false
36 response:
37 body: false
38 context: false
39 headers: false
40 sdl: false
41 status_code: false
42 router:
43 request:
44 body: false
45 condition:
46 eq:
47 - false
48 - false
49 context: false
50 headers: false
51 method: false
52 path: false
53 sdl: false
54 response:
55 body: false
56 condition:
57 eq:
58 - false
59 - false
60 context: false
61 headers: false
62 sdl: false
63 status_code: false
64 subgraph:
65 all:
66 request:
67 body: false
68 condition:
69 eq:
70 - false
71 - false
72 context: false
73 headers: false
74 method: false
75 service_name: false
76 subgraph_request_id: false
77 uri: false
78 response:
79 body: false
80 condition:
81 eq:
82 - false
83 - false
84 context: false
85 headers: false
86 service_name: false
87 status_code: false
88 subgraph_request_id: false
89 supergraph:
90 request:
91 body: false
92 condition:
93 eq:
94 - false
95 - false
96 context: false
97 headers: false
98 method: false
99 sdl: false
100 response:
101 body: false
102 condition:
103 eq:
104 - false
105 - false
106 context: false
107 headers: false
108 sdl: false
109 status_code: false
110 timeout:
111 nanos: 0
112 secs: 1
113 url: http://service.example.com/urlLearn more in External coprocessing in the GraphOS Router.
cors
YAML
cors
1cors:
2 allow_any_origin: false
3 allow_credentials: false
4 allow_headers: []
5 expose_headers: null
6 max_age: null
7 methods:
8 - GET
9 - POST
10 - OPTIONS
11 policies:
12 - origins:
13 - https://studio.apollographql.com
14 - https://myapp.com
15 allow_credentials: false
16 allow_headers: []
17 expose_headers: []
18 private_network_access:
19 access_id:
20 # methods not specified - uses global defaults [GET, POST, OPTIONS]
21 - origins:
22 - https://restricted.com
23 methods: [] # Explicitly no methods allowed
24 - origins:
25 - https://api.example.com
26 match_origins:
27 - "^https://.*\\.example\\.com$"
28 allow_headers:
29 - content-type
30 - authorization
31 methods:
32 - GET
33 - POST
34 private_network_access:
35 access_id: "01:23:45:67:89:0A"
36 access_name: "mega-corp device"
37 # Specific methods override global defaultsBy default, the router only allows GraphOS Studio to initiate browser connections to it. If your supergraph serves data to other browser-based applications, you need to update its Cross-Origin Resource Sharing (CORS) configuration.
Learn more in CORS.
csrf
YAML
csrf
1csrf:
2 required_headers:
3 - x-apollo-operation-name
4 - apollo-require-preflight
5 unsafe_disabled: falseLearn more in CSRF prevention in the router.
demand_control
YAML
demand_control
1demand_control:
2 enabled: false
3 mode: measure
4 strategy:
5 static_estimated:
6 list_size: 0
7 max: 0.0
8 actual_cost_mode: by_subgraph
9 subgraph:
10 all:
11 list_size: 0
12 max: 0.0
13 subgraphs: {}With demand control, the router analyzes the cost of operations and rejects requests with operations that exceed customizable cost limits.
Learn more in Demand Control
experimental_chaos
YAML
experimental_chaos
1experimental_chaos:
2 force_reload: nullexperimental_hoist_orphan_errors
YAML
experimental_hoist_orphan_errors
1experimental_hoist_orphan_errors:
2 all:
3 enabled: false
4 subgraphs: {}When the entity-resolution process for a subgraph returns errors that apply to multiple entities in a list, the router defaults to propagating each error to every matching entity path. That results in a multiplicative increase in the size of the returned error array.
The experimental_hoist_orphan_errors option changes that behavior on a per-subgraph basis. When enabled, the router attaches each orphaned subgraph error to a single parent path instead of duplicating the error across every entity path, which can significantly reduce the number of errors in the response.
caution
The
experimental_hoist_orphan_errors option isn't compliant with the GraphQL spec. The option changes how errors are associated with paths in the response, compared to the behavior described in the GraphQL specification. Only use the feature for your subgraphs when the reduction in error volume is more desirable than strict compliance.To target a specific subgraph:
YAML
router.yaml
1experimental_hoist_orphan_errors:
2 subgraphs:
3 my_subgraph:
4 enabled: trueTo target all subgraphs:
YAML
router.yaml
1experimental_hoist_orphan_errors:
2 all:
3 enabled: trueTo target all subgraphs except one:
YAML
router.yaml
1experimental_hoist_orphan_errors:
2 all:
3 enabled: true
4 subgraphs:
5 spec_compliant_one:
6 enabled: falsePer-subgraph settings override all.
note
Although the
experimental_hoist_orphan_errors option can reduce the number of propagated errors, the option doesn't limit the total number of errors. If a subgraph returns a large number of errors, the router still processes all of them. For subgraphs that are likely to produce an unbounded number of errors, consider additional mitigation strategies at the subgraph level.experimental_type_conditioned_fetching
YAML
experimental_type_conditioned_fetching
1experimental_type_conditioned_fetching: falsefleet_detector
YAML
fleet_detector
1fleet_detector: {}forbid_mutations
YAML
forbid_mutations
1forbid_mutations: falseheaders
YAML
headers
1headers:
2 all:
3 request:
4 - insert:
5 name: example_name
6 value: example_value
7 subgraphs: {}Learn more in Sending HTTP headers to subgraphs.
health_check
YAML
health_check
1health_check:
2 enabled: true
3 listen: example_listen
4 path: /health
5 readiness:
6 allowed: 100
7 interval:
8 sampling: 0s
9 unready: nullLearn more in Health Checks.
homepage
YAML
homepage
1homepage:
2 enabled: true
3 graph_ref: nullThe router can serve a landing page to browsers that visit its endpoint path (supergraph.path):
A basic landing page that displays an example query
curlcommand (default)YAMLrouter.yaml1# This is the default behavior. You don't need to include this config. 2homepage: 3 enabled: trueNo landing page
YAMLrouter.yaml1homepage: 2 enabled: falseSending users to Apollo Explorer
YAMLrouter.yaml1homepage: 2 graph_ref: my-org-graph@productionWhen you specify a
graph_ref, the router's landing page includes an option for users to redirect to Apollo Explorer. Users can check a box that will remember their preference and automatically redirect them to Explorer on subsequent visits.noteThegraph_refvalue should match the formatorganization-name@variant-name, which is the same format used with theAPOLLO_GRAPH_REFenvironment variable. Note that the router does not automatically use the value from theAPOLLO_GRAPH_REFenvironment variable for this setting - you must explicitly setgraph_refin your YAML configuration even if you're already using the environment variable.
include_subgraph_errors
YAML
include_subgraph_errors
1include_subgraph_errors:
2 all: false
3 subgraphs: {}license_enforcement
YAML
license_enforcement
1license_enforcement: {}limits
YAML
limits
1limits:
2 connector:
3 all:
4 http_max_response_size: null
5 sources: {}
6 router:
7 http1_max_request_buf_size: null
8 http1_max_request_headers: null
9 http2_max_headers_list_bytes: null
10 http_max_request_bytes: 2000000
11 introspection_max_depth: true
12 max_aliases: null
13 max_depth: null
14 max_height: null
15 max_root_fields: null
16 max_recursive_selections: 10000000
17 parser_max_recursion: 500
18 parser_max_tokens: 15000
19 warn_only: false
20 subgraph:
21 all:
22 http_max_response_size: null
23 subgraphs: {}Learn more in Request Limits.
override_subgraph_url
YAML
override_subgraph_url
1override_subgraph_url: {}By default, the router obtains the routing URL for each of your subgraphs from the composed supergraph schema you provide it. In most cases, no additional configuration is required. The URL can use HTTP and HTTPS for network access to subgraph, or have the following shape for Unix sockets usage: unix:///path/to/subgraph.sock
note
Unix socket paths should be absolute (starting with
/). The URL format is unix:// followed by the absolute path, resulting in three slashes: unix:///var/run/subgraph.sock.Because .sock is not required as a file extension, the router cannot determine if a path is appended to the base URL. Specify a custom HTTP path using the path query parameter:
YAML
1override_subgraph_url:
2 my_subgraph: "unix:///tmp/subgraph.sock?path=/graphql/v1"This configuration also applies to subgraph URLs defined in your supergraph schema (using the url argument of the @join__graph directive).
However, if you do need to override a particular subgraph's routing URL (for example, to handle changing network topography), you can do so with the override_subgraph_url option:
YAML
1override_subgraph_url:
2 organizations: http://localhost:8080
3 accounts: "${env.ACCOUNTS_SUBGRAPH_HOST_URL}"In this example, the organizations subgraph URL is overridden to point to http://localhost:8080, and the accounts subgraph URL is overridden to point to a new URL using variable expansion. The URL specified in the supergraph schema is ignored.
Any subgraphs that are omitted from override_subgraph_url continue to use the routing URL specified in the supergraph schema.
If you need to override the subgraph URL at runtime on a per-request basis, you can use request customizations in the SubgraphService layer.
persisted_queries
YAML
persisted_queries
1persisted_queries:
2 enabled: false
3 experimental_prewarm_query_plan_cache:
4 on_reload: true
5 on_startup: false
6 hot_reload: false
7 local_manifests: null
8 log_unknown: false
9 safelist:
10 enabled: false
11 require_id: falseYou can enhance your graph's security with GraphOS Router by maintaining a persisted query list (PQL), an operation safelist made by your first-party apps. As opposed to automatic persisted queries (APQ) where operations are automatically cached, operations must be preregistered to the PQL. Once configured, the router checks incoming requests against the PQL.
Learn more about safelisting with persisted queries.
plugins
YAML
plugins
1plugins: unknown_type_pluginsYou can customize the router's behavior with plugins. Each plugin can have its own section in the configuration file with arbitrary values:
YAML
example-plugin-router.yaml
1plugins:
2 example.plugin:
3 var1: "hello"
4 var2: 1Learn more in Native Plugins for router.
preview_entity_cache
YAML
preview_entity_cache
1preview_entity_cache:
2 enabled: false
3 expose_keys_in_context: false
4 invalidation:
5 concurrent_requests: 10
6 listen: example_listen
7 path: example_path
8 scan_count: 1000
9 metrics:
10 enabled: false
11 separate_per_type: false
12 ttl: 30s
13 subgraph:
14 all:
15 enabled: true
16 invalidation:
17 enabled: false
18 shared_key: ''
19 private_id: null
20 redis:
21 namespace: example_namespace
22 password: example_password
23 pool_size: 1
24 required_to_start: false
25 reset_ttl: true
26 timeout: null
27 tls:
28 certificate_authorities: null
29 client_authentication:
30 certificate_chain: example_certificate_chain
31 key: example_key
32 ttl: null
33 urls:
34 - http://example.com/urls_item
35 username: example_username
36 ttl: 30s
37 subgraphs: {}When using Redis as the cache backend, the router emits additional Redis-specific metrics to help monitor cache performance:
Connection metrics: Track Redis connection establishment and health
Command metrics: Monitor Redis command execution, queue length, and redelivery counts
Performance metrics: Measure average latency, network latency, and request/response sizes
Operational metrics: Help identify connection issues, network problems, or performance bottlenecks
These metrics use the kind attribute to distinguish between different Redis cache uses (e.g., entity). For the complete list of Redis metrics and their descriptions, see the Redis Cache metrics documentation.
note
For new projects, Apollo recommends using Response Caching instead.
Learn more in Entity Caching.
response_cache
YAML
response_cache.router.yaml
1response_cache:
2 enabled: false
3 debug: false
4 include_cache_control_header_on_router_response: true # set to false to suppress Cache-Control header on client responses
5 private_queries_buffer_size: 2048
6 invalidation:
7 listen: 127.0.0.1:4000
8 path: /invalidation
9 subgraph:
10 all:
11 enabled: true
12 ttl: 30s
13 private_id: null
14 redis:
15 urls:
16 - redis://127.0.0.1:6379
17 username: example_username
18 password: example_password
19 fetch_timeout: 150ms
20 insert_timeout: 500ms
21 invalidate_timeout: 1s
22 maintenance_timeout: 500ms
23 namespace: example_namespace
24 tls:
25 certificate_authorities: null
26 client_authentication:
27 certificate_chain: example_certificate_chain
28 key: example_key
29 required_to_start: false
30 pool_size: 5
31 metrics_interval: 1s
32 invalidation:
33 enabled: false
34 shared_key: ''
35 subgraphs: {}When using Redis as the cache backend, the router emits additional Redis-specific metrics to help monitor cache performance:
Connection metrics: Track Redis connection establishment and health
Command metrics: Monitor Redis command execution, queue length, and redelivery counts
Performance metrics: Measure average latency, network latency, and request/response sizes
Operational metrics: Help identify connection issues, network problems, or performance bottlenecks
These metrics use the kind attribute to distinguish between different Redis cache uses (e.g., response). For the complete list of Redis metrics and their descriptions, see the Redis Cache metrics documentation.
Learn more in Response Caching.
preview_file_uploads
YAML
preview_file_uploads
1preview_file_uploads:
2 enabled: false
3 protocols:
4 multipart:
5 enabled: true
6 limits:
7 max_file_size: example_max_file_size
8 max_files: 0
9 operation_body_timeout: 30s
10 mode: streamLearn more in File Uploads.
reload
YAML
router.yaml
1reload:
2 # Maximum retry attempts after a failed reload.
3 # 0 disables retries. null allows unlimited retries. Default: 5
4 max_retries: 5
5
6 # Base delay between retries. Up to 25% jitter is added automatically
7 # Default: 10s
8 retry_delay: 10sLearn more about configuring reload retries.
rhai
YAML
rhai
1rhai:
2 main: example_main
3 scripts: example_scripts
4 # intern_strings: falseLearn more in Rhai customization for router.
sandbox
YAML
sandbox
1sandbox:
2 enabled: falseApollo Sandbox is a GraphQL development environment. It runs a graph via introspection queries on the router's supergrpah schema, and it provides an IDE for making queries to the graph.
Running Sandbox in router requires configuring sandbox.enabled, supergraph.instrospection, and homepage.enabled:
YAML
router.yaml
1sandbox:
2 enabled: true
3
4# Sandbox uses introspection to obtain your router's schema.
5supergraph:
6 introspection: true
7
8# Sandbox requires the default landing page to be disabled.
9homepage:
10 enabled: falsecaution
Do not enable Sandbox in production. Sandbox requires enabling introspection, which is strongly discouraged in production environments.
Learn more in Apollo Sandbox.
server
YAML
server
1server:
2 http:
3 header_read_timeout: 30s
4 tls_handshake_timeout: 30sHeader Read Timeout
The header read timeout is the amount of time the Router will wait to receive the complete request headers from a client before timing out. It applies both when the connection is fully idle and when a request has been started but sending the headers has not been completed.
By default, the header read timeout is set to 10 seconds. A longer timeout can be configured using the server.http.header_read_timeout configuration option.
TLS handshake timeout
The TLS handshake timeout determines how long the router waits to complete a TLS handshake with a client.
The default timeout is ten seconds. You can configure the server.http.tls_handshake_timeout option to change this duration.
subscription
YAML
subscription
1subscription:
2 enable_deduplication: true
3 enabled: true
4 max_lifetime: null
5 max_opened_subscriptions: null
6 mode:
7 callback:
8 heartbeat_interval: disabled
9 listen: example_listen
10 path: example_path
11 public_url: http://service.example.com/public_url
12 subgraphs: []
13 passthrough:
14 all:
15 heartbeat_interval: disabled
16 path: null
17 protocol: graphql_ws
18 subgraphs: {}
19 queue_capacity: nullLearn more in Subscriptions.
supergraph
YAML
supergraph
1supergraph:
2 defer_support: true
3 early_cancel: false
4 experimental_log_on_broken_pipe: false
5 generate_query_fragments: true
6 introspection: false
7 listen: example_listen
8 path: /
9 redact_query_validation_errors: false
10 query_planning:
11 cache:
12 in_memory:
13 limit: 1
14 redis:
15 namespace: example_namespace
16 password: example_password
17 pool_size: 1
18 required_to_start: false
19 reset_ttl: true
20 timeout: null
21 tls:
22 certificate_authorities: null
23 client_authentication:
24 certificate_chain: example_certificate_chain
25 key: example_key
26 ttl:
27 nanos: 0
28 secs: 2592000
29 urls:
30 - http://example.com/urls_item
31 username: example_username
32 experimental_paths_limit: null
33 experimental_plans_limit: null
34 experimental_reuse_query_plans: false
35 warmed_up_queries: null
36 strict_variable_validation: enforceSupergraph listen address
As the gateway and single endpoint to your supergraph, an Apollo Router has a socket address and port that it listens for client requests. This listen address is configurable in YAML as supergraph.listen.
By default, the router starts an HTTP server that listens on 127.0.0.1:4000. You can specify a different address by setting supergraph.listen for IPv4, IPv6, or Unix sockets.
IPv4
YAML
router.yaml
1supergraph:
2 # The socket address and port to listen on (default: 127.0.0.1:400)
3 listen: 127.0.0.1:4000IPv6
YAML
router.yaml
1supergraph:
2 # The socket address and port to listen on. (default: [::1]:4000)
3 # Note that this must be quoted to avoid interpretation as an array in YAML.
4 listen: "[::1]:4000"Unix socket
YAML
router_unix.yaml
1supergraph:
2 # Absolute path to a Unix socket
3 listen: /tmp/router.socknote
Listening on a Unix socket is not supported on Windows.
Supergraph endpoint path
The path of the HTTP endpoint of the supergraph that the router runs is configured by supergraph.path.
By default, the router starts an HTTP server that exposes a POST/GET endpoint at path /.
YAML
router.yaml
1supergraph:
2 # The path for GraphQL execution
3 # (Defaults to /)
4 path: /graphqlThe path must start with /.
A path can contain parameters and wildcards:
/{parameter}matches a single segment. For example:/abc/{my_param}/defmatches/abc/1/defand/abc/whatever/def, but it doesn't match/abc/1/2/defor/abc/def
/{*parameter}matches all segments in the rest of a path. For example:/abc/{*wildcard}matches/abc/1/defand/abc/w/h/a/t/e/v/e/r, but it doesn't match/abc/or/not_abc_at_all
note
- Both parameters and wildcards require a name, even though you can’t use those names anywhere.
- The router doesn't support wildcards in the middle of a path (e.g.,
/{*wild}/graphql). Instead, use a path parameter (e.g.,/{parameter}/graphql).
The router normalizes trailing slashes automatically. For example, if you configure the path as /graphql, the router accepts requests to both /graphql and /graphql/. This applies regardless of whether your configured path includes a trailing slash.
Introspection
In GraphQL, introspection queries are used during development to learn about a GraphQL API's schema. The router can resolve introspection queries, based on the configuration of supergraph.introspection.
By default, the router doesn't resolve introspection queries.
To enable introspection queries during development, set the supergraph.introspection flag:
YAML
router.yaml
1# Do not enable introspection in production!
2supergraph:
3 introspection: trueIntrospection recursion limit
The schema-introspection schema is recursive: a client can query the fields of the types of some other fields, and so on arbitrarily deep. This can produce responses that grow much faster than the size of the request.
To prevent this, the router is configured by default to not execute introspection queries that nest list fields that are too deep, instead returning an error. The criteria matches MaxIntrospectionDepthRule in graphql-js, and it may change in future versions.
In case the router rejects legitimate queries, you can disable the limit by setting the limits.introspection_max_depth flag:
YAML
router.yaml
1# Do not enable introspection in production!
2supergraph:
3 introspection: true
4limits:
5 router:
6 introspection_max_depth: falseRedacting query validation errors
Query validation errors might reveal information about your schema structure, such as field names, types, and required arguments. Although this is not typically a significant security concern (especially with persisted queries), you can redact these error details in production environments.
Apollo Router returns detailed validation error messages by default. To redact validation errors and return a generic error message, set the supergraph.redact_query_validation_errors flag:
YAML
router.yaml
1supergraph:
2 redact_query_validation_errors: trueWhen you enable this setting, Apollo Router replaces query validation errors with a single generic error:
JSON
1{
2 "message": "invalid query",
3 "extensions": {
4 "code": "UNKNOWN_ERROR"
5 }
6}note
Enabling this option will make debugging more difficult, as clients won't receive specific information about what's wrong with their queries. Consider enabling it only in production environments where schema details should remain private.
Early cancel
Up until Apollo Router Core v1.43.1, when the client closed the connection without waiting for the response, the entire request was cancelled and did not go through the entire pipeline. Since this causes issues with request monitoring, the router introduced a new behavior in 1.43.1. Now, the entire pipeline is executed if the request is detected as cancelled, but subgraph requests are not actually done. The response will be reported with the 499 status code, but not actually sent to the client.
To go back to the previous behavior of immediately cancelling the request, the following configuration can be used for supergraph.early_cancel:
YAML
1supergraph:
2 early_cancel: trueAdditionally, since v1.43.1, the router can show a log when it detects that the client canceled the request. This log can be activated with:
YAML
router.yaml
1supergraph:
2 experimental_log_on_broken_pipe: trueConnection shutdown timeout
When the Router schema or configuration updates all connections must be closed for resources to be freed.
To ensure that long-lived connections do not hang on to resources, a maximum graceful shutdown timeout can be configured with supergraph.connection_shutdown_timeout:
YAML
router.yaml
1supergraph:
2 connection_shutdown_timeout: 60sThe default value is 60 seconds.
Note that if early_cancel is false (default), then requests in progress will still hold onto pipeline resources.
In that case, traffic shaping request timeouts should be used to prevent long-running requests:
YAML
router.yaml
1traffic_shaping:
2 router:
3 timeout: 60sAutomatic fragment generation
By default, the router compresses subgraph requests by generating fragment definitions based on the shape of the subgraph operation. In many cases this significantly reduces the size of the query sent to subgraphs.
Opt out of this behavior by specifying supergraph.generate_query_fragments:
YAML
1supergraph:
2 generate_query_fragments: falseVariable validation modes
By default, the router validates input variables strictly. It validates each input object value against its type definition, and any unknown fields result in a request error.
YAML
1supergraph:
2 strict_variable_validation: enforceIf your implementation requires unknown fields on a defined type, you can opt out of stricter validation by specifying strict_variable_validation: measure.
In this case, the router will not error when encountering unknown fields, but will log the field for reference.
telemetry
YAML
telemetry
1telemetry:
2 apollo:
3 tracing:
4 batch_processor:
5 max_export_timeout: 30s
6 scheduled_delay: 5s
7 max_export_batch_size: 512
8 max_concurrent_exports: 1
9 max_queue_size: 2048
10 metrics:
11 otlp:
12 batch_processor:
13 scheduled_delay: 5s
14 max_export_timeout: 30s
15 usage_reports:
16 batch_processor:
17 max_export_timeout: 30s
18 scheduled_delay: 5s
19 max_queue_size: 2048
20 buffer_size: 10000
21 client_name_header: apollographql-client-name
22 client_version_header: apollographql-client-version
23 endpoint: https://usage-reporting.api.apollographql.com/api/ingress/traces
24 errors:
25 preview_extended_error_metrics: disabled
26 subgraph:
27 all:
28 redact: true
29 redaction_policy: strict
30 send: true
31 subgraphs: {}
32 experimental_local_field_metrics: false
33 experimental_otlp_endpoint: https://usage-reporting.api.apollographql.com/
34 experimental_otlp_tracing_protocol: grpc
35 field_level_instrumentation_sampler: 0.0
36 metrics_reference_mode: extended
37 otlp_tracing_sampler: 0.0
38 send_headers:
39 only:
40 - example_only_item
41 send_variable_values:
42 only:
43 - example_only_item
44 signature_normalization_algorithm: enhanced
45 exporters:
46 logging:
47 common:
48 resource: {}
49 service_name: null
50 service_namespace: null
51 stdout:
52 enabled: true
53 format:
54 json:
55 display_current_span: false
56 display_filename: false
57 display_level: true
58 display_line_number: false
59 display_resource: true
60 display_span_id: true
61 display_span_list: true
62 display_target: true
63 display_thread_id: false
64 display_thread_name: false
65 display_timestamp: true
66 display_trace_id: hexadecimal
67 span_attributes: []
68 expand_json_string_values: false
69 rate_limit:
70 capacity: 1
71 enabled: false
72 interval:
73 nanos: 0
74 secs: 1
75 tty_format:
76 json:
77 display_current_span: false
78 display_filename: false
79 display_level: true
80 display_line_number: false
81 display_resource: true
82 display_span_id: true
83 display_span_list: true
84 display_target: true
85 display_thread_id: false
86 display_thread_name: false
87 display_timestamp: true
88 display_trace_id: hexadecimal
89 span_attributes: []
90 expand_json_string_values: false
91 metrics:
92 common:
93 buckets:
94 - 0.001
95 - 0.005
96 - 0.015
97 - 0.05
98 - 0.1
99 - 0.2
100 - 0.3
101 - 0.4
102 - 0.5
103 - 1.0
104 - 5.0
105 - 10.0
106 resource: {}
107 service_name: null
108 service_namespace: null
109 views:
110 - aggregation:
111 histogram:
112 buckets:
113 - 0.0
114 allowed_attribute_keys:
115 - example_allowed_attribute_keys_item
116 description: example_description
117 name: example_name
118 rename: example_rename
119 unit: example_unit
120 otlp:
121 batch_processor:
122 max_concurrent_exports: 1
123 max_export_batch_size: 512
124 max_export_timeout:
125 nanos: 0
126 secs: 30
127 max_queue_size: 2048
128 scheduled_delay:
129 nanos: 0
130 secs: 5
131 enabled: false
132 endpoint: example_endpoint
133 grpc:
134 ca: null
135 cert: null
136 domain_name: null
137 key: null
138 metadata: {}
139 http:
140 headers: {}
141 protocol: grpc
142 temporality: cumulative
143 prometheus:
144 enabled: false
145 listen: example_listen
146 path: /metrics
147 tracing:
148 common:
149 max_attributes_per_event: 128
150 max_attributes_per_link: 128
151 max_attributes_per_span: 128
152 max_events_per_span: 128
153 max_links_per_span: 128
154 parent_based_sampler: true
155 preview_datadog_agent_sampling: null
156 resource: {}
157 sampler: 0.0
158 service_name: null
159 service_namespace: null
160 datadog:
161 batch_processor:
162 max_concurrent_exports: 1
163 max_export_batch_size: 512
164 max_export_timeout:
165 nanos: 0
166 secs: 30
167 max_queue_size: 2048
168 scheduled_delay:
169 nanos: 0
170 secs: 5
171 enable_span_mapping: true
172 enabled: false
173 endpoint: example_endpoint
174 fixed_span_names: true
175 resource_mapping: {}
176 span_metrics:
177 connect: true
178 connect_request: true
179 execution: true
180 http_request: true
181 parse_query: true
182 query_planning: true
183 request: true
184 router: true
185 subgraph: true
186 subgraph_request: true
187 supergraph: true
188 experimental_response_trace_id:
189 enabled: false
190 format: hexadecimal
191 header_name: example_header_name
192 otlp:
193 batch_processor:
194 max_concurrent_exports: 1
195 max_export_batch_size: 512
196 max_export_timeout:
197 nanos: 0
198 secs: 30
199 max_queue_size: 2048
200 scheduled_delay:
201 nanos: 0
202 secs: 5
203 enabled: false
204 endpoint: example_endpoint
205 grpc:
206 ca: null
207 cert: null
208 domain_name: null
209 key: null
210 metadata: {}
211 http:
212 headers: {}
213 protocol: grpc
214 temporality: cumulative
215 propagation:
216 aws_xray: false
217 baggage: false
218 datadog: false
219 jaeger: false
220 request:
221 format: hexadecimal
222 header_name: example_header_name
223 trace_context: false
224 zipkin: false
225 zipkin:
226 batch_processor:
227 max_concurrent_exports: 1
228 max_export_batch_size: 512
229 max_export_timeout:
230 nanos: 0
231 secs: 30
232 max_queue_size: 2048
233 scheduled_delay:
234 nanos: 0
235 secs: 5
236 enabled: false
237 endpoint: example_endpoint
238 instrumentation:
239 events:
240 connector:
241 error:
242 condition:
243 eq:
244 - false
245 - false
246 level: info
247 request:
248 condition:
249 eq:
250 - false
251 - false
252 level: info
253 response:
254 condition:
255 eq:
256 - false
257 - false
258 level: info
259 router:
260 error:
261 condition:
262 eq:
263 - false
264 - false
265 level: info
266 request:
267 condition:
268 eq:
269 - false
270 - false
271 level: info
272 response:
273 condition:
274 eq:
275 - false
276 - false
277 level: info
278 subgraph:
279 error:
280 condition:
281 eq:
282 - false
283 - false
284 level: info
285 request:
286 condition:
287 eq:
288 - false
289 - false
290 level: info
291 response:
292 condition:
293 eq:
294 - false
295 - false
296 level: info
297 supergraph:
298 error:
299 condition:
300 eq:
301 - false
302 - false
303 level: info
304 request:
305 condition:
306 eq:
307 - false
308 - false
309 level: info
310 response:
311 condition:
312 eq:
313 - false
314 - false
315 level: info
316 instruments:
317 cache:
318 apollo.router.operations.entity.cache:
319 attributes:
320 graphql.type.name:
321 alias: example_alias
322 connector:
323 http.client.request.body.size:
324 attributes:
325 connector.http.method:
326 alias: example_alias
327 connector.source.name:
328 alias: example_alias
329 connector.url.template:
330 alias: example_alias
331 subgraph.name:
332 alias: example_alias
333 http.client.request.duration:
334 attributes:
335 connector.http.method:
336 alias: example_alias
337 connector.source.name:
338 alias: example_alias
339 connector.url.template:
340 alias: example_alias
341 subgraph.name:
342 alias: example_alias
343 http.client.response.body.size:
344 attributes:
345 connector.http.method:
346 alias: example_alias
347 connector.source.name:
348 alias: example_alias
349 connector.url.template:
350 alias: example_alias
351 subgraph.name:
352 alias: example_alias
353 default_requirement_level: none
354 graphql:
355 field.execution:
356 attributes:
357 graphql.field.name:
358 alias: example_alias
359 graphql.field.type:
360 alias: example_alias
361 graphql.list.length:
362 alias: example_alias
363 graphql.operation.name:
364 alias: example_alias
365 graphql.type.name:
366 alias: example_alias
367 list.length:
368 attributes:
369 graphql.field.name:
370 alias: example_alias
371 graphql.field.type:
372 alias: example_alias
373 graphql.list.length:
374 alias: example_alias
375 graphql.operation.name:
376 alias: example_alias
377 graphql.type.name:
378 alias: example_alias
379 router:
380 http.server.active_requests:
381 attributes:
382 http.request.method: false
383 server.address: false
384 server.port: false
385 url.scheme: false
386 http.server.request.body.size:
387 attributes:
388 baggage: null
389 dd.trace_id:
390 alias: example_alias
391 error.type:
392 alias: example_alias
393 http.request.body.size:
394 alias: example_alias
395 http.request.method:
396 alias: example_alias
397 http.response.body.size:
398 alias: example_alias
399 http.response.status_code:
400 alias: example_alias
401 http.route:
402 alias: example_alias
403 network.local.address:
404 alias: example_alias
405 network.local.port:
406 alias: example_alias
407 network.peer.address:
408 alias: example_alias
409 network.peer.port:
410 alias: example_alias
411 network.protocol.name:
412 alias: example_alias
413 network.protocol.version:
414 alias: example_alias
415 network.transport:
416 alias: example_alias
417 network.type:
418 alias: example_alias
419 server.address:
420 alias: example_alias
421 server.port:
422 alias: example_alias
423 trace_id:
424 alias: example_alias
425 url.path:
426 alias: example_alias
427 url.query:
428 alias: example_alias
429 url.scheme:
430 alias: example_alias
431 user_agent.original:
432 alias: example_alias
433 http.server.request.duration:
434 attributes:
435 baggage: null
436 dd.trace_id:
437 alias: example_alias
438 error.type:
439 alias: example_alias
440 http.request.body.size:
441 alias: example_alias
442 http.request.method:
443 alias: example_alias
444 http.response.body.size:
445 alias: example_alias
446 http.response.status_code:
447 alias: example_alias
448 http.route:
449 alias: example_alias
450 network.local.address:
451 alias: example_alias
452 network.local.port:
453 alias: example_alias
454 network.peer.address:
455 alias: example_alias
456 network.peer.port:
457 alias: example_alias
458 network.protocol.name:
459 alias: example_alias
460 network.protocol.version:
461 alias: example_alias
462 network.transport:
463 alias: example_alias
464 network.type:
465 alias: example_alias
466 server.address:
467 alias: example_alias
468 server.port:
469 alias: example_alias
470 trace_id:
471 alias: example_alias
472 url.path:
473 alias: example_alias
474 url.query:
475 alias: example_alias
476 url.scheme:
477 alias: example_alias
478 user_agent.original:
479 alias: example_alias
480 http.server.response.body.size:
481 attributes:
482 baggage: null
483 dd.trace_id:
484 alias: example_alias
485 error.type:
486 alias: example_alias
487 http.request.body.size:
488 alias: example_alias
489 http.request.method:
490 alias: example_alias
491 http.response.body.size:
492 alias: example_alias
493 http.response.status_code:
494 alias: example_alias
495 http.route:
496 alias: example_alias
497 network.local.address:
498 alias: example_alias
499 network.local.port:
500 alias: example_alias
501 network.peer.address:
502 alias: example_alias
503 network.peer.port:
504 alias: example_alias
505 network.protocol.name:
506 alias: example_alias
507 network.protocol.version:
508 alias: example_alias
509 network.transport:
510 alias: example_alias
511 network.type:
512 alias: example_alias
513 server.address:
514 alias: example_alias
515 server.port:
516 alias: example_alias
517 trace_id:
518 alias: example_alias
519 url.path:
520 alias: example_alias
521 url.query:
522 alias: example_alias
523 url.scheme:
524 alias: example_alias
525 user_agent.original:
526 alias: example_alias
527 subgraph:
528 http.client.request.body.size:
529 attributes:
530 http.request.resend_count:
531 alias: example_alias
532 subgraph.graphql.document:
533 alias: example_alias
534 subgraph.graphql.operation.name:
535 alias: example_alias
536 subgraph.graphql.operation.type:
537 alias: example_alias
538 subgraph.name:
539 alias: example_alias
540 http.client.request.duration:
541 attributes:
542 http.request.resend_count:
543 alias: example_alias
544 subgraph.graphql.document:
545 alias: example_alias
546 subgraph.graphql.operation.name:
547 alias: example_alias
548 subgraph.graphql.operation.type:
549 alias: example_alias
550 subgraph.name:
551 alias: example_alias
552 http.client.response.body.size:
553 attributes:
554 http.request.resend_count:
555 alias: example_alias
556 subgraph.graphql.document:
557 alias: example_alias
558 subgraph.graphql.operation.name:
559 alias: example_alias
560 subgraph.graphql.operation.type:
561 alias: example_alias
562 subgraph.name:
563 alias: example_alias
564 supergraph:
565 cost.actual:
566 attributes:
567 cost.actual:
568 alias: example_alias
569 cost.delta:
570 alias: example_alias
571 cost.estimated:
572 alias: example_alias
573 cost.result:
574 alias: example_alias
575 graphql.document:
576 alias: example_alias
577 graphql.operation.name:
578 alias: example_alias
579 graphql.operation.type:
580 alias: example_alias
581 cost.delta:
582 attributes:
583 cost.actual:
584 alias: example_alias
585 cost.delta:
586 alias: example_alias
587 cost.estimated:
588 alias: example_alias
589 cost.result:
590 alias: example_alias
591 graphql.document:
592 alias: example_alias
593 graphql.operation.name:
594 alias: example_alias
595 graphql.operation.type:
596 alias: example_alias
597 cost.estimated:
598 attributes:
599 cost.actual:
600 alias: example_alias
601 cost.delta:
602 alias: example_alias
603 cost.estimated:
604 alias: example_alias
605 cost.result:
606 alias: example_alias
607 graphql.document:
608 alias: example_alias
609 graphql.operation.name:
610 alias: example_alias
611 graphql.operation.type:
612 alias: example_alias
613 spans:
614 connector:
615 attributes:
616 connector.http.method:
617 alias: example_alias
618 connector.source.name:
619 alias: example_alias
620 connector.url.template:
621 alias: example_alias
622 subgraph.name:
623 alias: example_alias
624 default_attribute_requirement_level: none
625 mode: deprecated
626 router:
627 attributes:
628 baggage: null
629 dd.trace_id:
630 alias: example_alias
631 error.type:
632 alias: example_alias
633 http.request.body.size:
634 alias: example_alias
635 http.request.method:
636 alias: example_alias
637 http.response.body.size:
638 alias: example_alias
639 http.response.status_code:
640 alias: example_alias
641 http.route:
642 alias: example_alias
643 network.local.address:
644 alias: example_alias
645 network.local.port:
646 alias: example_alias
647 network.peer.address:
648 alias: example_alias
649 network.peer.port:
650 alias: example_alias
651 network.protocol.name:
652 alias: example_alias
653 network.protocol.version:
654 alias: example_alias
655 network.transport:
656 alias: example_alias
657 network.type:
658 alias: example_alias
659 server.address:
660 alias: example_alias
661 server.port:
662 alias: example_alias
663 trace_id:
664 alias: example_alias
665 url.path:
666 alias: example_alias
667 url.query:
668 alias: example_alias
669 url.scheme:
670 alias: example_alias
671 user_agent.original:
672 alias: example_alias
673 subgraph:
674 attributes:
675 http.request.resend_count:
676 alias: example_alias
677 subgraph.graphql.document:
678 alias: example_alias
679 subgraph.graphql.operation.name:
680 alias: example_alias
681 subgraph.graphql.operation.type:
682 alias: example_alias
683 subgraph.name:
684 alias: example_alias
685 supergraph:
686 attributes:
687 cost.actual:
688 alias: example_alias
689 cost.delta:
690 alias: example_alias
691 cost.estimated:
692 alias: example_alias
693 cost.result:
694 alias: example_alias
695 graphql.document:
696 alias: example_alias
697 graphql.operation.name:
698 alias: example_alias
699 graphql.operation.type:
700 alias: example_aliasYAML
telemetry
1telemetry:
2 apollo:
3 batch_processor:
4 max_concurrent_exports: 1
5 max_export_batch_size: 512
6 max_export_timeout:
7 nanos: 0
8 secs: 30
9 max_queue_size: 2048
10 scheduled_delay:
11 nanos: 0
12 secs: 5
13 buffer_size: 10000
14 client_name_header: apollographql-client-name
15 client_version_header: apollographql-client-version
16 endpoint: https://usage-reporting.api.apollographql.com/api/ingress/traces
17 errors:
18 preview_extended_error_metrics: disabled
19 subgraph:
20 all:
21 redact: true
22 redaction_policy: strict
23 send: true
24 subgraphs: {}
25 experimental_local_field_metrics: false
26 experimental_otlp_endpoint: https://usage-reporting.api.apollographql.com/
27 experimental_otlp_tracing_protocol: grpc
28 field_level_instrumentation_sampler: 0.0
29 metrics_reference_mode: extended
30 otlp_tracing_sampler: 0.0
31 send_headers:
32 only:
33 - example_only_item
34 send_variable_values:
35 only:
36 - example_only_item
37 signature_normalization_algorithm: enhanced
38 exporters:
39 logging:
40 common:
41 resource: {}
42 service_name: null
43 service_namespace: null
44 stdout:
45 enabled: true
46 format:
47 json:
48 display_current_span: false
49 display_filename: false
50 display_level: true
51 display_line_number: false
52 display_resource: true
53 display_span_id: true
54 display_span_list: true
55 display_target: true
56 display_thread_id: false
57 display_thread_name: false
58 display_timestamp: true
59 display_trace_id: hexadecimal
60 span_attributes: []
61 expand_json_string_values: false
62 rate_limit:
63 capacity: 1
64 enabled: false
65 interval:
66 nanos: 0
67 secs: 1
68 tty_format:
69 json:
70 display_current_span: false
71 display_filename: false
72 display_level: true
73 display_line_number: false
74 display_resource: true
75 display_span_id: true
76 display_span_list: true
77 display_target: true
78 display_thread_id: false
79 display_thread_name: false
80 display_timestamp: true
81 display_trace_id: hexadecimal
82 span_attributes: []
83 expand_json_string_values: false
84 metrics:
85 common:
86 buckets:
87 - 0.001
88 - 0.005
89 - 0.015
90 - 0.05
91 - 0.1
92 - 0.2
93 - 0.3
94 - 0.4
95 - 0.5
96 - 1.0
97 - 5.0
98 - 10.0
99 resource: {}
100 service_name: null
101 service_namespace: null
102 views:
103 - aggregation:
104 histogram:
105 buckets:
106 - 0.0
107 allowed_attribute_keys:
108 - example_allowed_attribute_keys_item
109 description: example_description
110 name: example_name
111 unit: example_unit
112 otlp:
113 batch_processor:
114 max_concurrent_exports: 1
115 max_export_batch_size: 512
116 max_export_timeout:
117 nanos: 0
118 secs: 30
119 max_queue_size: 2048
120 scheduled_delay:
121 nanos: 0
122 secs: 5
123 enabled: false
124 endpoint: example_endpoint
125 grpc:
126 ca: null
127 cert: null
128 domain_name: null
129 key: null
130 metadata: {}
131 http:
132 headers: {}
133 protocol: grpc
134 temporality: cumulative
135 prometheus:
136 enabled: false
137 listen: example_listen
138 path: /metrics
139 tracing:
140 common:
141 max_attributes_per_event: 128
142 max_attributes_per_link: 128
143 max_attributes_per_span: 128
144 max_events_per_span: 128
145 max_links_per_span: 128
146 parent_based_sampler: true
147 preview_datadog_agent_sampling: null
148 resource: {}
149 sampler: 0.0
150 service_name: null
151 service_namespace: null
152 datadog:
153 batch_processor:
154 max_concurrent_exports: 1
155 max_export_batch_size: 512
156 max_export_timeout:
157 nanos: 0
158 secs: 30
159 max_queue_size: 2048
160 scheduled_delay:
161 nanos: 0
162 secs: 5
163 enable_span_mapping: true
164 enabled: false
165 endpoint: example_endpoint
166 fixed_span_names: true
167 resource_mapping: {}
168 span_metrics:
169 connect: true
170 connect_request: true
171 execution: true
172 http_request: true
173 parse_query: true
174 query_planning: true
175 request: true
176 router: true
177 subgraph: true
178 subgraph_request: true
179 supergraph: true
180 experimental_response_trace_id:
181 enabled: false
182 format: hexadecimal
183 header_name: example_header_name
184 otlp:
185 batch_processor:
186 max_concurrent_exports: 1
187 max_export_batch_size: 512
188 max_export_timeout:
189 nanos: 0
190 secs: 30
191 max_queue_size: 2048
192 scheduled_delay:
193 nanos: 0
194 secs: 5
195 enabled: false
196 endpoint: example_endpoint
197 grpc:
198 ca: null
199 cert: null
200 domain_name: null
201 key: null
202 metadata: {}
203 http:
204 headers: {}
205 protocol: grpc
206 temporality: cumulative
207 propagation:
208 aws_xray: false
209 baggage: false
210 datadog: false
211 jaeger: false
212 request:
213 format: hexadecimal
214 header_name: example_header_name
215 trace_context: false
216 zipkin: false
217 zipkin:
218 batch_processor:
219 max_concurrent_exports: 1
220 max_export_batch_size: 512
221 max_export_timeout:
222 nanos: 0
223 secs: 30
224 max_queue_size: 2048
225 scheduled_delay:
226 nanos: 0
227 secs: 5
228 enabled: false
229 endpoint: example_endpoint
230 instrumentation:
231 events:
232 connector:
233 error:
234 condition:
235 eq:
236 - false
237 - false
238 level: info
239 request:
240 condition:
241 eq:
242 - false
243 - false
244 level: info
245 response:
246 condition:
247 eq:
248 - false
249 - false
250 level: info
251 router:
252 error:
253 condition:
254 eq:
255 - false
256 - false
257 level: info
258 request:
259 condition:
260 eq:
261 - false
262 - false
263 level: info
264 response:
265 condition:
266 eq:
267 - false
268 - false
269 level: info
270 subgraph:
271 error:
272 condition:
273 eq:
274 - false
275 - false
276 level: info
277 request:
278 condition:
279 eq:
280 - false
281 - false
282 level: info
283 response:
284 condition:
285 eq:
286 - false
287 - false
288 level: info
289 supergraph:
290 error:
291 condition:
292 eq:
293 - false
294 - false
295 level: info
296 request:
297 condition:
298 eq:
299 - false
300 - false
301 level: info
302 response:
303 condition:
304 eq:
305 - false
306 - false
307 level: info
308 instruments:
309 cache:
310 apollo.router.operations.entity.cache:
311 attributes:
312 graphql.type.name:
313 alias: example_alias
314 connector:
315 http.client.request.body.size:
316 attributes:
317 connector.http.method:
318 alias: example_alias
319 connector.source.name:
320 alias: example_alias
321 connector.url.template:
322 alias: example_alias
323 subgraph.name:
324 alias: example_alias
325 http.client.request.duration:
326 attributes:
327 connector.http.method:
328 alias: example_alias
329 connector.source.name:
330 alias: example_alias
331 connector.url.template:
332 alias: example_alias
333 subgraph.name:
334 alias: example_alias
335 http.client.response.body.size:
336 attributes:
337 connector.http.method:
338 alias: example_alias
339 connector.source.name:
340 alias: example_alias
341 connector.url.template:
342 alias: example_alias
343 subgraph.name:
344 alias: example_alias
345 default_requirement_level: none
346 graphql:
347 field.execution:
348 attributes:
349 graphql.field.name:
350 alias: example_alias
351 graphql.field.type:
352 alias: example_alias
353 graphql.list.length:
354 alias: example_alias
355 graphql.operation.name:
356 alias: example_alias
357 graphql.type.name:
358 alias: example_alias
359 list.length:
360 attributes:
361 graphql.field.name:
362 alias: example_alias
363 graphql.field.type:
364 alias: example_alias
365 graphql.list.length:
366 alias: example_alias
367 graphql.operation.name:
368 alias: example_alias
369 graphql.type.name:
370 alias: example_alias
371 router:
372 http.server.active_requests:
373 attributes:
374 http.request.method: false
375 server.address: false
376 server.port: false
377 url.scheme: false
378 http.server.request.body.size:
379 attributes:
380 baggage: null
381 dd.trace_id:
382 alias: example_alias
383 error.type:
384 alias: example_alias
385 http.request.body.size:
386 alias: example_alias
387 http.request.method:
388 alias: example_alias
389 http.response.body.size:
390 alias: example_alias
391 http.response.status_code:
392 alias: example_alias
393 http.route:
394 alias: example_alias
395 network.local.address:
396 alias: example_alias
397 network.local.port:
398 alias: example_alias
399 network.peer.address:
400 alias: example_alias
401 network.peer.port:
402 alias: example_alias
403 network.protocol.name:
404 alias: example_alias
405 network.protocol.version:
406 alias: example_alias
407 network.transport:
408 alias: example_alias
409 network.type:
410 alias: example_alias
411 server.address:
412 alias: example_alias
413 server.port:
414 alias: example_alias
415 trace_id:
416 alias: example_alias
417 url.path:
418 alias: example_alias
419 url.query:
420 alias: example_alias
421 url.scheme:
422 alias: example_alias
423 user_agent.original:
424 alias: example_alias
425 http.server.request.duration:
426 attributes:
427 baggage: null
428 dd.trace_id:
429 alias: example_alias
430 error.type:
431 alias: example_alias
432 http.request.body.size:
433 alias: example_alias
434 http.request.method:
435 alias: example_alias
436 http.response.body.size:
437 alias: example_alias
438 http.response.status_code:
439 alias: example_alias
440 http.route:
441 alias: example_alias
442 network.local.address:
443 alias: example_alias
444 network.local.port:
445 alias: example_alias
446 network.peer.address:
447 alias: example_alias
448 network.peer.port:
449 alias: example_alias
450 network.protocol.name:
451 alias: example_alias
452 network.protocol.version:
453 alias: example_alias
454 network.transport:
455 alias: example_alias
456 network.type:
457 alias: example_alias
458 server.address:
459 alias: example_alias
460 server.port:
461 alias: example_alias
462 trace_id:
463 alias: example_alias
464 url.path:
465 alias: example_alias
466 url.query:
467 alias: example_alias
468 url.scheme:
469 alias: example_alias
470 user_agent.original:
471 alias: example_alias
472 http.server.response.body.size:
473 attributes:
474 baggage: null
475 dd.trace_id:
476 alias: example_alias
477 error.type:
478 alias: example_alias
479 http.request.body.size:
480 alias: example_alias
481 http.request.method:
482 alias: example_alias
483 http.response.body.size:
484 alias: example_alias
485 http.response.status_code:
486 alias: example_alias
487 http.route:
488 alias: example_alias
489 network.local.address:
490 alias: example_alias
491 network.local.port:
492 alias: example_alias
493 network.peer.address:
494 alias: example_alias
495 network.peer.port:
496 alias: example_alias
497 network.protocol.name:
498 alias: example_alias
499 network.protocol.version:
500 alias: example_alias
501 network.transport:
502 alias: example_alias
503 network.type:
504 alias: example_alias
505 server.address:
506 alias: example_alias
507 server.port:
508 alias: example_alias
509 trace_id:
510 alias: example_alias
511 url.path:
512 alias: example_alias
513 url.query:
514 alias: example_alias
515 url.scheme:
516 alias: example_alias
517 user_agent.original:
518 alias: example_alias
519 subgraph:
520 http.client.request.body.size:
521 attributes:
522 http.request.resend_count:
523 alias: example_alias
524 subgraph.graphql.document:
525 alias: example_alias
526 subgraph.graphql.operation.name:
527 alias: example_alias
528 subgraph.graphql.operation.type:
529 alias: example_alias
530 subgraph.name:
531 alias: example_alias
532 http.client.request.duration:
533 attributes:
534 http.request.resend_count:
535 alias: example_alias
536 subgraph.graphql.document:
537 alias: example_alias
538 subgraph.graphql.operation.name:
539 alias: example_alias
540 subgraph.graphql.operation.type:
541 alias: example_alias
542 subgraph.name:
543 alias: example_alias
544 http.client.response.body.size:
545 attributes:
546 http.request.resend_count:
547 alias: example_alias
548 subgraph.graphql.document:
549 alias: example_alias
550 subgraph.graphql.operation.name:
551 alias: example_alias
552 subgraph.graphql.operation.type:
553 alias: example_alias
554 subgraph.name:
555 alias: example_alias
556 supergraph:
557 cost.actual:
558 attributes:
559 cost.actual:
560 alias: example_alias
561 cost.delta:
562 alias: example_alias
563 cost.estimated:
564 alias: example_alias
565 cost.result:
566 alias: example_alias
567 graphql.document:
568 alias: example_alias
569 graphql.operation.name:
570 alias: example_alias
571 graphql.operation.type:
572 alias: example_alias
573 cost.delta:
574 attributes:
575 cost.actual:
576 alias: example_alias
577 cost.delta:
578 alias: example_alias
579 cost.estimated:
580 alias: example_alias
581 cost.result:
582 alias: example_alias
583 graphql.document:
584 alias: example_alias
585 graphql.operation.name:
586 alias: example_alias
587 graphql.operation.type:
588 alias: example_alias
589 cost.estimated:
590 attributes:
591 cost.actual:
592 alias: example_alias
593 cost.delta:
594 alias: example_alias
595 cost.estimated:
596 alias: example_alias
597 cost.result:
598 alias: example_alias
599 graphql.document:
600 alias: example_alias
601 graphql.operation.name:
602 alias: example_alias
603 graphql.operation.type:
604 alias: example_alias
605 spans:
606 connector:
607 attributes:
608 connector.http.method:
609 alias: example_alias
610 connector.source.name:
611 alias: example_alias
612 connector.url.template:
613 alias: example_alias
614 subgraph.name:
615 alias: example_alias
616 default_attribute_requirement_level: none
617 mode: deprecated
618 router:
619 attributes:
620 baggage: null
621 dd.trace_id:
622 alias: example_alias
623 error.type:
624 alias: example_alias
625 http.request.body.size:
626 alias: example_alias
627 http.request.method:
628 alias: example_alias
629 http.response.body.size:
630 alias: example_alias
631 http.response.status_code:
632 alias: example_alias
633 http.route:
634 alias: example_alias
635 network.local.address:
636 alias: example_alias
637 network.local.port:
638 alias: example_alias
639 network.peer.address:
640 alias: example_alias
641 network.peer.port:
642 alias: example_alias
643 network.protocol.name:
644 alias: example_alias
645 network.protocol.version:
646 alias: example_alias
647 network.transport:
648 alias: example_alias
649 network.type:
650 alias: example_alias
651 server.address:
652 alias: example_alias
653 server.port:
654 alias: example_alias
655 trace_id:
656 alias: example_alias
657 url.path:
658 alias: example_alias
659 url.query:
660 alias: example_alias
661 url.scheme:
662 alias: example_alias
663 user_agent.original:
664 alias: example_alias
665 subgraph:
666 attributes:
667 http.request.resend_count:
668 alias: example_alias
669 subgraph.graphql.document:
670 alias: example_alias
671 subgraph.graphql.operation.name:
672 alias: example_alias
673 subgraph.graphql.operation.type:
674 alias: example_alias
675 subgraph.name:
676 alias: example_alias
677 supergraph:
678 attributes:
679 cost.actual:
680 alias: example_alias
681 cost.delta:
682 alias: example_alias
683 cost.estimated:
684 alias: example_alias
685 cost.result:
686 alias: example_alias
687 graphql.document:
688 alias: example_alias
689 graphql.operation.name:
690 alias: example_alias
691 graphql.operation.type:
692 alias: example_aliasEnhanced operation signature normalization
Requires ≥ Router v1.49.0
note
The router supports enhanced operation signature normalization in the following versions:
- General availability in v1.54.0 and later
- Experimental in v1.49.0 to v1.53.0
Apollo's legacy operation signature algorithm removes information about certain fields, such as input objects and aliases. This removal means some operations may have the same normalized signature though they are distinct operations.
Enhanced normalization incorporates input types and aliases in signature generation. It also includes other improvements that make it more likely that two operations that only vary slightly have the same signature.
Configure enhanced operation signature normalization in router.yaml with the telemetry.apollo.signature_normalization_algorithm option:
YAML
router.yaml
1telemetry:
2 apollo:
3 signature_normalization_algorithm: enhanced # Default is legacyOnce you enable this configuration, operations with enhanced signatures might appear with different operation IDs than they did previously in GraphOS Studio.
Input types
Enhanced signatures include input object type shapes, while still redacting any actual values.
Legacy signatures replace input object type with {}.
Given the following example operation:
GraphQL
query InlineInputTypeQuery {
inputTypeQuery(
input: {
inputString: "foo"
inputInt: 42
inputBoolean: null
nestedType: { someFloat: 4.2 }
enumInput: SOME_VALUE_1
nestedTypeList: [{ someFloat: 4.2, someNullableFloat: null }]
listInput: [1, 2, 3]
}
) {
enumResponse
}
}The legacy normalization algorithm generates the following signature:
GraphQL
query InlineInputTypeQuery {
inputTypeQuery(input: {}) {
enumResponse
}
}The enhanced normalization algorithm generates the following signature:
GraphQL
query InlineInputTypeQuery {
inputTypeQuery(
input: {
inputString: ""
inputInt: 0
inputBoolean: null
nestedType: { someFloat: 0 }
enumInput: SOME_VALUE_1
nestedTypeList: [{ someFloat: 0, someNullableFloat: null }]
listInput: []
}
) {
enumResponse
}
}Aliases
Enhanced signatures include any field aliases used in an operation. Legacy signatures remove aliases completely, meaning the signature may be invalid if the same field was used with multiple aliases.
Given the following example operation:
GraphQL
query AliasedQuery {
noInputQuery {
interfaceAlias1: interfaceResponse {
sharedField
}
interfaceAlias2: interfaceResponse {
... on InterfaceImplementation1 {
implementation1Field
}
... on InterfaceImplementation2 {
implementation2Field
}
}
inputFieldAlias1: objectTypeWithInputField(boolInput: true) {
stringField
}
inputFieldAlias2: objectTypeWithInputField(boolInput: false) {
intField
}
}
}The legacy normalization algorithm generates the following signature:
GraphQL
query AliasedQuery {
noInputQuery {
interfaceResponse {
sharedField
}
interfaceResponse {
... on InterfaceImplementation1 {
implementation1Field
}
... on InterfaceImplementation2 {
implementation2Field
}
}
objectTypeWithInputField(boolInput: true) {
stringField
}
objectTypeWithInputField(boolInput: false) {
intField
}
}
}The enhanced normalization algorithm generates the following signature:
GraphQL
query AliasedQuery {
noInputQuery {
interfaceAlias1: interfaceResponse {
sharedField
}
interfaceAlias2: interfaceResponse {
... on InterfaceImplementation1 {
implementation1Field
}
... on InterfaceImplementation2 {
implementation2Field
}
}
inputFieldAlias1: objectTypeWithInputField(boolInput: true) {
stringField
}
inputFieldAlias2: objectTypeWithInputField(boolInput: false) {
intField
}
}
}Extended reference reporting
Requires ≥ Router v1.50.0
note
The router supports extended reference reporting in the following versions:
- General availability in v1.54.0 and later
- Experimental in v1.50.0 to v1.53.0
You can configure the router to report enum and input object references for enhanced insights and operation checks. Apollo's legacy reference reporting doesn't include data about enum values and input object fields, meaning you can't view enum and input object field usage in GraphOS Studio. Legacy reporting can also cause inaccurate operation checks.
Configure extended reference reporting in router.yaml with the telemetry.apollo.metrics_reference_mode option like so:
YAML
router.yaml
1telemetry:
2 apollo:
3 metrics_reference_mode: extended # Default is legacyExtended error reporting
Requires ≥ Router v2.1.2
PREVIEW
This feature is in preview. Your questions and feedback are highly valued—don't hesitate to get in touch with your Apollo contact.
note
The router supports extended error reporting in the following versions:
- Preview in v2.1.2 and later
- Experimental in v2.0.0
You can configure the router to report extended error information for improved diagnostics. Apollo's legacy error reporting doesn't include the service or error code, meaning you can't easily attribute errors to their root cause in GraphOS Studio.
Configure extended reference reporting in router.yaml with the telemetry.apollo.errors.preview_extended_error_metrics option like so:
YAML
router.yaml
1telemetry:
2 apollo:
3 errors:
4 preview_extended_error_metrics: enabled # Default is disabledConfiguration effect timing
Once you configure extended reference reporting, you can view enum value and input field usage alongside object field usage in GraphOS Studio for all subsequent operations.
Configuring extended reference reporting automatically turns on enhanced operation checks, though you won't see an immediate change in your operations check behavior.
This delay is because operation checks rely on historical operation data. To ensure sufficient data to distinguish between genuinely unused values and those simply not reported in legacy data, enhanced checks require some operations with extended reference reporting turned on.
Enhanced operation checks
Thanks to extended reference reporting, operation checks can more accurately flag issues for changes to enum values and input object fields. See the comparison table below for differences between standard operation checks based on legacy reference reporting and enhanced checks based on extended reference reporting.
| Standard Check Behavior (Legacy reference reporting) | Enhanced Check Behavior (Extended reference reporting) | |
|---|---|---|
Enum value removal | Removing any enum values is considered a breaking change if any operations use the enum. | Removing enum values is only a breaking change if historical operations use the specific enum value(s) that were removed. |
Default argument changes for input object fields | Changing or removing a default argument is generally considered a breaking change, but changing or removing default values for input object fields isn't. | Changing or removing default values for input object fields is considered a breaking change.You can configure checks to ignore default values changes. |
Nullable input object field removal | Removing a nullable input object field is always considered a breaking change. | Removing a nullable input object field is only considered a breaking change if the nullable field is present in historical operations. If the nullable field is always omitted in historical operations, its removal isn't considered a breaking change. |
Changing nullable input object fields to non-nullable | Changing a nullable input object field to non-nullable is considered a breaking change. | Changing a nullable input object field to non-nullable is only considered a breaking change if the field had a null value in historical operations. If the field was always a non-null value in historical operations, changing it to non-nullable isn't considered a breaking change. |
note
You won't see an immediate change in checks behavior when you first turn on extended reference reporting.
Learn more.
tls
YAML
tls
1tls:
2 connector:
3 all:
4 certificate_authorities: null
5 client_authentication:
6 certificate_chain: example_certificate_chain
7 key: example_key
8 sources: {}
9 subgraph:
10 all:
11 certificate_authorities: null
12 client_authentication:
13 certificate_chain: example_certificate_chain
14 key: example_key
15 subgraphs: {}
16 supergraph:
17 certificate: example_certificate
18 certificate_chain: example_certificate_chain
19 key: example_keyLearn more in TLS for the router.
traffic_shaping
YAML
traffic_shaping
1traffic_shaping:
2 all:
3 compression: gzip
4 deduplicate_query: false
5 dns_resolution_strategy: ipv4_only
6 experimental_http2: enable
7 experimental_http2_keep_alive_interval: null
8 experimental_http2_keep_alive_timeout: null
9 global_rate_limit:
10 capacity: 1
11 interval: 30s
12 timeout: null
13 connector:
14 all:
15 compression: gzip
16 dns_resolution_strategy: ipv4_only
17 experimental_http2: enable
18 experimental_http2_keep_alive_interval: null
19 experimental_http2_keep_alive_timeout: null
20 global_rate_limit:
21 capacity: 1
22 interval: 30s
23 timeout: null
24 sources: {}
25 deduplicate_variables: null
26 router:
27 concurrency_limit: 0
28 global_rate_limit:
29 capacity: 1
30 interval: 30s
31 timeout: null
32 subgraphs: {}Learn more in Traffic Shaping.
YAML configuration utilities
Variable expansion
You can reference variables directly in your YAML config file. This is useful for referencing secrets without including them in the file.
Currently, the router supports expansion of environment variables and file paths. Corresponding variables are prefixed with env. and file., respectively.
The router uses Unix-style expansion. Here are some examples:
${env.ENV_VAR_NAME}expands to the value of environment variableENV_VAR_NAME.${env.ENV_VAR_NAME:-some_default}expands to the value of environment variableENV_VAR_NAME, or falls back to the valuesome_defaultif the environment variable is not defined.${file.a.txt}expands to the contents of the filea.txt.${file.a.txt:-some_default}expands to the contents of the filea.txt, or falls back to the valuesome_defaultif the file does not exist.
Variable expansions are valid only for YAML values, not keys.
Reusing configurations with YAML aliases
You can reuse parts of your configuration file in multiple places using standard YAML aliasing syntax:
YAML
router.yaml
1headers:
2 subgraphs:
3 products:
4 request:
5 - insert: &insert_custom_header
6 name: "custom-header"
7 value: "something"
8 reviews:
9 request:
10 - insert: *insert_custom_headerHere, the name and value entries under &insert_custom_header are reused under *insert_custom_header.
Escaping special characters
To include a literal $ character, double it as $$. The router converts each $$ to a single $:
Config value:
prefix$$suffixResult:
prefix$suffix
Related topics
Give FeedbackFeedback