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.yaml

tip

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.

Example router YAML config file with 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  http1_max_request_buf_size: null
236  http1_max_request_headers: null
237  http_max_request_bytes: 2000000
238  introspection_max_depth: true
239  max_aliases: null
240  max_depth: null
241  max_height: null
242  max_root_fields: null
243  parser_max_recursion: 500
244  parser_max_tokens: 15000
245  warn_only: false
246override_subgraph_url: {}
247persisted_queries:
248  enabled: false
249  experimental_prewarm_query_plan_cache:
250    on_reload: true
251    on_startup: false
252  hot_reload: false
253  local_manifests: null
254  log_unknown: false
255  safelist:
256    enabled: false
257    require_id: false
258plugins: unknown_type_plugins
259preview_entity_cache:
260  enabled: false
261  expose_keys_in_context: false
262  invalidation:
263    concurrent_requests: 10
264    listen: example_listen
265    path: example_path
266    scan_count: 1000
267  metrics:
268    enabled: false
269    separate_per_type: false
270    ttl: 30s
271  subgraph:
272    all:
273      enabled: true
274      invalidation:
275        enabled: false
276        shared_key: ""
277      private_id: null
278      redis:
279        namespace: example_namespace
280        password: example_password
281        pool_size: 1
282        required_to_start: false
283        reset_ttl: true
284        timeout: null
285        tls:
286          certificate_authorities: null
287          client_authentication:
288            certificate_chain: example_certificate_chain
289            key: example_key
290        ttl: null
291        urls:
292          - http://example.com/urls_item
293        username: example_username
294      ttl: 30s
295    subgraphs: {}
296preview_file_uploads:
297  enabled: false
298  protocols:
299    multipart:
300      enabled: true
301      limits:
302        max_file_size: example_max_file_size
303        max_files: 0
304      mode: stream
305progressive_override: {}
306reload:
307  max_retries: 5
308  retry_delay: 10s
309rhai:
310  main: example_main
311  scripts: example_scripts
312sandbox:
313  enabled: false
314subscription:
315  enable_deduplication: true
316  enabled: true
317  max_opened_subscriptions: null
318  mode:
319    callback:
320      heartbeat_interval: disabled
321      listen: example_listen
322      path: example_path
323      public_url: http://service.example.com/public_url
324      subgraphs: []
325    passthrough:
326      all:
327        heartbeat_interval: disabled
328        path: null
329        protocol: graphql_ws
330      subgraphs: {}
331  queue_capacity: null
332supergraph:
333  defer_support: true
334  early_cancel: false
335  experimental_log_on_broken_pipe: false
336  generate_query_fragments: true
337  introspection: false
338  listen: example_listen
339  path: /
340  redact_query_validation_errors: false
341  query_planning:
342    cache:
343      in_memory:
344        limit: 1
345      redis:
346        namespace: example_namespace
347        password: example_password
348        pool_size: 1
349        required_to_start: false
350        reset_ttl: true
351        timeout: null
352        tls:
353          certificate_authorities: null
354          client_authentication:
355            certificate_chain: example_certificate_chain
356            key: example_key
357        ttl:
358          secs: 2592000
359          nanos: 0
360        urls:
361          - http://example.com/urls_item
362        username: example_username
363    experimental_paths_limit: null
364    experimental_plans_limit: null
365    experimental_reuse_query_plans: false
366    warmed_up_queries: null
367  strict_variable_validation: enforce
368telemetry:
369  apollo:
370    batch_processor:
371      max_concurrent_exports: 1
372      max_export_batch_size: 512
373      max_export_timeout:
374        secs: 30
375        nanos: 0
376      max_queue_size: 2048
377      scheduled_delay:
378        secs: 5
379        nanos: 0
380    buffer_size: 10000
381    client_name_header: apollographql-client-name
382    client_version_header: apollographql-client-version
383    endpoint: https://usage-reporting.api.apollographql.com/api/ingress/traces
384    errors:
385      preview_extended_error_metrics: disabled
386      subgraph:
387        all:
388          redact: true
389          redaction_policy: strict
390          send: true
391        subgraphs: {}
392    experimental_local_field_metrics: false
393    experimental_otlp_endpoint: https://usage-reporting.api.apollographql.com/
394    experimental_otlp_tracing_protocol: grpc
395    field_level_instrumentation_sampler: 0.0
396    metrics_reference_mode: extended
397    otlp_tracing_sampler: 0.0
398    send_headers:
399      only:
400        - example_only_item
401    send_variable_values:
402      only:
403        - example_only_item
404    signature_normalization_algorithm: legacy
405  exporters:
406    logging:
407      common:
408        resource: {}
409        service_name: null
410        service_namespace: null
411      stdout:
412        enabled: true
413        format:
414          json:
415            display_current_span: false
416            display_filename: false
417            display_level: true
418            display_line_number: false
419            display_resource: true
420            display_span_id: true
421            display_span_list: true
422            display_target: true
423            display_thread_id: false
424            display_thread_name: false
425            display_timestamp: true
426            display_trace_id: hexadecimal
427            span_attributes: []
428        rate_limit:
429          capacity: 1
430          enabled: false
431          interval:
432            secs: 1
433            nanos: 0
434        tty_format:
435          json:
436            display_current_span: false
437            display_filename: false
438            display_level: true
439            display_line_number: false
440            display_resource: true
441            display_span_id: true
442            display_span_list: true
443            display_target: true
444            display_thread_id: false
445            display_thread_name: false
446            display_timestamp: true
447            display_trace_id: hexadecimal
448            span_attributes: []
449    metrics:
450      common:
451        buckets:
452          - 0.001
453          - 0.005
454          - 0.015
455          - 0.05
456          - 0.1
457          - 0.2
458          - 0.3
459          - 0.4
460          - 0.5
461          - 1.0
462          - 5.0
463          - 10.0
464        resource: {}
465        service_name: null
466        service_namespace: null
467        views:
468          - aggregation:
469              histogram:
470                buckets:
471                  - 0.0
472            allowed_attribute_keys:
473              - example_allowed_attribute_keys_item
474            description: example_description
475            name: example_name
476            unit: example_unit
477      otlp:
478        batch_processor:
479          max_concurrent_exports: 1
480          max_export_batch_size: 512
481          max_export_timeout:
482            secs: 30
483            nanos: 0
484          max_queue_size: 2048
485          scheduled_delay:
486            secs: 5
487            nanos: 0
488        enabled: false
489        endpoint: example_endpoint
490        grpc:
491          ca: null
492          cert: null
493          domain_name: null
494          key: null
495          metadata: {}
496        http:
497          headers: {}
498        protocol: grpc
499        temporality: cumulative
500      prometheus:
501        enabled: false
502        listen: example_listen
503        path: /metrics
504    tracing:
505      common:
506        max_attributes_per_event: 128
507        max_attributes_per_link: 128
508        max_attributes_per_span: 128
509        max_events_per_span: 128
510        max_links_per_span: 128
511        parent_based_sampler: true
512        preview_datadog_agent_sampling: null
513        resource: {}
514        sampler: 0.0
515        service_name: null
516        service_namespace: null
517      datadog:
518        batch_processor:
519          max_concurrent_exports: 1
520          max_export_batch_size: 512
521          max_export_timeout:
522            secs: 30
523            nanos: 0
524          max_queue_size: 2048
525          scheduled_delay:
526            secs: 5
527            nanos: 0
528        enable_span_mapping: true
529        enabled: false
530        endpoint: example_endpoint
531        fixed_span_names: true
532        resource_mapping: {}
533        span_metrics:
534          parse_query: true
535          connect: true
536          execution: true
537          http_request: true
538          request: true
539          query_planning: true
540          connect_request: true
541          subgraph: true
542          router: true
543          supergraph: true
544          subgraph_request: true
545      experimental_response_trace_id:
546        enabled: false
547        format: hexadecimal
548        header_name: example_header_name
549      otlp:
550        batch_processor:
551          max_concurrent_exports: 1
552          max_export_batch_size: 512
553          max_export_timeout:
554            secs: 30
555            nanos: 0
556          max_queue_size: 2048
557          scheduled_delay:
558            secs: 5
559            nanos: 0
560        enabled: false
561        endpoint: example_endpoint
562        grpc:
563          ca: null
564          cert: null
565          domain_name: null
566          key: null
567          metadata: {}
568        http:
569          headers: {}
570        protocol: grpc
571        temporality: cumulative
572      propagation:
573        aws_xray: false
574        baggage: false
575        datadog: false
576        jaeger: false
577        request:
578          format: hexadecimal
579          header_name: example_header_name
580        trace_context: false
581        zipkin: false
582      zipkin:
583        batch_processor:
584          max_concurrent_exports: 1
585          max_export_batch_size: 512
586          max_export_timeout:
587            secs: 30
588            nanos: 0
589          max_queue_size: 2048
590          scheduled_delay:
591            secs: 5
592            nanos: 0
593        enabled: false
594        endpoint: example_endpoint
595  instrumentation:
596    events:
597      connector:
598        error:
599          condition:
600            eq:
601              - false
602              - false
603          level: info
604        request:
605          condition:
606            eq:
607              - false
608              - false
609          level: info
610        response:
611          condition:
612            eq:
613              - false
614              - false
615          level: info
616      router:
617        error:
618          condition:
619            eq:
620              - false
621              - false
622          level: info
623        request:
624          condition:
625            eq:
626              - false
627              - false
628          level: info
629        response:
630          condition:
631            eq:
632              - false
633              - false
634          level: info
635      subgraph:
636        error:
637          condition:
638            eq:
639              - false
640              - false
641          level: info
642        request:
643          condition:
644            eq:
645              - false
646              - false
647          level: info
648        response:
649          condition:
650            eq:
651              - false
652              - false
653          level: info
654      supergraph:
655        error:
656          condition:
657            eq:
658              - false
659              - false
660          level: info
661        request:
662          condition:
663            eq:
664              - false
665              - false
666          level: info
667        response:
668          condition:
669            eq:
670              - false
671              - false
672          level: info
673    instruments:
674      cache:
675        apollo.router.operations.entity.cache:
676          attributes:
677            graphql.type.name:
678              alias: example_alias
679      connector:
680        http.client.request.body.size:
681          attributes:
682            connector.http.method:
683              alias: example_alias
684            connector.source.name:
685              alias: example_alias
686            connector.url.template:
687              alias: example_alias
688            subgraph.name:
689              alias: example_alias
690        http.client.request.duration:
691          attributes:
692            connector.http.method:
693              alias: example_alias
694            connector.source.name:
695              alias: example_alias
696            connector.url.template:
697              alias: example_alias
698            subgraph.name:
699              alias: example_alias
700        http.client.response.body.size:
701          attributes:
702            connector.http.method:
703              alias: example_alias
704            connector.source.name:
705              alias: example_alias
706            connector.url.template:
707              alias: example_alias
708            subgraph.name:
709              alias: example_alias
710      default_requirement_level: none
711      graphql:
712        field.execution:
713          attributes:
714            graphql.field.name:
715              alias: example_alias
716            graphql.field.type:
717              alias: example_alias
718            graphql.list.length:
719              alias: example_alias
720            graphql.operation.name:
721              alias: example_alias
722            graphql.type.name:
723              alias: example_alias
724        list.length:
725          attributes:
726            graphql.field.name:
727              alias: example_alias
728            graphql.field.type:
729              alias: example_alias
730            graphql.list.length:
731              alias: example_alias
732            graphql.operation.name:
733              alias: example_alias
734            graphql.type.name:
735              alias: example_alias
736      router:
737        http.server.active_requests:
738          attributes:
739            http.request.method: false
740            server.address: false
741            server.port: false
742            url.scheme: false
743        http.server.request.body.size:
744          attributes:
745            baggage: null
746            dd.trace_id:
747              alias: example_alias
748            error.type:
749              alias: example_alias
750            http.request.body.size:
751              alias: example_alias
752            http.request.method:
753              alias: example_alias
754            http.response.body.size:
755              alias: example_alias
756            http.response.status_code:
757              alias: example_alias
758            http.route:
759              alias: example_alias
760            network.local.address:
761              alias: example_alias
762            network.local.port:
763              alias: example_alias
764            network.peer.address:
765              alias: example_alias
766            network.peer.port:
767              alias: example_alias
768            network.protocol.name:
769              alias: example_alias
770            network.protocol.version:
771              alias: example_alias
772            network.transport:
773              alias: example_alias
774            network.type:
775              alias: example_alias
776            server.address:
777              alias: example_alias
778            server.port:
779              alias: example_alias
780            trace_id:
781              alias: example_alias
782            url.path:
783              alias: example_alias
784            url.query:
785              alias: example_alias
786            url.scheme:
787              alias: example_alias
788            user_agent.original:
789              alias: example_alias
790        http.server.request.duration:
791          attributes:
792            baggage: null
793            dd.trace_id:
794              alias: example_alias
795            error.type:
796              alias: example_alias
797            http.request.body.size:
798              alias: example_alias
799            http.request.method:
800              alias: example_alias
801            http.response.body.size:
802              alias: example_alias
803            http.response.status_code:
804              alias: example_alias
805            http.route:
806              alias: example_alias
807            network.local.address:
808              alias: example_alias
809            network.local.port:
810              alias: example_alias
811            network.peer.address:
812              alias: example_alias
813            network.peer.port:
814              alias: example_alias
815            network.protocol.name:
816              alias: example_alias
817            network.protocol.version:
818              alias: example_alias
819            network.transport:
820              alias: example_alias
821            network.type:
822              alias: example_alias
823            server.address:
824              alias: example_alias
825            server.port:
826              alias: example_alias
827            trace_id:
828              alias: example_alias
829            url.path:
830              alias: example_alias
831            url.query:
832              alias: example_alias
833            url.scheme:
834              alias: example_alias
835            user_agent.original:
836              alias: example_alias
837        http.server.response.body.size:
838          attributes:
839            baggage: null
840            dd.trace_id:
841              alias: example_alias
842            error.type:
843              alias: example_alias
844            http.request.body.size:
845              alias: example_alias
846            http.request.method:
847              alias: example_alias
848            http.response.body.size:
849              alias: example_alias
850            http.response.status_code:
851              alias: example_alias
852            http.route:
853              alias: example_alias
854            network.local.address:
855              alias: example_alias
856            network.local.port:
857              alias: example_alias
858            network.peer.address:
859              alias: example_alias
860            network.peer.port:
861              alias: example_alias
862            network.protocol.name:
863              alias: example_alias
864            network.protocol.version:
865              alias: example_alias
866            network.transport:
867              alias: example_alias
868            network.type:
869              alias: example_alias
870            server.address:
871              alias: example_alias
872            server.port:
873              alias: example_alias
874            trace_id:
875              alias: example_alias
876            url.path:
877              alias: example_alias
878            url.query:
879              alias: example_alias
880            url.scheme:
881              alias: example_alias
882            user_agent.original:
883              alias: example_alias
884      subgraph:
885        http.client.request.body.size:
886          attributes:
887            http.request.resend_count:
888              alias: example_alias
889            subgraph.graphql.document:
890              alias: example_alias
891            subgraph.graphql.operation.name:
892              alias: example_alias
893            subgraph.graphql.operation.type:
894              alias: example_alias
895            subgraph.name:
896              alias: example_alias
897        http.client.request.duration:
898          attributes:
899            http.request.resend_count:
900              alias: example_alias
901            subgraph.graphql.document:
902              alias: example_alias
903            subgraph.graphql.operation.name:
904              alias: example_alias
905            subgraph.graphql.operation.type:
906              alias: example_alias
907            subgraph.name:
908              alias: example_alias
909        http.client.response.body.size:
910          attributes:
911            http.request.resend_count:
912              alias: example_alias
913            subgraph.graphql.document:
914              alias: example_alias
915            subgraph.graphql.operation.name:
916              alias: example_alias
917            subgraph.graphql.operation.type:
918              alias: example_alias
919            subgraph.name:
920              alias: example_alias
921      supergraph:
922        cost.actual:
923          attributes:
924            cost.actual:
925              alias: example_alias
926            cost.delta:
927              alias: example_alias
928            cost.estimated:
929              alias: example_alias
930            cost.result:
931              alias: example_alias
932            graphql.document:
933              alias: example_alias
934            graphql.operation.name:
935              alias: example_alias
936            graphql.operation.type:
937              alias: example_alias
938        cost.delta:
939          attributes:
940            cost.actual:
941              alias: example_alias
942            cost.delta:
943              alias: example_alias
944            cost.estimated:
945              alias: example_alias
946            cost.result:
947              alias: example_alias
948            graphql.document:
949              alias: example_alias
950            graphql.operation.name:
951              alias: example_alias
952            graphql.operation.type:
953              alias: example_alias
954        cost.estimated:
955          attributes:
956            cost.actual:
957              alias: example_alias
958            cost.delta:
959              alias: example_alias
960            cost.estimated:
961              alias: example_alias
962            cost.result:
963              alias: example_alias
964            graphql.document:
965              alias: example_alias
966            graphql.operation.name:
967              alias: example_alias
968            graphql.operation.type:
969              alias: example_alias
970    spans:
971      connector:
972        attributes:
973          connector.http.method:
974            alias: example_alias
975          connector.source.name:
976            alias: example_alias
977          connector.url.template:
978            alias: example_alias
979          subgraph.name:
980            alias: example_alias
981      default_attribute_requirement_level: none
982      mode: deprecated
983      router:
984        attributes:
985          baggage: null
986          dd.trace_id:
987            alias: example_alias
988          error.type:
989            alias: example_alias
990          http.request.body.size:
991            alias: example_alias
992          http.request.method:
993            alias: example_alias
994          http.response.body.size:
995            alias: example_alias
996          http.response.status_code:
997            alias: example_alias
998          http.route:
999            alias: example_alias
1000          network.local.address:
1001            alias: example_alias
1002          network.local.port:
1003            alias: example_alias
1004          network.peer.address:
1005            alias: example_alias
1006          network.peer.port:
1007            alias: example_alias
1008          network.protocol.name:
1009            alias: example_alias
1010          network.protocol.version:
1011            alias: example_alias
1012          network.transport:
1013            alias: example_alias
1014          network.type:
1015            alias: example_alias
1016          server.address:
1017            alias: example_alias
1018          server.port:
1019            alias: example_alias
1020          trace_id:
1021            alias: example_alias
1022          url.path:
1023            alias: example_alias
1024          url.query:
1025            alias: example_alias
1026          url.scheme:
1027            alias: example_alias
1028          user_agent.original:
1029            alias: example_alias
1030      subgraph:
1031        attributes:
1032          http.request.resend_count:
1033            alias: example_alias
1034          subgraph.graphql.document:
1035            alias: example_alias
1036          subgraph.graphql.operation.name:
1037            alias: example_alias
1038          subgraph.graphql.operation.type:
1039            alias: example_alias
1040          subgraph.name:
1041            alias: example_alias
1042      supergraph:
1043        attributes:
1044          cost.actual:
1045            alias: example_alias
1046          cost.delta:
1047            alias: example_alias
1048          cost.estimated:
1049            alias: example_alias
1050          cost.result:
1051            alias: example_alias
1052          graphql.document:
1053            alias: example_alias
1054          graphql.operation.name:
1055            alias: example_alias
1056          graphql.operation.type:
1057            alias: example_alias
1058tls:
1059  connector:
1060    all:
1061      certificate_authorities: null
1062      client_authentication:
1063        certificate_chain: example_certificate_chain
1064        key: example_key
1065    sources: {}
1066  subgraph:
1067    all:
1068      certificate_authorities: null
1069      client_authentication:
1070        certificate_chain: example_certificate_chain
1071        key: example_key
1072    subgraphs: {}
1073  supergraph:
1074    certificate: example_certificate
1075    certificate_chain: example_certificate_chain
1076    key: example_key
1077traffic_shaping:
1078  all:
1079    compression: gzip
1080    deduplicate_query: false
1081    dns_resolution_strategy: ipv4_only
1082    experimental_http2: enable
1083    global_rate_limit:
1084      capacity: 1
1085      interval: 30s
1086    timeout: null
1087  connector:
1088    all:
1089      compression: gzip
1090      dns_resolution_strategy: ipv4_only
1091      experimental_http2: enable
1092      global_rate_limit:
1093        capacity: 1
1094        interval: 30s
1095      timeout: null
1096    sources: {}
1097  deduplicate_variables: null
1098  router:
1099    concurrency_limit: 0
1100    global_rate_limit:
1101      capacity: 1
1102      interval: 30s
1103    timeout: null
1104  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`

authentication YAML snippet

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: false

To 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`

