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

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

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  execution:
6    request:
7      body: false
8      context: false
9      headers: false
10      method: false
11      query_plan: false
12      sdl: false
13    response:
14      body: false
15      context: false
16      headers: false
17      sdl: false
18      status_code: false
19  router:
20    request:
21      body: false
22      condition:
23        eq:
24        - false
25        - false
26      context: false
27      headers: false
28      method: false
29      path: false
30      sdl: false
31    response:
32      body: false
33      condition:
34        eq:
35        - false
36        - false
37      context: false
38      headers: false
39      sdl: false
40      status_code: false
41  subgraph:
42    all:
43      request:
44        body: false
45        condition:
46          eq:
47          - false
48          - false
49        context: false
50        headers: false
51        method: false
52        service_name: false
53        subgraph_request_id: false
54        uri: false
55      response:
56        body: false
57        condition:
58          eq:
59          - false
60          - false
61        context: false
62        headers: false
63        service_name: false
64        status_code: false
65        subgraph_request_id: false
66  supergraph:
67    request:
68      body: false
69      condition:
70        eq:
71        - false
72        - false
73      context: false
74      headers: false
75      method: false
76      sdl: false
77    response:
78      body: false
79      condition:
80        eq:
81        - false
82        - false
83      context: false
84      headers: false
85      sdl: false
86      status_code: false
87  timeout:
88    nanos: 0
89    secs: 1
90  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  match_origins: null
7  max_age: null
8  methods:
9  - GET
10  - POST
11  - OPTIONS
12  origins:
13  - https://studio.apollographql.com

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

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_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

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

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 in 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: {}

Learn more in Entity 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      mode: stream

Learn more in File Uploads.

progressive_override

YAML
progressive_override
1progressive_override: {}

Learn more in Progressive Override.

rhai

YAML
rhai
1rhai:
2  main: example_main
3  scripts: example_scripts

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.

subscription

YAML
subscription
1subscription:
2  enable_deduplication: true
3  enabled: true
4  max_opened_subscriptions: null
5  mode:
6    callback:
7      heartbeat_interval: disabled
8      listen: example_listen
9      path: example_path
10      public_url: http://service.example.com/public_url
11      subgraphs: []
12    passthrough:
13      all:
14        heartbeat_interval: disabled
15        path: null
16        protocol: graphql_ws
17      subgraphs: {}
18  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  query_planning:
10    cache:
11      in_memory:
12        limit: 1
13      redis:
14        namespace: example_namespace
15        password: example_password
16        pool_size: 1
17        required_to_start: false
18        reset_ttl: true
19        timeout: null
20        tls:
21          certificate_authorities: null
22          client_authentication:
23            certificate_chain: example_certificate_chain
24            key: example_key
25        ttl:
26          nanos: 0
27          secs: 2592000
28        urls:
29        - http://example.com/urls_item
30        username: example_username
31    experimental_paths_limit: null
32    experimental_plans_limit: null
33    experimental_reuse_query_plans: false
34    warmed_up_queries: null

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

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

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.

You can explicitly opt-out of this behavior by specifying supergraph.generate_query_fragments:

YAML
1supergraph:
2  generate_query_fragments: false

telemetry

