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

Properties

apq

YAML
apq
1apq:
2  enabled: true
3  router:
4    cache:
5      in_memory:
6        limit: 1
7      redis:
8        namespace: example_namespace
9        password: example_password
10        pool_size: 1
11        required_to_start: false
12        reset_ttl: true
13        timeout: null
14        tls:
15          certificate_authorities: null
16          client_authentication:
17            certificate_chain: example_certificate_chain
18            key: example_key
19        ttl: null
20        urls:
21        - http://example.com/urls_item
22        username: example_username
23  subgraph:
24    all:
25      enabled: false
26    subgraphs: {}

Learn more in Automatic Persisted Queries.

authentication

authentication YAML snippet
YAML
authentication
1authentication:
2  connector:
3    sources: {}
4  router:
5    jwt:
6      header_name: authorization
7      header_value_prefix: Bearer
8      ignore_other_prefixes: false
9      jwks:
10      - algorithms: null
11        allow_missing_exp: false
12        headers:
13        - name: example_name
14          value: example_value
15        issuer: example_issuer
16        poll_interval:
17          nanos: 0
18          secs: 60
19        url: http://service.example.com/url
20      on_error: Continue
21      sources:
22      - name: authorization
23        type: header
24        value_prefix: Bearer
25  subgraph:
26    all:
27      aws_sig_v4:
28        hardcoded:
29          access_key_id: example_access_key_id
30          assume_role:
31            external_id: example_external_id
32            role_arn: example_role_arn
33            session_name: example_session_name
34          region: example_region
35          secret_access_key: example_secret_access_key
36          service_name: example_service_name
37    subgraphs: {}

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: {} # Deprecated. Use `sources` instead.

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: none
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: none
25        headers: false
26        service_name: false
27        status_code: false
28  execution:
29    request:
30      body: false
31      context: none
32      headers: false
33      method: false
34      query_plan: false
35      sdl: false
36    response:
37      body: false
38      context: none
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: none
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: none
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: none
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: none
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: none
97      headers: false
98      method: false
99      sdl: false
100    response:
101      body: false
102      condition:
103        eq:
104        - false
105        - false
106      context: none
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  connector:
3    all:
4      http_max_response_size: null
5    sources: {}
6  router:
7    http1_max_request_buf_size: null
8    http1_max_request_headers: null
9    http2_max_headers_list_bytes: null
10    http_max_request_bytes: 2000000
11    introspection_max_depth: true
12    max_aliases: null
13    max_depth: null
14    max_height: null
15    max_root_fields: null
16    max_recursive_selections: 10000000
17    parser_max_recursion: 500
18    parser_max_tokens: 15000
19    warn_only: false
20  subgraph:
21    all:
22      http_max_response_size: null
23    subgraphs: {}

Learn more in Request Limits.

override_subgraph_url

YAML
override_subgraph_url
1override_subgraph_url: {}

By default, the router obtains the routing URL for each of your subgraphs from the composed supergraph schema you provide it. In most cases, no additional configuration is required. The URL can use HTTP and HTTPS for network access to subgraph, or have the following shape for Unix sockets usage: unix:///path/to/subgraph.sock

note
Unix socket paths should be absolute (starting with /). The URL format is unix:// followed by the absolute path, resulting in three slashes: unix:///var/run/subgraph.sock.

Because .sock is not required as a file extension, the router cannot determine if a path is appended to the base URL. Specify a custom HTTP path using the path query parameter:

YAML
1override_subgraph_url:
2  my_subgraph: "unix:///tmp/subgraph.sock?path=/graphql/v1"

This configuration also applies to subgraph URLs defined in your supergraph schema (using the url argument of the @join__graph directive).

However, if you do need to override a particular subgraph's routing URL (for example, to handle changing network topography), you can do so with the override_subgraph_url option:

YAML
1override_subgraph_url:
2  organizations: http://localhost:8080
3  accounts: "${env.ACCOUNTS_SUBGRAPH_HOST_URL}"

In this example, the organizations subgraph URL is overridden to point to http://localhost:8080, and the accounts subgraph URL is overridden to point to a new URL using variable expansion. The URL specified in the supergraph schema is ignored.