coprocessor YAML snippet

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/url

Learn 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 defaults

By 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: false

Learn 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: null

`experimental_hoist_orphan_errors`

YAML

experimental_hoist_orphan_errors

1experimental_hoist_orphan_errors:
2  all:
3    enabled: false
4  subgraphs: {}

Experimental Feature

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: true

To target all subgraphs:

YAML

router.yaml

1experimental_hoist_orphan_errors:
2  all:
3    enabled: true

To 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: false

Per-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: false

`fleet_detector`

YAML

fleet_detector

1fleet_detector: {}

`forbid_mutations`

YAML

forbid_mutations

1forbid_mutations: false

`headers`

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: null

Learn more in Health Checks.

`homepage`

YAML

homepage

1homepage:
2  enabled: true
3  graph_ref: null

The router can serve a landing page to browsers that visit its endpoint path (supergraph.path):

A basic landing page that displays an example query curl command (default)

YAML

router.yaml

1# This is the default behavior. You don't need to include this config.
2homepage:
3  enabled: true

No landing page
YAML
router.yaml
1homepage: 2 enabled: false
Sending users to Apollo Explorer
YAML
router.yaml
1homepage: 2 graph_ref: my-org-graph@production
When 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.
note
The graph_ref value should match the format organization-name@variant-name, which is the same format used with the APOLLO_GRAPH_REF environment variable. Note that the router does not automatically use the value from the APOLLO_GRAPH_REF environment variable for this setting - you must explicitly set graph_ref in 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  http1_max_request_buf_size: null
3  http1_max_request_headers: null
4  http_max_request_bytes: 2000000
5  introspection_max_depth: true
6  max_aliases: null
7  max_depth: null
8  max_height: null
9  max_root_fields: null
10  parser_max_recursion: 500
11  parser_max_tokens: 15000
12  warn_only: false

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: false