telemetry YAML snippet
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: legacy
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        rate_limit:
62          capacity: 1
63          enabled: false
64          interval:
65            nanos: 0
66            secs: 1
67        tty_format:
68          json:
69            display_current_span: false
70            display_filename: false
71            display_level: true
72            display_line_number: false
73            display_resource: true
74            display_span_id: true
75            display_span_list: true
76            display_target: true
77            display_thread_id: false
78            display_thread_name: false
79            display_timestamp: true
80            display_trace_id: hexadecimal
81            span_attributes: []
82    metrics:
83      common:
84        buckets:
85        - 0.001
86        - 0.005
87        - 0.015
88        - 0.05
89        - 0.1
90        - 0.2
91        - 0.3
92        - 0.4
93        - 0.5
94        - 1.0
95        - 5.0
96        - 10.0
97        resource: {}
98        service_name: null
99        service_namespace: null
100        views:
101        - aggregation:
102            histogram:
103              buckets:
104              - 0.0
105          allowed_attribute_keys:
106          - example_allowed_attribute_keys_item
107          description: example_description
108          name: example_name
109          unit: example_unit
110      otlp:
111        batch_processor:
112          max_concurrent_exports: 1
113          max_export_batch_size: 512
114          max_export_timeout:
115            nanos: 0
116            secs: 30
117          max_queue_size: 2048
118          scheduled_delay:
119            nanos: 0
120            secs: 5
121        enabled: false
122        endpoint: example_endpoint
123        grpc:
124          ca: null
125          cert: null
126          domain_name: null
127          key: null
128          metadata: {}
129        http:
130          headers: {}
131        protocol: grpc
132        temporality: cumulative
133      prometheus:
134        enabled: false
135        listen: example_listen
136        path: /metrics
137    tracing:
138      common:
139        max_attributes_per_event: 128
140        max_attributes_per_link: 128
141        max_attributes_per_span: 128
142        max_events_per_span: 128
143        max_links_per_span: 128
144        parent_based_sampler: true
145        preview_datadog_agent_sampling: null
146        resource: {}
147        sampler: 0.0
148        service_name: null
149        service_namespace: null
150      datadog:
151        batch_processor:
152          max_concurrent_exports: 1
153          max_export_batch_size: 512
154          max_export_timeout:
155            nanos: 0
156            secs: 30
157          max_queue_size: 2048
158          scheduled_delay:
159            nanos: 0
160            secs: 5
161        enable_span_mapping: true
162        enabled: false
163        endpoint: example_endpoint
164        fixed_span_names: true
165        resource_mapping: {}
166        span_metrics:
167          connect: true
168          connect_request: true
169          execution: true
170          http_request: true
171          parse_query: true
172          query_planning: true
173          request: true
174          router: true
175          subgraph: true
176          subgraph_request: true
177          supergraph: true
178      experimental_response_trace_id:
179        enabled: false
180        format: hexadecimal
181        header_name: example_header_name
182      otlp:
183        batch_processor:
184          max_concurrent_exports: 1
185          max_export_batch_size: 512
186          max_export_timeout:
187            nanos: 0
188            secs: 30
189          max_queue_size: 2048
190          scheduled_delay:
191            nanos: 0
192            secs: 5
193        enabled: false
194        endpoint: example_endpoint
195        grpc:
196          ca: null
197          cert: null
198          domain_name: null
199          key: null
200          metadata: {}
201        http:
202          headers: {}
203        protocol: grpc
204        temporality: cumulative
205      propagation:
206        aws_xray: false
207        baggage: false
208        datadog: false
209        jaeger: false
210        request:
211          format: hexadecimal
212          header_name: example_header_name
213        trace_context: false
214        zipkin: false
215      zipkin:
216        batch_processor:
217          max_concurrent_exports: 1
218          max_export_batch_size: 512
219          max_export_timeout:
220            nanos: 0
221            secs: 30
222          max_queue_size: 2048
223          scheduled_delay:
224            nanos: 0
225            secs: 5
226        enabled: false
227        endpoint: example_endpoint
228  instrumentation:
229    events:
230      connector:
231        error:
232          condition:
233            eq:
234            - false
235            - false
236          level: info
237        request:
238          condition:
239            eq:
240            - false
241            - false
242          level: info
243        response:
244          condition:
245            eq:
246            - false
247            - false
248          level: info
249      router:
250        error:
251          condition:
252            eq:
253            - false
254            - false
255          level: info
256        request:
257          condition:
258            eq:
259            - false
260            - false
261          level: info
262        response:
263          condition:
264            eq:
265            - false
266            - false
267          level: info
268      subgraph:
269        error:
270          condition:
271            eq:
272            - false
273            - false
274          level: info
275        request:
276          condition:
277            eq:
278            - false
279            - false
280          level: info
281        response:
282          condition:
283            eq:
284            - false
285            - false
286          level: info
287      supergraph:
288        error:
289          condition:
290            eq:
291            - false
292            - false
293          level: info
294        request:
295          condition:
296            eq:
297            - false
298            - false
299          level: info
300        response:
301          condition:
302            eq:
303            - false
304            - false
305          level: info
306    instruments:
307      cache:
308        apollo.router.operations.entity.cache:
309          attributes:
310            graphql.type.name:
311              alias: example_alias
312      connector:
313        http.client.request.body.size:
314          attributes:
315            connector.http.method:
316              alias: example_alias
317            connector.source.name:
318              alias: example_alias
319            connector.url.template:
320              alias: example_alias
321            subgraph.name:
322              alias: example_alias
323        http.client.request.duration:
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.response.body.size:
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      default_requirement_level: none
344      graphql:
345        field.execution:
346          attributes:
347            graphql.field.name:
348              alias: example_alias
349            graphql.field.type:
350              alias: example_alias
351            graphql.list.length:
352              alias: example_alias
353            graphql.operation.name:
354              alias: example_alias
355            graphql.type.name:
356              alias: example_alias
357        list.length:
358          attributes:
359            graphql.field.name:
360              alias: example_alias
361            graphql.field.type:
362              alias: example_alias
363            graphql.list.length:
364              alias: example_alias
365            graphql.operation.name:
366              alias: example_alias
367            graphql.type.name:
368              alias: example_alias
369      router:
370        http.server.active_requests:
371          attributes:
372            http.request.method: false
373            server.address: false
374            server.port: false
375            url.scheme: false
376        http.server.request.body.size:
377          attributes:
378            baggage: null
379            dd.trace_id:
380              alias: example_alias
381            error.type:
382              alias: example_alias
383            http.request.body.size:
384              alias: example_alias
385            http.request.method:
386              alias: example_alias
387            http.response.body.size:
388              alias: example_alias
389            http.response.status_code:
390              alias: example_alias
391            http.route:
392              alias: example_alias
393            network.local.address:
394              alias: example_alias
395            network.local.port:
396              alias: example_alias
397            network.peer.address:
398              alias: example_alias
399            network.peer.port:
400              alias: example_alias
401            network.protocol.name:
402              alias: example_alias
403            network.protocol.version:
404              alias: example_alias
405            network.transport:
406              alias: example_alias
407            network.type:
408              alias: example_alias
409            server.address:
410              alias: example_alias
411            server.port:
412              alias: example_alias
413            trace_id:
414              alias: example_alias
415            url.path:
416              alias: example_alias
417            url.query:
418              alias: example_alias
419            url.scheme:
420              alias: example_alias
421            user_agent.original:
422              alias: example_alias
423        http.server.request.duration:
424          attributes:
425            baggage: null
426            dd.trace_id:
427              alias: example_alias
428            error.type:
429              alias: example_alias
430            http.request.body.size:
431              alias: example_alias
432            http.request.method:
433              alias: example_alias
434            http.response.body.size:
435              alias: example_alias
436            http.response.status_code:
437              alias: example_alias
438            http.route:
439              alias: example_alias
440            network.local.address:
441              alias: example_alias
442            network.local.port:
443              alias: example_alias
444            network.peer.address:
445              alias: example_alias
446            network.peer.port:
447              alias: example_alias
448            network.protocol.name:
449              alias: example_alias
450            network.protocol.version:
451              alias: example_alias
452            network.transport:
453              alias: example_alias
454            network.type:
455              alias: example_alias
456            server.address:
457              alias: example_alias
458            server.port:
459              alias: example_alias
460            trace_id:
461              alias: example_alias
462            url.path:
463              alias: example_alias
464            url.query:
465              alias: example_alias
466            url.scheme:
467              alias: example_alias
468            user_agent.original:
469              alias: example_alias
470        http.server.response.body.size:
471          attributes:
472            baggage: null
473            dd.trace_id:
474              alias: example_alias
475            error.type:
476              alias: example_alias
477            http.request.body.size:
478              alias: example_alias
479            http.request.method:
480              alias: example_alias
481            http.response.body.size:
482              alias: example_alias
483            http.response.status_code:
484              alias: example_alias
485            http.route:
486              alias: example_alias
487            network.local.address:
488              alias: example_alias
489            network.local.port:
490              alias: example_alias
491            network.peer.address:
492              alias: example_alias
493            network.peer.port:
494              alias: example_alias
495            network.protocol.name:
496              alias: example_alias
497            network.protocol.version:
498              alias: example_alias
499            network.transport:
500              alias: example_alias
501            network.type:
502              alias: example_alias
503            server.address:
504              alias: example_alias
505            server.port:
506              alias: example_alias
507            trace_id:
508              alias: example_alias
509            url.path:
510              alias: example_alias
511            url.query:
512              alias: example_alias
513            url.scheme:
514              alias: example_alias
515            user_agent.original:
516              alias: example_alias
517      subgraph:
518        http.client.request.body.size:
519          attributes:
520            http.request.resend_count:
521              alias: example_alias
522            subgraph.graphql.document:
523              alias: example_alias
524            subgraph.graphql.operation.name:
525              alias: example_alias
526            subgraph.graphql.operation.type:
527              alias: example_alias
528            subgraph.name:
529              alias: example_alias
530        http.client.request.duration:
531          attributes:
532            http.request.resend_count:
533              alias: example_alias
534            subgraph.graphql.document:
535              alias: example_alias
536            subgraph.graphql.operation.name:
537              alias: example_alias
538            subgraph.graphql.operation.type:
539              alias: example_alias
540            subgraph.name:
541              alias: example_alias
542        http.client.response.body.size:
543          attributes:
544            http.request.resend_count:
545              alias: example_alias
546            subgraph.graphql.document:
547              alias: example_alias
548            subgraph.graphql.operation.name:
549              alias: example_alias
550            subgraph.graphql.operation.type:
551              alias: example_alias
552            subgraph.name:
553              alias: example_alias
554      supergraph:
555        cost.actual:
556          attributes:
557            cost.actual:
558              alias: example_alias
559            cost.delta:
560              alias: example_alias
561            cost.estimated:
562              alias: example_alias
563            cost.result:
564              alias: example_alias
565            graphql.document:
566              alias: example_alias
567            graphql.operation.name:
568              alias: example_alias
569            graphql.operation.type:
570              alias: example_alias
571        cost.delta:
572          attributes:
573            cost.actual:
574              alias: example_alias
575            cost.delta:
576              alias: example_alias
577            cost.estimated:
578              alias: example_alias
579            cost.result:
580              alias: example_alias
581            graphql.document:
582              alias: example_alias
583            graphql.operation.name:
584              alias: example_alias
585            graphql.operation.type:
586              alias: example_alias
587        cost.estimated:
588          attributes:
589            cost.actual:
590              alias: example_alias
591            cost.delta:
592              alias: example_alias
593            cost.estimated:
594              alias: example_alias
595            cost.result:
596              alias: example_alias
597            graphql.document:
598              alias: example_alias
599            graphql.operation.name:
600              alias: example_alias
601            graphql.operation.type:
602              alias: example_alias
603    spans:
604      connector:
605        attributes:
606          connector.http.method:
607            alias: example_alias
608          connector.source.name:
609            alias: example_alias
610          connector.url.template:
611            alias: example_alias
612          subgraph.name:
613            alias: example_alias
614      default_attribute_requirement_level: none
615      mode: deprecated
616      router:
617        attributes:
618          baggage: null
619          dd.trace_id:
620            alias: example_alias
621          error.type:
622            alias: example_alias
623          http.request.body.size:
624            alias: example_alias
625          http.request.method:
626            alias: example_alias
627          http.response.body.size:
628            alias: example_alias
629          http.response.status_code:
630            alias: example_alias
631          http.route:
632            alias: example_alias
633          network.local.address:
634            alias: example_alias
635          network.local.port:
636            alias: example_alias
637          network.peer.address:
638            alias: example_alias
639          network.peer.port:
640            alias: example_alias
641          network.protocol.name:
642            alias: example_alias
643          network.protocol.version:
644            alias: example_alias
645          network.transport:
646            alias: example_alias
647          network.type:
648            alias: example_alias
649          server.address:
650            alias: example_alias
651          server.port:
652            alias: example_alias
653          trace_id:
654            alias: example_alias
655          url.path:
656            alias: example_alias
657          url.query:
658            alias: example_alias
659          url.scheme:
660            alias: example_alias
661          user_agent.original:
662            alias: example_alias
663      subgraph:
664        attributes:
665          http.request.resend_count:
666            alias: example_alias
667          subgraph.graphql.document:
668            alias: example_alias
669          subgraph.graphql.operation.name:
670            alias: example_alias
671          subgraph.graphql.operation.type:
672            alias: example_alias
673          subgraph.name:
674            alias: example_alias
675      supergraph:
676        attributes:
677          cost.actual:
678            alias: example_alias
679          cost.delta:
680            alias: example_alias
681          cost.estimated:
682            alias: example_alias
683          cost.result:
684            alias: example_alias
685          graphql.document:
686            alias: example_alias
687          graphql.operation.name:
688            alias: example_alias
689          graphql.operation.type:
690            alias: example_alias

Enhanced operation signature normalizationSince 1.49.0

note
The router supports enhanced operation signature normalization in the following versions:

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 reportingSince 1.50.0

note
The router supports extended reference reporting in the following versions:
enterprise
This feature is only available with a GraphOS Enterprise plan. To compare GraphOS feature support across all plan types, see the pricing page.

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 reportingSince 2.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:

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    global_rate_limit:
8      capacity: 1
9      interval: 30s
10    timeout: null
11  connector:
12    all:
13      compression: gzip
14      dns_resolution_strategy: ipv4_only
15      experimental_http2: enable
16      global_rate_limit:
17        capacity: 1
18        interval: 30s
19      timeout: null
20    sources: {}
21  deduplicate_variables: null
22  router:
23    concurrency_limit: 0
24    global_rate_limit:
25      capacity: 1
26      interval: 30s
27    timeout: null
28  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.

Related topics
Feedback

Edit on GitHub

Ask Community