Any subgraphs that are omitted from override_subgraph_url continue to use the routing URL specified in the supergraph schema.

If you need to override the subgraph URL at runtime on a per-request basis, you can use request customizations in the SubgraphService layer.

persisted_queries

YAML
persisted_queries
1persisted_queries:
2  enabled: false
3  experimental_prewarm_query_plan_cache:
4    on_reload: true
5    on_startup: false
6  hot_reload: false
7  local_manifests: null
8  log_unknown: false
9  safelist:
10    enabled: false
11    require_id: 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.

response_cache

response_cache YAML snippet
YAML
response_cache.router.yaml
1response_cache:
2  enabled: false
3  debug: false
4  include_cache_control_header_on_router_response: true # set to false to suppress Cache-Control header on client responses
5  private_queries_buffer_size: 2048
6  invalidation:
7    listen: 127.0.0.1:4000
8    path: /invalidation
9  subgraph:
10    all:
11      enabled: true
12      ttl: 30s
13      private_id: null
14      redis:
15        urls:
16        - redis://127.0.0.1:6379
17        username: example_username
18        password: example_password
19        fetch_timeout: 150ms
20        insert_timeout: 500ms
21        invalidate_timeout: 1s
22        maintenance_timeout: 500ms
23        namespace: example_namespace
24        tls:
25          certificate_authorities: null
26          client_authentication:
27            certificate_chain: example_certificate_chain
28            key: example_key
29        required_to_start: false
30        pool_size: 5
31        metrics_interval: 1s
32      invalidation:
33        enabled: false
34        shared_key: ''
35    subgraphs: {}

When using Redis as the cache backend, the router emits additional Redis-specific metrics to help monitor cache performance:

  • Connection metrics: Track Redis connection establishment and health

  • Command metrics: Monitor Redis command execution, queue length, and redelivery counts

  • Performance metrics: Measure average latency, network latency, and request/response sizes

  • Operational metrics: Help identify connection issues, network problems, or performance bottlenecks

These metrics use the kind attribute to distinguish between different Redis cache uses (e.g., response). For the complete list of Redis metrics and their descriptions, see the Redis Cache metrics documentation.

Learn more in Response Caching.

preview_file_uploads

YAML
preview_file_uploads
1preview_file_uploads:
2  enabled: false
3  protocols:
4    multipart:
5      enabled: true
6      limits:
7        max_file_size: example_max_file_size
8        max_files: 0
9        operation_body_timeout: 30s
10      mode: stream

Learn more in File Uploads.

reload

YAML
router.yaml
1reload:
2  # Maximum retry attempts after a failed reload.
3  # 0 disables retries. null allows unlimited retries. Default: 5
4  max_retries: 5
5
6  # Base delay between retries. Up to 25% jitter is added automatically
7  # Default: 10s
8  retry_delay: 10s

Learn more about configuring reload retries.

rhai

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

Learn more in Rhai customization for router.

sandbox

YAML
sandbox
1sandbox:
2  enabled: false

Apollo Sandbox is a GraphQL development environment. It runs a graph via introspection queries on the router's supergrpah schema, and it provides an IDE for making queries to the graph.

Running Sandbox in router requires configuring sandbox.enabled, supergraph.instrospection, and homepage.enabled:

YAML
router.yaml
1sandbox:
2  enabled: true
3
4# Sandbox uses introspection to obtain your router's schema.
5supergraph:
6  introspection: true
7
8# Sandbox requires the default landing page to be disabled.
9homepage:
10  enabled: false
caution
Do not enable Sandbox in production. Sandbox requires enabling introspection, which is strongly discouraged in production environments.

Learn more in Apollo Sandbox.

server

YAML
server
1server:
2  http:
3    header_read_timeout: 30s
4    tls_handshake_timeout: 30s

Header Read Timeout

The header read timeout is the amount of time the Router will wait to receive the complete request headers from a client before timing out. It applies both when the connection is fully idle and when a request has been started but sending the headers has not been completed.

By default, the header read timeout is set to 10 seconds. A longer timeout can be configured using the server.http.header_read_timeout configuration option.