You 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_plugins

You 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: 1

Learn more in Native Plugins for router.

`preview_entity_cache`

preview_entity_cache YAML snippet

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`

response_cache YAML snippet

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: stream

Learn 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: 10s

Learn more about configuring reload retries.

`rhai`

YAML

rhai

1rhai:
2  main: example_main
3  scripts: example_scripts
4  # intern_strings: false

Learn more in Rhai customization for router.

`sandbox`

YAML

sandbox

1sandbox:
2  enabled: false

Apollo 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: false

caution

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: 30s

Header 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: null

Learn more in Subscriptions.

`supergraph`

supergraph YAML snippet

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: enforce

Supergraph 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:4000

IPv6

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.sock

note

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: /graphql

The path must start with /.

A path can contain parameters and wildcards:

/{parameter} matches a single segment. For example:
- /abc/{my_param}/def matches /abc/1/def and /abc/whatever/def, but it doesn't match /abc/1/2/def or /abc/def
/{*parameter} matches all segments in the rest of a path. For example:
- /abc/{*wildcard} matches /abc/1/def and /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: true

Introspection 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: false

Redacting 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: true

When 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: true

Additionally, 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: true

Connection 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: 60s

The 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: 60s

Automatic 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: false

Variable 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: enforce

If 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`

telemetry YAML snippet (>= Router v2.7.0)

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_alias

