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        headers:
12        - name: example_name
13          value: example_value
14        issuer: example_issuer
15        poll_interval:
16          nanos: 0
17          secs: 60
18        url: http://service.example.com/url
19      on_error: Continue
20      sources:
21      - name: authorization
22        type: header
23        value_prefix: Bearer
24  subgraph:
25    all:
26      aws_sig_v4:
27        hardcoded:
28          access_key_id: example_access_key_id
29          assume_role:
30            external_id: example_external_id
31            role_arn: example_role_arn
32            session_name: example_session_name
33          region: example_region
34          secret_access_key: example_secret_access_key
35          service_name: example_service_name
36    subgraphs: {}

authorization

YAML
authorization
1authorization:
2  directives:
3    dry_run: false
4    enabled: true
5    errors:
6      log: true
7      response: errors
8    reject_unauthorized: false
9  require_authentication: false

batching

YAML
batching
1batching:
2  enabled: false
3  maximum_size: null
4  mode: batch_http_link
5  subgraph:
6    all:
7      enabled: false
8    subgraphs: {}

Learn more in query batching.

connectors

YAML
connectors
1connectors:
2  debug_extensions: false
3  expose_sources_in_context: false
4  max_requests_per_operation_per_source: null
5  sources: {}
6  subgraphs: {}

Learn more in Working with router for Apollo Connectors.

coprocessor

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

Enhanced operation signature normalization

Requires ≥ Router v1.49.0
note
The router supports enhanced operation signature normalization in the following versions:

Apollo's legacy operation signature algorithm removes information about certain fields, such as input objects and aliases. This removal means some operations may have the same normalized signature though they are distinct operations.

Enhanced normalization incorporates input types and aliases in signature generation. It also includes other improvements that make it more likely that two operations that only vary slightly have the same signature.

Configure enhanced operation signature normalization in router.yaml with the telemetry.apollo.signature_normalization_algorithm option:

YAML
router.yaml
1telemetry:
2  apollo:
3    signature_normalization_algorithm: enhanced # Default is legacy

Once you enable this configuration, operations with enhanced signatures might appear with different operation IDs than they did previously in GraphOS Studio.

Input types

Enhanced signatures include input object type shapes, while still redacting any actual values. Legacy signatures replace input object type with {}.

Given the following example operation:

GraphQL
query InlineInputTypeQuery {
  inputTypeQuery(
    input: {
      inputString: "foo"
      inputInt: 42
      inputBoolean: null
      nestedType: { someFloat: 4.2 }
      enumInput: SOME_VALUE_1
      nestedTypeList: [{ someFloat: 4.2, someNullableFloat: null }]
      listInput: [1, 2, 3]
    }
  ) {
    enumResponse
  }
}

The legacy normalization algorithm generates the following signature:

GraphQL
query InlineInputTypeQuery {
  inputTypeQuery(input: {}) {
    enumResponse
  }
}

The enhanced normalization algorithm generates the following signature:

GraphQL
query InlineInputTypeQuery {
  inputTypeQuery(
    input: {
      inputString: ""
      inputInt: 0
      inputBoolean: null
      nestedType: { someFloat: 0 }
      enumInput: SOME_VALUE_1
      nestedTypeList: [{ someFloat: 0, someNullableFloat: null }]
      listInput: []
    }
  ) {
    enumResponse
  }
}
Aliases

Enhanced signatures include any field aliases used in an operation. Legacy signatures remove aliases completely, meaning the signature may be invalid if the same field was used with multiple aliases.

Given the following example operation:

GraphQL
query AliasedQuery {
  noInputQuery {
    interfaceAlias1: interfaceResponse {
      sharedField
    }
    interfaceAlias2: interfaceResponse {
      ... on InterfaceImplementation1 {
        implementation1Field
      }
      ... on InterfaceImplementation2 {
        implementation2Field
      }
    }
    inputFieldAlias1: objectTypeWithInputField(boolInput: true) {
      stringField
    }
    inputFieldAlias2: objectTypeWithInputField(boolInput: false) {
      intField
    }
  }
}

The legacy normalization algorithm generates the following signature:

GraphQL
query AliasedQuery {
  noInputQuery {
    interfaceResponse {
      sharedField
    }
    interfaceResponse {
      ... on InterfaceImplementation1 {
        implementation1Field
      }
      ... on InterfaceImplementation2 {
        implementation2Field
      }
    }
    objectTypeWithInputField(boolInput: true) {
      stringField
    }
    objectTypeWithInputField(boolInput: false) {
      intField
    }
  }
}

The enhanced normalization algorithm generates the following signature:

GraphQL
query AliasedQuery {
  noInputQuery {
    interfaceAlias1: interfaceResponse {
      sharedField
    }
    interfaceAlias2: interfaceResponse {
      ... on InterfaceImplementation1 {
        implementation1Field
      }
      ... on InterfaceImplementation2 {
        implementation2Field
      }
    }
    inputFieldAlias1: objectTypeWithInputField(boolInput: true) {
      stringField
    }
    inputFieldAlias2: objectTypeWithInputField(boolInput: false) {
      intField
    }
  }
}