TLS handshake timeout

The TLS handshake timeout determines how long the router waits to complete a TLS handshake with a client.

The default timeout is ten seconds. You can configure the server.http.tls_handshake_timeout option to change this duration.

subscription

YAML
subscription
1subscription:
2  enable_deduplication: true
3  enabled: true
4  max_lifetime: null
5  max_opened_subscriptions: null
6  mode:
7    callback:
8      heartbeat_interval: disabled
9      listen: example_listen
10      path: example_path
11      public_url: http://service.example.com/public_url
12      subgraphs: []
13    passthrough:
14      all:
15        heartbeat_interval: disabled
16        path: null
17        protocol: graphql_ws
18      subgraphs: {}
19  queue_capacity: null

Learn more in Subscriptions.

supergraph

supergraph YAML snippet
YAML
supergraph
1supergraph:
2  defer_support: true
3  early_cancel: false
4  experimental_log_on_broken_pipe: false
5  generate_query_fragments: true
6  introspection: false
7  listen: example_listen
8  path: /
9  redact_query_validation_errors: false
10  query_planning:
11    cache:
12      in_memory:
13        limit: 1
14      redis:
15        namespace: example_namespace
16        password: example_password
17        pool_size: 1
18        required_to_start: false
19        reset_ttl: true
20        timeout: null
21        tls:
22          certificate_authorities: null
23          client_authentication:
24            certificate_chain: example_certificate_chain
25            key: example_key
26        ttl:
27          nanos: 0
28          secs: 2592000
29        urls:
30        - http://example.com/urls_item
31        username: example_username
32    experimental_paths_limit: null
33    experimental_plans_limit: null
34    warmed_up_queries: null
35  strict_variable_validation: enforce

Supergraph listen address

As the gateway and single endpoint to your supergraph, an Apollo Router has a socket address and port that it listens for client requests. This listen address is configurable in YAML as supergraph.listen.

By default, the router starts an HTTP server that listens on 127.0.0.1:4000. You can specify a different address by setting supergraph.listen for IPv4, IPv6, or Unix sockets.

IPv4
YAML
router.yaml
1supergraph:
2  # The socket address and port to listen on (default: 127.0.0.1:400)
3  listen: 127.0.0.1:4000
IPv6
YAML
router.yaml
1supergraph:
2  # The socket address and port to listen on. (default: [::1]:4000)
3  # Note that this must be quoted to avoid interpretation as an array in YAML.
4  listen: "[::1]:4000"
Unix socket
YAML
router_unix.yaml
1supergraph:
2  # Absolute path to a Unix socket
3  listen: /tmp/router.sock
note
Listening on a Unix socket is not supported on Windows.

Supergraph endpoint path

The path of the HTTP endpoint of the supergraph that the router runs is configured by supergraph.path.

By default, the router starts an HTTP server that exposes a POST/GET endpoint at path /.

YAML
router.yaml
1supergraph:
2  # The path for GraphQL execution
3  # (Defaults to /)
4  path: /graphql

The path must start with /.

A path can contain parameters and wildcards:

  • /{parameter} matches a single segment. For example:

    • /abc/{my_param}/def matches /abc/1/def and /abc/whatever/def, but it doesn't match /abc/1/2/def or /abc/def

  • /{*parameter} matches all segments in the rest of a path. For example:

    • /abc/{*wildcard} matches /abc/1/def and /abc/w/h/a/t/e/v/e/r, but it doesn't match /abc/ or /not_abc_at_all

note
  • Both parameters and wildcards require a name, even though you can’t use those names anywhere.
  • The router doesn't support wildcards in the middle of a path (e.g., /{*wild}/graphql). Instead, use a path parameter (e.g., /{parameter}/graphql).

The router normalizes trailing slashes automatically. For example, if you configure the path as /graphql, the router accepts requests to both /graphql and /graphql/. This applies regardless of whether your configured path includes a trailing slash.

Introspection

In GraphQL, introspection queries are used during development to learn about a GraphQL API's schema. The router can resolve introspection queries, based on the configuration of supergraph.introspection.