telemetry YAML snippet (deprecated <= Router v2.6)

YAML

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_alias

Enhanced 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 legacy

Once 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 legacy

Extended 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 disabled

Learn more.

Configuration 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_key

Learn 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 variable ENV_VAR_NAME.
${env.ENV_VAR_NAME:-some_default} expands to the value of environment variable ENV_VAR_NAME, or falls back to the value some_default if the environment variable is not defined.
${file.a.txt} expands to the contents of the file a.txt.
${file.a.txt:-some_default} expands to the contents of the file a.txt, or falls back to the value some_default if 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_header

Here, 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$$suffix
Result: prefix$suffix

Checklist for configuring the router for production

Log Exporters

Metrics Exporters

Trace Exporters

Instrumentation

AWS Lattice

Log Exporters

Metrics Exporters

Trace Exporters

Instrumentation

AWS Lattice

Router YAML Configuration Reference

YAML configuration properties

Example YAML with all properties

Properties

apq

authentication

authorization

batching

connectors

coprocessor

cors

csrf

demand_control

experimental_chaos

experimental_hoist_orphan_errors

experimental_type_conditioned_fetching

fleet_detector

forbid_mutations

headers

health_check

homepage

include_subgraph_errors

license_enforcement

limits

override_subgraph_url

persisted_queries

plugins

preview_entity_cache

response_cache

preview_file_uploads

reload

rhai

sandbox

server

Header Read Timeout

TLS handshake timeout

subscription

supergraph

`apq`

`authentication`

`authorization`

`batching`

`connectors`

`coprocessor`

`cors`

`csrf`

`demand_control`

`experimental_chaos`

`experimental_hoist_orphan_errors`

`experimental_type_conditioned_fetching`

`fleet_detector`

`forbid_mutations`

`headers`

`health_check`

`homepage`

`include_subgraph_errors`

`license_enforcement`

`limits`

`override_subgraph_url`

`persisted_queries`

`plugins`

`preview_entity_cache`

`response_cache`

`preview_file_uploads`

`reload`

`rhai`

`sandbox`

`server`

`subscription`

`supergraph`