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

Learn more in File Uploads.

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

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

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

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

Telemetry Data

Metrics

Traces

Usage Guides

Subgraph Observability

Client Observability

Telemetry Exporters

Metrics Exporters

Log Exporters

Trace Exporters

APM Guides

Datadog

Connecting to Datadog

Datadog Agent

New Relic

Prometheus

Zipkin

Jaeger

Dynatrace

AWS Lattice

Telemetry Data

Metrics

Traces

Usage Guides

Subgraph Observability

Client Observability

Telemetry Exporters

Metrics Exporters

Log Exporters

Trace Exporters

APM Guides

Datadog

Connecting to Datadog

Datadog Agent

New Relic

Prometheus

Zipkin

Jaeger

Dynatrace

AWS Lattice

Router YAML Configuration Reference

YAML configuration properties

Example YAML with all properties

Properties

apq

authentication

`apq`

`authentication`