By default, the router doesn't resolve introspection queries.

To enable introspection queries during development, set the supergraph.introspection flag:

YAML
router.yaml
1# Do not enable introspection in production!
2supergraph:
3  introspection: true
Introspection recursion limit

The schema-introspection schema is recursive: a client can query the fields of the types of some other fields, and so on arbitrarily deep. This can produce responses that grow much faster than the size of the request.

To prevent this, the router is configured by default to not execute introspection queries that nest list fields that are too deep, instead returning an error. The criteria matches MaxIntrospectionDepthRule in graphql-js, and it may change in future versions.

In case the router rejects legitimate queries, you can disable the limit by setting the limits.introspection_max_depth flag:

YAML
router.yaml
1# Do not enable introspection in production!
2supergraph:
3  introspection: true
4limits:
5  router:
6    introspection_max_depth: false

Redacting query validation errors

Query validation errors might reveal information about your schema structure, such as field names, types, and required arguments. Although this is not typically a significant security concern (especially with persisted queries), you can redact these error details in production environments.

Apollo Router returns detailed validation error messages by default. To redact validation errors and return a generic error message, set the supergraph.redact_query_validation_errors flag:

YAML
router.yaml
1supergraph:
2  redact_query_validation_errors: true

When you enable this setting, Apollo Router replaces query validation errors with a single generic error:

JSON
1{
2  "message": "invalid query",
3  "extensions": {
4    "code": "UNKNOWN_ERROR"
5  }
6}
note
Enabling this option will make debugging more difficult, as clients won't receive specific information about what's wrong with their queries. Consider enabling it only in production environments where schema details should remain private.

Early cancel

Up until Apollo Router Core v1.43.1, when the client closed the connection without waiting for the response, the entire request was cancelled and did not go through the entire pipeline. Since this causes issues with request monitoring, the router introduced a new behavior in 1.43.1. Now, the entire pipeline is executed if the request is detected as cancelled, but subgraph requests are not actually done. The response will be reported with the 499 status code, but not actually sent to the client.

To go back to the previous behavior of immediately cancelling the request, the following configuration can be used for supergraph.early_cancel:

YAML
1supergraph:
2  early_cancel: true

Additionally, since v1.43.1, the router can show a log when it detects that the client canceled the request. This log can be activated with:

YAML
router.yaml
1supergraph:
2  experimental_log_on_broken_pipe: true

Connection shutdown timeout

When the Router schema or configuration updates all connections must be closed for resources to be freed. To ensure that long-lived connections do not hang on to resources, a maximum graceful shutdown timeout can be configured with supergraph.connection_shutdown_timeout:

YAML
router.yaml
1supergraph:
2  connection_shutdown_timeout: 60s

The default value is 60 seconds.

Note that if early_cancel is false (default), then requests in progress will still hold onto pipeline resources. In that case, traffic shaping request timeouts should be used to prevent long-running requests:

YAML
router.yaml
1traffic_shaping:
2  router:
3    timeout: 60s

Automatic fragment generation

By default, the router compresses subgraph requests by generating fragment definitions based on the shape of the subgraph operation. In many cases this significantly reduces the size of the query sent to subgraphs.

Opt out of this behavior by specifying supergraph.generate_query_fragments:

YAML
1supergraph:
2  generate_query_fragments: false

Variable validation modes

By default, the router validates input variables strictly. It validates each input object value against its type definition, and any unknown fields result in a request error.

YAML
1supergraph:
2  strict_variable_validation: enforce

If your implementation requires unknown fields on a defined type, you can opt out of stricter validation by specifying strict_variable_validation: measure. In this case, the router will not error when encountering unknown fields, but will log the field for reference.

telemetry

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

Learn more in Traffic Shaping.

YAML configuration utilities

Variable expansion

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

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

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

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

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

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

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

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

Reusing configurations with YAML aliases

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

YAML
router.yaml
1headers:
2  subgraphs:
3    products:
4      request:
5        operations:
6          - insert: &insert_custom_header
7              name: "custom-header"
8              value: "something"
9    reviews:
10      request:
11        operations:
12          - 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