Extended reference reporting

Requires ≥ Router v1.50.0
note
The router supports extended reference reporting in the following versions:

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:

You can configure the router to report extended error information for improved diagnostics. Apollo's legacy error reporting doesn't include the service or error code, meaning you can't easily attribute errors to their root cause in GraphOS Studio.

Configure extended reference reporting in router.yaml with the telemetry.apollo.errors.preview_extended_error_metrics option like so:

YAML
router.yaml
1telemetry:
2  apollo:
3    errors:
4      preview_extended_error_metrics: enabled # Default is disabled

Learn more.

Configuration effect timing

Once you configure extended reference reporting, you can view enum value and input field usage alongside object field usage in GraphOS Studio for all subsequent operations.

Configuring extended reference reporting automatically turns on enhanced operation checks, though you won't see an immediate change in your operations check behavior.

This delay is because operation checks rely on historical operation data. To ensure sufficient data to distinguish between genuinely unused values and those simply not reported in legacy data, enhanced checks require some operations with extended reference reporting turned on.

Enhanced operation checks

Thanks to extended reference reporting, operation checks can more accurately flag issues for changes to enum values and input object fields. See the comparison table below for differences between standard operation checks based on legacy reference reporting and enhanced checks based on extended reference reporting.

Standard Check Behavior
(Legacy reference reporting)		Enhanced Check Behavior
(Extended reference reporting)
Enum value removal
Removing any enum values is considered a breaking change if any operations use the enum. Removing enum values is only a breaking change if historical operations use the specific enum value(s) that were removed.
Default argument changes for input object fields
Changing or removing a default argument is generally considered a breaking change, but changing or removing default values for input object fields isn't.Changing or removing default values for input object fields is considered a breaking change.You can configure checks to ignore default values changes.
Nullable input object field removal
Removing a nullable input object field is always considered a breaking change. Removing a nullable input object field is only considered a breaking change if the nullable field is present in historical operations. If the nullable field is always omitted in historical operations, its removal isn't considered a breaking change.
Changing nullable input object fields to non-nullable
Changing a nullable input object field to non-nullable is considered a breaking change. Changing a nullable input object field to non-nullable is only considered a breaking change if the field had a null value in historical operations. If the field was always a non-null value in historical operations, changing it to non-nullable isn't considered a breaking change.
note
You won't see an immediate change in checks behavior when you first turn on extended reference reporting. Learn more.

tls

YAML
tls
1tls:
2  connector:
3    all:
4      certificate_authorities: null
5      client_authentication:
6        certificate_chain: example_certificate_chain
7        key: example_key
8    sources: {}
9  subgraph:
10    all:
11      certificate_authorities: null
12      client_authentication:
13        certificate_chain: example_certificate_chain
14        key: example_key
15    subgraphs: {}
16  supergraph:
17    certificate: example_certificate
18    certificate_chain: example_certificate_chain
19    key: example_key

Learn more in TLS for the router.

traffic_shaping

YAML
traffic_shaping
1traffic_shaping:
2  all:
3    compression: gzip
4    deduplicate_query: false
5    dns_resolution_strategy: ipv4_only
6    experimental_http2: enable
7    global_rate_limit:
8      capacity: 1
9      interval: 30s
10    timeout: null
11  connector:
12    all:
13      compression: gzip
14      dns_resolution_strategy: ipv4_only
15      experimental_http2: enable
16      global_rate_limit:
17        capacity: 1
18        interval: 30s
19      timeout: null
20    sources: {}
21  deduplicate_variables: null
22  router:
23    concurrency_limit: 0
24    global_rate_limit:
25      capacity: 1
26      interval: 30s
27    timeout: null
28  subgraphs: {}

Learn more in Traffic Shaping.

YAML configuration utilities

Variable expansion

You can reference variables directly in your YAML config file. This is useful for referencing secrets without including them in the file.

Currently, the router supports expansion of environment variables and file paths. Corresponding variables are prefixed with env. and file., respectively.

The router uses Unix-style expansion. Here are some examples:

  • ${env.ENV_VAR_NAME} expands to the value of environment variable ENV_VAR_NAME.

  • ${env.ENV_VAR_NAME:-some_default} expands to the value of environment variable ENV_VAR_NAME, or falls back to the value some_default if the environment variable is not defined.

  • ${file.a.txt} expands to the contents of the file a.txt.

  • ${file.a.txt:-some_default} expands to the contents of the file a.txt, or falls back to the value some_default if the file does not exist.

Variable expansions are valid only for YAML values, not keys.

Reusing configurations with YAML aliases

You can reuse parts of your configuration file in multiple places using standard YAML aliasing syntax:

YAML
router.yaml
1headers:
2  subgraphs:
3    products:
4      request:
5        - insert: &insert_custom_header
6            name: "custom-header"
7            value: "something"
8    reviews:
9      request:
10        - insert: *insert_custom_header

Here, the name and value entries under &insert_custom_header are reused under *insert_custom_header.

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

Related topics
Feedback

Edit on GitHub

Ask Community