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    otlp_tracing_sampler: 0.0
362    send_headers:
363      only:
364        - example_only_item
365    send_variable_values:
366      only:
367        - example_only_item
368    signature_normalization_algorithm: legacy
369  exporters:
370    logging:
371      common:
372        resource: {}
373        service_name: null
374        service_namespace: null
375      stdout:
376        enabled: true
377        format:
378          json:
379            display_current_span: false
380            display_filename: false
381            display_level: true
382            display_line_number: false
383            display_resource: true
384            display_span_id: true
385            display_span_list: true
386            display_target: true
387            display_thread_id: false
388            display_thread_name: false
389            display_timestamp: true
390            display_trace_id: hexadecimal
391            span_attributes: []
392        rate_limit:
393          capacity: 1
394          enabled: false
395          interval:
396            secs: 1
397            nanos: 0
398        tty_format:
399          json:
400            display_current_span: false
401            display_filename: false
402            display_level: true
403            display_line_number: false
404            display_resource: true
405            display_span_id: true
406            display_span_list: true
407            display_target: true
408            display_thread_id: false
409            display_thread_name: false
410            display_timestamp: true
411            display_trace_id: hexadecimal
412            span_attributes: []
413    metrics:
414      common:
415        buckets:
416          - 0.001
417          - 0.005
418          - 0.015
419          - 0.05
420          - 0.1
421          - 0.2
422          - 0.3
423          - 0.4
424          - 0.5
425          - 1.0
426          - 5.0
427          - 10.0
428        resource: {}
429        service_name: null
430        service_namespace: null
431        views:
432          - aggregation:
433              histogram:
434                buckets:
435                  - 0.0
436            allowed_attribute_keys:
437              - example_allowed_attribute_keys_item
438            description: example_description
439            name: example_name
440            unit: example_unit
441      otlp:
442        batch_processor:
443          max_concurrent_exports: 1
444          max_export_batch_size: 512
445          max_export_timeout:
446            secs: 30
447            nanos: 0
448          max_queue_size: 2048
449          scheduled_delay:
450            secs: 5
451            nanos: 0
452        enabled: false
453        endpoint: example_endpoint
454        grpc:
455          ca: null
456          cert: null
457          domain_name: null
458          key: null
459          metadata: {}
460        http:
461          headers: {}
462        protocol: grpc
463        temporality: cumulative
464      prometheus:
465        enabled: false
466        listen: example_listen
467        path: /metrics
468    tracing:
469      common:
470        max_attributes_per_event: 128
471        max_attributes_per_link: 128
472        max_attributes_per_span: 128
473        max_events_per_span: 128
474        max_links_per_span: 128
475        parent_based_sampler: true
476        preview_datadog_agent_sampling: null
477        resource: {}
478        sampler: 0.0
479        service_name: null
480        service_namespace: null
481      datadog:
482        batch_processor:
483          max_concurrent_exports: 1
484          max_export_batch_size: 512
485          max_export_timeout:
486            secs: 30
487            nanos: 0
488          max_queue_size: 2048
489          scheduled_delay:
490            secs: 5
491            nanos: 0
492        enable_span_mapping: true
493        enabled: false
494        endpoint: example_endpoint
495        fixed_span_names: true
496        resource_mapping: {}
497        span_metrics:
498          parse_query: true
499          connect: true
500          execution: true
501          http_request: true
502          request: true
503          query_planning: true
504          connect_request: true
505          subgraph: true
506          router: true
507          supergraph: true
508          subgraph_request: true
509      experimental_response_trace_id:
510        enabled: false
511        format: hexadecimal
512        header_name: example_header_name
513      otlp:
514        batch_processor:
515          max_concurrent_exports: 1
516          max_export_batch_size: 512
517          max_export_timeout:
518            secs: 30
519            nanos: 0
520          max_queue_size: 2048
521          scheduled_delay:
522            secs: 5
523            nanos: 0
524        enabled: false
525        endpoint: example_endpoint
526        grpc:
527          ca: null
528          cert: null
529          domain_name: null
530          key: null
531          metadata: {}
532        http:
533          headers: {}
534        protocol: grpc
535        temporality: cumulative
536      propagation:
537        aws_xray: false
538        baggage: false
539        datadog: false
540        jaeger: false
541        request:
542          format: hexadecimal
543          header_name: example_header_name
544        trace_context: false
545        zipkin: false
546      zipkin:
547        batch_processor:
548          max_concurrent_exports: 1
549          max_export_batch_size: 512
550          max_export_timeout:
551            secs: 30
552            nanos: 0
553          max_queue_size: 2048
554          scheduled_delay:
555            secs: 5
556            nanos: 0
557        enabled: false
558        endpoint: example_endpoint
559  instrumentation:
560    events:
561      connector:
562        error:
563          condition:
564            eq:
565              - false
566              - false
567          level: info
568        request:
569          condition:
570            eq:
571              - false
572              - false
573          level: info
574        response:
575          condition:
576            eq:
577              - false
578              - false
579          level: info
580      router:
581        error:
582          condition:
583            eq:
584              - false
585              - false
586          level: info
587        request:
588          condition:
589            eq:
590              - false
591              - false
592          level: info
593        response:
594          condition:
595            eq:
596              - false
597              - false
598          level: info
599      subgraph:
600        error:
601          condition:
602            eq:
603              - false
604              - false
605          level: info
606        request:
607          condition:
608            eq:
609              - false
610              - false
611          level: info
612        response:
613          condition:
614            eq:
615              - false
616              - false
617          level: info
618      supergraph:
619        error:
620          condition:
621            eq:
622              - false
623              - false
624          level: info
625        request:
626          condition:
627            eq:
628              - false
629              - false
630          level: info
631        response:
632          condition:
633            eq:
634              - false
635              - false
636          level: info
637    instruments:
638      cache:
639        apollo.router.response.cache:
640          attributes:
641            graphql.type.name:
642              alias: example_alias
643      connector:
644        http.client.request.body.size:
645          attributes:
646            connector.http.method:
647              alias: example_alias
648            connector.source.name:
649              alias: example_alias
650            connector.url.template:
651              alias: example_alias
652            subgraph.name:
653              alias: example_alias
654        http.client.request.duration:
655          attributes:
656            connector.http.method:
657              alias: example_alias
658            connector.source.name:
659              alias: example_alias
660            connector.url.template:
661              alias: example_alias
662            subgraph.name:
663              alias: example_alias
664        http.client.response.body.size:
665          attributes:
666            connector.http.method:
667              alias: example_alias
668            connector.source.name:
669              alias: example_alias
670            connector.url.template:
671              alias: example_alias
672            subgraph.name:
673              alias: example_alias
674      default_requirement_level: none
675      graphql:
676        field.execution:
677          attributes:
678            graphql.field.name:
679              alias: example_alias
680            graphql.field.type:
681              alias: example_alias
682            graphql.list.length:
683              alias: example_alias
684            graphql.operation.name:
685              alias: example_alias
686            graphql.type.name:
687              alias: example_alias
688        list.length:
689          attributes:
690            graphql.field.name:
691              alias: example_alias
692            graphql.field.type:
693              alias: example_alias
694            graphql.list.length:
695              alias: example_alias
696            graphql.operation.name:
697              alias: example_alias
698            graphql.type.name:
699              alias: example_alias
700      router:
701        http.server.active_requests:
702          attributes:
703            http.request.method: false
704            server.address: false
705            server.port: false
706            url.scheme: false
707        http.server.request.body.size:
708          attributes:
709            baggage: null
710            dd.trace_id:
711              alias: example_alias
712            error.type:
713              alias: example_alias
714            http.request.body.size:
715              alias: example_alias
716            http.request.method:
717              alias: example_alias
718            http.response.body.size:
719              alias: example_alias
720            http.response.status_code:
721              alias: example_alias
722            http.route:
723              alias: example_alias
724            network.local.address:
725              alias: example_alias
726            network.local.port:
727              alias: example_alias
728            network.peer.address:
729              alias: example_alias
730            network.peer.port:
731              alias: example_alias
732            network.protocol.name:
733              alias: example_alias
734            network.protocol.version:
735              alias: example_alias
736            network.transport:
737              alias: example_alias
738            network.type:
739              alias: example_alias
740            server.address:
741              alias: example_alias
742            server.port:
743              alias: example_alias
744            trace_id:
745              alias: example_alias
746            url.path:
747              alias: example_alias
748            url.query:
749              alias: example_alias
750            url.scheme:
751              alias: example_alias
752            user_agent.original:
753              alias: example_alias
754        http.server.request.duration:
755          attributes:
756            baggage: null
757            dd.trace_id:
758              alias: example_alias
759            error.type:
760              alias: example_alias
761            http.request.body.size:
762              alias: example_alias
763            http.request.method:
764              alias: example_alias
765            http.response.body.size:
766              alias: example_alias
767            http.response.status_code:
768              alias: example_alias
769            http.route:
770              alias: example_alias
771            network.local.address:
772              alias: example_alias
773            network.local.port:
774              alias: example_alias
775            network.peer.address:
776              alias: example_alias
777            network.peer.port:
778              alias: example_alias
779            network.protocol.name:
780              alias: example_alias
781            network.protocol.version:
782              alias: example_alias
783            network.transport:
784              alias: example_alias
785            network.type:
786              alias: example_alias
787            server.address:
788              alias: example_alias
789            server.port:
790              alias: example_alias
791            trace_id:
792              alias: example_alias
793            url.path:
794              alias: example_alias
795            url.query:
796              alias: example_alias
797            url.scheme:
798              alias: example_alias
799            user_agent.original:
800              alias: example_alias
801        http.server.response.body.size:
802          attributes:
803            baggage: null
804            dd.trace_id:
805              alias: example_alias
806            error.type:
807              alias: example_alias
808            http.request.body.size:
809              alias: example_alias
810            http.request.method:
811              alias: example_alias
812            http.response.body.size:
813              alias: example_alias
814            http.response.status_code:
815              alias: example_alias
816            http.route:
817              alias: example_alias
818            network.local.address:
819              alias: example_alias
820            network.local.port:
821              alias: example_alias
822            network.peer.address:
823              alias: example_alias
824            network.peer.port:
825              alias: example_alias
826            network.protocol.name:
827              alias: example_alias
828            network.protocol.version:
829              alias: example_alias
830            network.transport:
831              alias: example_alias
832            network.type:
833              alias: example_alias
834            server.address:
835              alias: example_alias
836            server.port:
837              alias: example_alias
838            trace_id:
839              alias: example_alias
840            url.path:
841              alias: example_alias
842            url.query:
843              alias: example_alias
844            url.scheme:
845              alias: example_alias
846            user_agent.original:
847              alias: example_alias
848      subgraph:
849        http.client.request.body.size:
850          attributes:
851            http.request.resend_count:
852              alias: example_alias
853            subgraph.graphql.document:
854              alias: example_alias
855            subgraph.graphql.operation.name:
856              alias: example_alias
857            subgraph.graphql.operation.type:
858              alias: example_alias
859            subgraph.name:
860              alias: example_alias
861        http.client.request.duration:
862          attributes:
863            http.request.resend_count:
864              alias: example_alias
865            subgraph.graphql.document:
866              alias: example_alias
867            subgraph.graphql.operation.name:
868              alias: example_alias
869            subgraph.graphql.operation.type:
870              alias: example_alias
871            subgraph.name:
872              alias: example_alias
873        http.client.response.body.size:
874          attributes:
875            http.request.resend_count:
876              alias: example_alias
877            subgraph.graphql.document:
878              alias: example_alias
879            subgraph.graphql.operation.name:
880              alias: example_alias
881            subgraph.graphql.operation.type:
882              alias: example_alias
883            subgraph.name:
884              alias: example_alias
885      supergraph:
886        cost.actual:
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.delta:
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        cost.estimated:
919          attributes:
920            cost.actual:
921              alias: example_alias
922            cost.delta:
923              alias: example_alias
924            cost.estimated:
925              alias: example_alias
926            cost.result:
927              alias: example_alias
928            graphql.document:
929              alias: example_alias
930            graphql.operation.name:
931              alias: example_alias
932            graphql.operation.type:
933              alias: example_alias
934    spans:
935      connector:
936        attributes:
937          connector.http.method:
938            alias: example_alias
939          connector.source.name:
940            alias: example_alias
941          connector.url.template:
942            alias: example_alias
943          subgraph.name:
944            alias: example_alias
945      default_attribute_requirement_level: none
946      router:
947        attributes:
948          baggage: null
949          dd.trace_id:
950            alias: example_alias
951          error.type:
952            alias: example_alias
953          http.request.body.size:
954            alias: example_alias
955          http.request.method:
956            alias: example_alias
957          http.response.body.size:
958            alias: example_alias
959          http.response.status_code:
960            alias: example_alias
961          http.route:
962            alias: example_alias
963          network.local.address:
964            alias: example_alias
965          network.local.port:
966            alias: example_alias
967          network.peer.address:
968            alias: example_alias
969          network.peer.port:
970            alias: example_alias
971          network.protocol.name:
972            alias: example_alias
973          network.protocol.version:
974            alias: example_alias
975          network.transport:
976            alias: example_alias
977          network.type:
978            alias: example_alias
979          server.address:
980            alias: example_alias
981          server.port:
982            alias: example_alias
983          trace_id:
984            alias: example_alias
985          url.path:
986            alias: example_alias
987          url.query:
988            alias: example_alias
989          url.scheme:
990            alias: example_alias
991          user_agent.original:
992            alias: example_alias
993      subgraph:
994        attributes:
995          http.request.resend_count:
996            alias: example_alias
997          subgraph.graphql.document:
998            alias: example_alias
999          subgraph.graphql.operation.name:
1000            alias: example_alias
1001          subgraph.graphql.operation.type:
1002            alias: example_alias
1003          subgraph.name:
1004            alias: example_alias
1005      supergraph:
1006        attributes:
1007          cost.actual:
1008            alias: example_alias
1009          cost.delta:
1010            alias: example_alias
1011          cost.estimated:
1012            alias: example_alias
1013          cost.result:
1014            alias: example_alias
1015          graphql.document:
1016            alias: example_alias
1017          graphql.operation.name:
1018            alias: example_alias
1019          graphql.operation.type:
1020            alias: example_alias
1021tls:
1022  connector:
1023    all:
1024      certificate_authorities: null
1025      client_authentication:
1026        certificate_chain: example_certificate_chain
1027        key: example_key
1028    sources: {}
1029  subgraph:
1030    all:
1031      certificate_authorities: null
1032      client_authentication:
1033        certificate_chain: example_certificate_chain
1034        key: example_key
1035    subgraphs: {}
1036  supergraph:
1037    certificate: example_certificate
1038    certificate_chain: example_certificate_chain
1039    key: example_key
1040traffic_shaping:
1041  all:
1042    compression: gzip
1043    deduplicate_query: false
1044    dns_resolution_strategy: ipv4_only
1045    experimental_http2: enable
1046    global_rate_limit:
1047      capacity: 1
1048      interval: 30s
1049    timeout: null
1050  connector:
1051    all:
1052      compression: gzip
1053      dns_resolution_strategy: ipv4_only
1054      experimental_http2: enable
1055      global_rate_limit:
1056        capacity: 1
1057        interval: 30s
1058      timeout: null
1059    sources: {}
1060  deduplicate_variables: null
1061  router:
1062    concurrency_limit: 0
1063    global_rate_limit:
1064      capacity: 1
1065      interval: 30s
1066    timeout: null
1067  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    otlp_tracing_sampler: 0.0
38    send_headers:
39      only:
40      - example_only_item
41    send_variable_values:
42      only:
43      - example_only_item
44    signature_normalization_algorithm: enhanced
45  exporters:
46    logging:
47      common:
48        resource: {}
49        service_name: null
50        service_namespace: null
51      stdout:
52        enabled: true
53        format:
54          json:
55            display_current_span: false
56            display_filename: false
57            display_level: true
58            display_line_number: false
59            display_resource: true
60            display_span_id: true
61            display_span_list: true
62            display_target: true
63            display_thread_id: false
64            display_thread_name: false
65            display_timestamp: true
66            display_trace_id: hexadecimal
67            span_attributes: []
68            expand_json_string_values: false
69        rate_limit:
70          capacity: 1
71          enabled: false
72          interval:
73            nanos: 0
74            secs: 1
75        tty_format:
76          json:
77            display_current_span: false
78            display_filename: false
79            display_level: true
80            display_line_number: false
81            display_resource: true
82            display_span_id: true
83            display_span_list: true
84            display_target: true
85            display_thread_id: false
86            display_thread_name: false
87            display_timestamp: true
88            display_trace_id: hexadecimal
89            span_attributes: []
90            expand_json_string_values: false
91    metrics:
92      common:
93        buckets:
94        - 0.001
95        - 0.005
96        - 0.015
97        - 0.05
98        - 0.1
99        - 0.2
100        - 0.3
101        - 0.4
102        - 0.5
103        - 1.0
104        - 5.0
105        - 10.0
106        resource: {}
107        service_name: null
108        service_namespace: null
109        views:
110        - aggregation:
111            histogram:
112              buckets:
113              - 0.0
114          allowed_attribute_keys:
115          - example_allowed_attribute_keys_item
116          description: example_description
117          name: example_name
118          rename: example_rename
119          unit: example_unit
120      otlp:
121        batch_processor:
122          max_concurrent_exports: 1
123          max_export_batch_size: 512
124          max_export_timeout:
125            nanos: 0
126            secs: 30
127          max_queue_size: 2048
128          scheduled_delay:
129            nanos: 0
130            secs: 5
131        enabled: false
132        endpoint: example_endpoint
133        grpc:
134          ca: null
135          cert: null
136          domain_name: null
137          key: null
138          metadata: {}
139        http:
140          headers: {}
141        protocol: grpc
142        temporality: cumulative
143      prometheus:
144        enabled: false
145        listen: example_listen
146        path: /metrics
147    tracing:
148      common:
149        max_attributes_per_event: 128
150        max_attributes_per_link: 128
151        max_attributes_per_span: 128
152        max_events_per_span: 128
153        max_links_per_span: 128
154        parent_based_sampler: true
155        preview_datadog_agent_sampling: null
156        resource: {}
157        sampler: 0.0
158        service_name: null
159        service_namespace: null
160      datadog:
161        batch_processor:
162          max_concurrent_exports: 1
163          max_export_batch_size: 512
164          max_export_timeout:
165            nanos: 0
166            secs: 30
167          max_queue_size: 2048
168          scheduled_delay:
169            nanos: 0
170            secs: 5
171        enable_span_mapping: true
172        enabled: false
173        endpoint: example_endpoint
174        fixed_span_names: true
175        resource_mapping: {}
176        span_metrics:
177          connect: true
178          connect_request: true
179          execution: true
180          http_request: true
181          parse_query: true
182          query_planning: true
183          request: true
184          router: true
185          subgraph: true
186          subgraph_request: true
187          supergraph: true
188      experimental_response_trace_id:
189        enabled: false
190        format: hexadecimal
191        header_name: example_header_name
192      otlp:
193        batch_processor:
194          max_concurrent_exports: 1
195          max_export_batch_size: 512
196          max_export_timeout:
197            nanos: 0
198            secs: 30
199          max_queue_size: 2048
200          scheduled_delay:
201            nanos: 0
202            secs: 5
203        enabled: false
204        endpoint: example_endpoint
205        grpc:
206          ca: null
207          cert: null
208          domain_name: null
209          key: null
210          metadata: {}
211        http:
212          headers: {}
213        protocol: grpc
214        temporality: cumulative
215      propagation:
216        aws_xray: false
217        baggage: false
218        datadog: false
219        jaeger: false
220        request:
221          format: hexadecimal
222          header_name: example_header_name
223        trace_context: false
224        zipkin: false
225      zipkin:
226        batch_processor:
227          max_concurrent_exports: 1
228          max_export_batch_size: 512
229          max_export_timeout:
230            nanos: 0
231            secs: 30
232          max_queue_size: 2048
233          scheduled_delay:
234            nanos: 0
235            secs: 5
236        enabled: false
237        endpoint: example_endpoint
238  instrumentation:
239    events:
240      connector:
241        error:
242          condition:
243            eq:
244            - false
245            - false
246          level: info
247        request:
248          condition:
249            eq:
250            - false
251            - false
252          level: info
253        response:
254          condition:
255            eq:
256            - false
257            - false
258          level: info
259      router:
260        error:
261          condition:
262            eq:
263            - false
264            - false
265          level: info
266        request:
267          condition:
268            eq:
269            - false
270            - false
271          level: info
272        response:
273          condition:
274            eq:
275            - false
276            - false
277          level: info
278      subgraph:
279        error:
280          condition:
281            eq:
282            - false
283            - false
284          level: info
285        request:
286          condition:
287            eq:
288            - false
289            - false
290          level: info
291        response:
292          condition:
293            eq:
294            - false
295            - false
296          level: info
297      supergraph:
298        error:
299          condition:
300            eq:
301            - false
302            - false
303          level: info
304        request:
305          condition:
306            eq:
307            - false
308            - false
309          level: info
310        response:
311          condition:
312            eq:
313            - false
314            - false
315          level: info
316    instruments:
317      cache:
318        apollo.router.operations.entity.cache:
319          attributes:
320            graphql.type.name:
321              alias: example_alias
322      connector:
323        http.client.request.body.size:
324          attributes:
325            connector.http.method:
326              alias: example_alias
327            connector.source.name:
328              alias: example_alias
329            connector.url.template:
330              alias: example_alias
331            subgraph.name:
332              alias: example_alias
333        http.client.request.duration:
334          attributes:
335            connector.http.method:
336              alias: example_alias
337            connector.source.name:
338              alias: example_alias
339            connector.url.template:
340              alias: example_alias
341            subgraph.name:
342              alias: example_alias
343        http.client.response.body.size:
344          attributes:
345            connector.http.method:
346              alias: example_alias
347            connector.source.name:
348              alias: example_alias
349            connector.url.template:
350              alias: example_alias
351            subgraph.name:
352              alias: example_alias
353      default_requirement_level: none
354      graphql:
355        field.execution:
356          attributes:
357            graphql.field.name:
358              alias: example_alias
359            graphql.field.type:
360              alias: example_alias
361            graphql.list.length:
362              alias: example_alias
363            graphql.operation.name:
364              alias: example_alias
365            graphql.type.name:
366              alias: example_alias
367        list.length:
368          attributes:
369            graphql.field.name:
370              alias: example_alias
371            graphql.field.type:
372              alias: example_alias
373            graphql.list.length:
374              alias: example_alias
375            graphql.operation.name:
376              alias: example_alias
377            graphql.type.name:
378              alias: example_alias
379      router:
380        http.server.active_requests:
381          attributes:
382            http.request.method: false
383            server.address: false
384            server.port: false
385            url.scheme: false
386        http.server.request.body.size:
387          attributes:
388            baggage: null
389            dd.trace_id:
390              alias: example_alias
391            error.type:
392              alias: example_alias
393            http.request.body.size:
394              alias: example_alias
395            http.request.method:
396              alias: example_alias
397            http.response.body.size:
398              alias: example_alias
399            http.response.status_code:
400              alias: example_alias
401            http.route:
402              alias: example_alias
403            network.local.address:
404              alias: example_alias
405            network.local.port:
406              alias: example_alias
407            network.peer.address:
408              alias: example_alias
409            network.peer.port:
410              alias: example_alias
411            network.protocol.name:
412              alias: example_alias
413            network.protocol.version:
414              alias: example_alias
415            network.transport:
416              alias: example_alias
417            network.type:
418              alias: example_alias
419            server.address:
420              alias: example_alias
421            server.port:
422              alias: example_alias
423            trace_id:
424              alias: example_alias
425            url.path:
426              alias: example_alias
427            url.query:
428              alias: example_alias
429            url.scheme:
430              alias: example_alias
431            user_agent.original:
432              alias: example_alias
433        http.server.request.duration:
434          attributes:
435            baggage: null
436            dd.trace_id:
437              alias: example_alias
438            error.type:
439              alias: example_alias
440            http.request.body.size:
441              alias: example_alias
442            http.request.method:
443              alias: example_alias
444            http.response.body.size:
445              alias: example_alias
446            http.response.status_code:
447              alias: example_alias
448            http.route:
449              alias: example_alias
450            network.local.address:
451              alias: example_alias
452            network.local.port:
453              alias: example_alias
454            network.peer.address:
455              alias: example_alias
456            network.peer.port:
457              alias: example_alias
458            network.protocol.name:
459              alias: example_alias
460            network.protocol.version:
461              alias: example_alias
462            network.transport:
463              alias: example_alias
464            network.type:
465              alias: example_alias
466            server.address:
467              alias: example_alias
468            server.port:
469              alias: example_alias
470            trace_id:
471              alias: example_alias
472            url.path:
473              alias: example_alias
474            url.query:
475              alias: example_alias
476            url.scheme:
477              alias: example_alias
478            user_agent.original:
479              alias: example_alias
480        http.server.response.body.size:
481          attributes:
482            baggage: null
483            dd.trace_id:
484              alias: example_alias
485            error.type:
486              alias: example_alias
487            http.request.body.size:
488              alias: example_alias
489            http.request.method:
490              alias: example_alias
491            http.response.body.size:
492              alias: example_alias
493            http.response.status_code:
494              alias: example_alias
495            http.route:
496              alias: example_alias
497            network.local.address:
498              alias: example_alias
499            network.local.port:
500              alias: example_alias
501            network.peer.address:
502              alias: example_alias
503            network.peer.port:
504              alias: example_alias
505            network.protocol.name:
506              alias: example_alias
507            network.protocol.version:
508              alias: example_alias
509            network.transport:
510              alias: example_alias
511            network.type:
512              alias: example_alias
513            server.address:
514              alias: example_alias
515            server.port:
516              alias: example_alias
517            trace_id:
518              alias: example_alias
519            url.path:
520              alias: example_alias
521            url.query:
522              alias: example_alias
523            url.scheme:
524              alias: example_alias
525            user_agent.original:
526              alias: example_alias
527      subgraph:
528        http.client.request.body.size:
529          attributes:
530            http.request.resend_count:
531              alias: example_alias
532            subgraph.graphql.document:
533              alias: example_alias
534            subgraph.graphql.operation.name:
535              alias: example_alias
536            subgraph.graphql.operation.type:
537              alias: example_alias
538            subgraph.name:
539              alias: example_alias
540        http.client.request.duration:
541          attributes:
542            http.request.resend_count:
543              alias: example_alias
544            subgraph.graphql.document:
545              alias: example_alias
546            subgraph.graphql.operation.name:
547              alias: example_alias
548            subgraph.graphql.operation.type:
549              alias: example_alias
550            subgraph.name:
551              alias: example_alias
552        http.client.response.body.size:
553          attributes:
554            http.request.resend_count:
555              alias: example_alias
556            subgraph.graphql.document:
557              alias: example_alias
558            subgraph.graphql.operation.name:
559              alias: example_alias
560            subgraph.graphql.operation.type:
561              alias: example_alias
562            subgraph.name:
563              alias: example_alias
564      supergraph:
565        cost.actual:
566          attributes:
567            cost.actual:
568              alias: example_alias
569            cost.delta:
570              alias: example_alias
571            cost.estimated:
572              alias: example_alias
573            cost.result:
574              alias: example_alias
575            graphql.document:
576              alias: example_alias
577            graphql.operation.name:
578              alias: example_alias
579            graphql.operation.type:
580              alias: example_alias
581        cost.delta:
582          attributes:
583            cost.actual:
584              alias: example_alias
585            cost.delta:
586              alias: example_alias
587            cost.estimated:
588              alias: example_alias
589            cost.result:
590              alias: example_alias
591            graphql.document:
592              alias: example_alias
593            graphql.operation.name:
594              alias: example_alias
595            graphql.operation.type:
596              alias: example_alias
597        cost.estimated:
598          attributes:
599            cost.actual:
600              alias: example_alias
601            cost.delta:
602              alias: example_alias
603            cost.estimated:
604              alias: example_alias
605            cost.result:
606              alias: example_alias
607            graphql.document:
608              alias: example_alias
609            graphql.operation.name:
610              alias: example_alias
611            graphql.operation.type:
612              alias: example_alias
613    spans:
614      connector:
615        attributes:
616          connector.http.method:
617            alias: example_alias
618          connector.source.name:
619            alias: example_alias
620          connector.url.template:
621            alias: example_alias
622          subgraph.name:
623            alias: example_alias
624      default_attribute_requirement_level: none
625      router:
626        attributes:
627          baggage: null
628          dd.trace_id:
629            alias: example_alias
630          error.type:
631            alias: example_alias
632          http.request.body.size:
633            alias: example_alias
634          http.request.method:
635            alias: example_alias
636          http.response.body.size:
637            alias: example_alias
638          http.response.status_code:
639            alias: example_alias
640          http.route:
641            alias: example_alias
642          network.local.address:
643            alias: example_alias
644          network.local.port:
645            alias: example_alias
646          network.peer.address:
647            alias: example_alias
648          network.peer.port:
649            alias: example_alias
650          network.protocol.name:
651            alias: example_alias
652          network.protocol.version:
653            alias: example_alias
654          network.transport:
655            alias: example_alias
656          network.type:
657            alias: example_alias
658          server.address:
659            alias: example_alias
660          server.port:
661            alias: example_alias
662          trace_id:
663            alias: example_alias
664          url.path:
665            alias: example_alias
666          url.query:
667            alias: example_alias
668          url.scheme:
669            alias: example_alias
670          user_agent.original:
671            alias: example_alias
672      subgraph:
673        attributes:
674          http.request.resend_count:
675            alias: example_alias
676          subgraph.graphql.document:
677            alias: example_alias
678          subgraph.graphql.operation.name:
679            alias: example_alias
680          subgraph.graphql.operation.type:
681            alias: example_alias
682          subgraph.name:
683            alias: example_alias
684      supergraph:
685        attributes:
686          cost.actual:
687            alias: example_alias
688          cost.delta:
689            alias: example_alias
690          cost.estimated:
691            alias: example_alias
692          cost.result:
693            alias: example_alias
694          graphql.document:
695            alias: example_alias
696          graphql.operation.name:
697            alias: example_alias
698          graphql.operation.type:
699            alias: example_alias
telemetry YAML snippet (deprecated <= Router v2.6)
YAML
telemetry
1telemetry:
2  apollo:
3    batch_processor:
4      max_concurrent_exports: 1
5      max_export_batch_size: 512
6      max_export_timeout:
7        nanos: 0
8        secs: 30
9      max_queue_size: 2048
10      scheduled_delay:
11        nanos: 0
12        secs: 5
13    buffer_size: 10000
14    client_name_header: apollographql-client-name
15    client_version_header: apollographql-client-version
16    endpoint: https://usage-reporting.api.apollographql.com/api/ingress/traces
17    errors:
18      preview_extended_error_metrics: disabled
19      subgraph:
20        all:
21          redact: true
22          redaction_policy: strict
23          send: true
24        subgraphs: {}
25    experimental_local_field_metrics: false
26    experimental_otlp_endpoint: https://usage-reporting.api.apollographql.com/
27    experimental_otlp_tracing_protocol: grpc
28    field_level_instrumentation_sampler: 0.0
29    metrics_reference_mode: extended
30    otlp_tracing_sampler: 0.0
31    send_headers:
32      only:
33      - example_only_item
34    send_variable_values:
35      only:
36      - example_only_item
37    signature_normalization_algorithm: enhanced
38  exporters:
39    logging:
40      common:
41        resource: {}
42        service_name: null
43        service_namespace: null
44      stdout:
45        enabled: true
46        format:
47          json:
48            display_current_span: false
49            display_filename: false
50            display_level: true
51            display_line_number: false
52            display_resource: true
53            display_span_id: true
54            display_span_list: true
55            display_target: true
56            display_thread_id: false
57            display_thread_name: false
58            display_timestamp: true
59            display_trace_id: hexadecimal
60            span_attributes: []
61            expand_json_string_values: false
62        rate_limit:
63          capacity: 1
64          enabled: false
65          interval:
66            nanos: 0
67            secs: 1
68        tty_format:
69          json:
70            display_current_span: false
71            display_filename: false
72            display_level: true
73            display_line_number: false
74            display_resource: true
75            display_span_id: true
76            display_span_list: true
77            display_target: true
78            display_thread_id: false
79            display_thread_name: false
80            display_timestamp: true
81            display_trace_id: hexadecimal
82            span_attributes: []
83            expand_json_string_values: false
84    metrics:
85      common:
86        buckets:
87        - 0.001
88        - 0.005
89        - 0.015
90        - 0.05
91        - 0.1
92        - 0.2
93        - 0.3
94        - 0.4
95        - 0.5
96        - 1.0
97        - 5.0
98        - 10.0
99        resource: {}
100        service_name: null
101        service_namespace: null
102        views:
103        - aggregation:
104            histogram:
105              buckets:
106              - 0.0
107          allowed_attribute_keys:
108          - example_allowed_attribute_keys_item
109          description: example_description
110          name: example_name
111          unit: example_unit
112      otlp:
113        batch_processor:
114          max_concurrent_exports: 1
115          max_export_batch_size: 512
116          max_export_timeout:
117            nanos: 0
118            secs: 30
119          max_queue_size: 2048
120          scheduled_delay:
121            nanos: 0
122            secs: 5
123        enabled: false
124        endpoint: example_endpoint
125        grpc:
126          ca: null
127          cert: null
128          domain_name: null
129          key: null
130          metadata: {}
131        http:
132          headers: {}
133        protocol: grpc
134        temporality: cumulative
135      prometheus:
136        enabled: false
137        listen: example_listen
138        path: /metrics
139    tracing:
140      common:
141        max_attributes_per_event: 128
142        max_attributes_per_link: 128
143        max_attributes_per_span: 128
144        max_events_per_span: 128
145        max_links_per_span: 128
146        parent_based_sampler: true
147        preview_datadog_agent_sampling: null
148        resource: {}
149        sampler: 0.0
150        service_name: null
151        service_namespace: null
152      datadog:
153        batch_processor:
154          max_concurrent_exports: 1
155          max_export_batch_size: 512
156          max_export_timeout:
157            nanos: 0
158            secs: 30
159          max_queue_size: 2048
160          scheduled_delay:
161            nanos: 0
162            secs: 5
163        enable_span_mapping: true
164        enabled: false
165        endpoint: example_endpoint
166        fixed_span_names: true
167        resource_mapping: {}
168        span_metrics:
169          connect: true
170          connect_request: true
171          execution: true
172          http_request: true
173          parse_query: true
174          query_planning: true
175          request: true
176          router: true
177          subgraph: true
178          subgraph_request: true
179          supergraph: true
180      experimental_response_trace_id:
181        enabled: false
182        format: hexadecimal
183        header_name: example_header_name
184      otlp:
185        batch_processor:
186          max_concurrent_exports: 1
187          max_export_batch_size: 512
188          max_export_timeout:
189            nanos: 0
190            secs: 30
191          max_queue_size: 2048
192          scheduled_delay:
193            nanos: 0
194            secs: 5
195        enabled: false
196        endpoint: example_endpoint
197        grpc:
198          ca: null
199          cert: null
200          domain_name: null
201          key: null
202          metadata: {}
203        http:
204          headers: {}
205        protocol: grpc
206        temporality: cumulative
207      propagation:
208        aws_xray: false
209        baggage: false
210        datadog: false
211        jaeger: false
212        request:
213          format: hexadecimal
214          header_name: example_header_name
215        trace_context: false
216        zipkin: false
217      zipkin:
218        batch_processor:
219          max_concurrent_exports: 1
220          max_export_batch_size: 512
221          max_export_timeout:
222            nanos: 0
223            secs: 30
224          max_queue_size: 2048
225          scheduled_delay:
226            nanos: 0
227            secs: 5
228        enabled: false
229        endpoint: example_endpoint
230  instrumentation:
231    events:
232      connector:
233        error:
234          condition:
235            eq:
236            - false
237            - false
238          level: info
239        request:
240          condition:
241            eq:
242            - false
243            - false
244          level: info
245        response:
246          condition:
247            eq:
248            - false
249            - false
250          level: info
251      router:
252        error:
253          condition:
254            eq:
255            - false
256            - false
257          level: info
258        request:
259          condition:
260            eq:
261            - false
262            - false
263          level: info
264        response:
265          condition:
266            eq:
267            - false
268            - false
269          level: info
270      subgraph:
271        error:
272          condition:
273            eq:
274            - false
275            - false
276          level: info
277        request:
278          condition:
279            eq:
280            - false
281            - false
282          level: info
283        response:
284          condition:
285            eq:
286            - false
287            - false
288          level: info
289      supergraph:
290        error:
291          condition:
292            eq:
293            - false
294            - false
295          level: info
296        request:
297          condition:
298            eq:
299            - false
300            - false
301          level: info
302        response:
303          condition:
304            eq:
305            - false
306            - false
307          level: info
308    instruments:
309      cache:
310        apollo.router.operations.entity.cache:
311          attributes:
312            graphql.type.name:
313              alias: example_alias
314      connector:
315        http.client.request.body.size:
316          attributes:
317            connector.http.method:
318              alias: example_alias
319            connector.source.name:
320              alias: example_alias
321            connector.url.template:
322              alias: example_alias
323            subgraph.name:
324              alias: example_alias
325        http.client.request.duration:
326          attributes:
327            connector.http.method:
328              alias: example_alias
329            connector.source.name:
330              alias: example_alias
331            connector.url.template:
332              alias: example_alias
333            subgraph.name:
334              alias: example_alias
335        http.client.response.body.size:
336          attributes:
337            connector.http.method:
338              alias: example_alias
339            connector.source.name:
340              alias: example_alias
341            connector.url.template:
342              alias: example_alias
343            subgraph.name:
344              alias: example_alias
345      default_requirement_level: none
346      graphql:
347        field.execution:
348          attributes:
349            graphql.field.name:
350              alias: example_alias
351            graphql.field.type:
352              alias: example_alias
353            graphql.list.length:
354              alias: example_alias
355            graphql.operation.name:
356              alias: example_alias
357            graphql.type.name:
358              alias: example_alias
359        list.length:
360          attributes:
361            graphql.field.name:
362              alias: example_alias
363            graphql.field.type:
364              alias: example_alias
365            graphql.list.length:
366              alias: example_alias
367            graphql.operation.name:
368              alias: example_alias
369            graphql.type.name:
370              alias: example_alias
371      router:
372        http.server.active_requests:
373          attributes:
374            http.request.method: false
375            server.address: false
376            server.port: false
377            url.scheme: false
378        http.server.request.body.size:
379          attributes:
380            baggage: null
381            dd.trace_id:
382              alias: example_alias
383            error.type:
384              alias: example_alias
385            http.request.body.size:
386              alias: example_alias
387            http.request.method:
388              alias: example_alias
389            http.response.body.size:
390              alias: example_alias
391            http.response.status_code:
392              alias: example_alias
393            http.route:
394              alias: example_alias
395            network.local.address:
396              alias: example_alias
397            network.local.port:
398              alias: example_alias
399            network.peer.address:
400              alias: example_alias
401            network.peer.port:
402              alias: example_alias
403            network.protocol.name:
404              alias: example_alias
405            network.protocol.version:
406              alias: example_alias
407            network.transport:
408              alias: example_alias
409            network.type:
410              alias: example_alias
411            server.address:
412              alias: example_alias
413            server.port:
414              alias: example_alias
415            trace_id:
416              alias: example_alias
417            url.path:
418              alias: example_alias
419            url.query:
420              alias: example_alias
421            url.scheme:
422              alias: example_alias
423            user_agent.original:
424              alias: example_alias
425        http.server.request.duration:
426          attributes:
427            baggage: null
428            dd.trace_id:
429              alias: example_alias
430            error.type:
431              alias: example_alias
432            http.request.body.size:
433              alias: example_alias
434            http.request.method:
435              alias: example_alias
436            http.response.body.size:
437              alias: example_alias
438            http.response.status_code:
439              alias: example_alias
440            http.route:
441              alias: example_alias
442            network.local.address:
443              alias: example_alias
444            network.local.port:
445              alias: example_alias
446            network.peer.address:
447              alias: example_alias
448            network.peer.port:
449              alias: example_alias
450            network.protocol.name:
451              alias: example_alias
452            network.protocol.version:
453              alias: example_alias
454            network.transport:
455              alias: example_alias
456            network.type:
457              alias: example_alias
458            server.address:
459              alias: example_alias
460            server.port:
461              alias: example_alias
462            trace_id:
463              alias: example_alias
464            url.path:
465              alias: example_alias
466            url.query:
467              alias: example_alias
468            url.scheme:
469              alias: example_alias
470            user_agent.original:
471              alias: example_alias
472        http.server.response.body.size:
473          attributes:
474            baggage: null
475            dd.trace_id:
476              alias: example_alias
477            error.type:
478              alias: example_alias
479            http.request.body.size:
480              alias: example_alias
481            http.request.method:
482              alias: example_alias
483            http.response.body.size:
484              alias: example_alias
485            http.response.status_code:
486              alias: example_alias
487            http.route:
488              alias: example_alias
489            network.local.address:
490              alias: example_alias
491            network.local.port:
492              alias: example_alias
493            network.peer.address:
494              alias: example_alias
495            network.peer.port:
496              alias: example_alias
497            network.protocol.name:
498              alias: example_alias
499            network.protocol.version:
500              alias: example_alias
501            network.transport:
502              alias: example_alias
503            network.type:
504              alias: example_alias
505            server.address:
506              alias: example_alias
507            server.port:
508              alias: example_alias
509            trace_id:
510              alias: example_alias
511            url.path:
512              alias: example_alias
513            url.query:
514              alias: example_alias
515            url.scheme:
516              alias: example_alias
517            user_agent.original:
518              alias: example_alias
519      subgraph:
520        http.client.request.body.size:
521          attributes:
522            http.request.resend_count:
523              alias: example_alias
524            subgraph.graphql.document:
525              alias: example_alias
526            subgraph.graphql.operation.name:
527              alias: example_alias
528            subgraph.graphql.operation.type:
529              alias: example_alias
530            subgraph.name:
531              alias: example_alias
532        http.client.request.duration:
533          attributes:
534            http.request.resend_count:
535              alias: example_alias
536            subgraph.graphql.document:
537              alias: example_alias
538            subgraph.graphql.operation.name:
539              alias: example_alias
540            subgraph.graphql.operation.type:
541              alias: example_alias
542            subgraph.name:
543              alias: example_alias
544        http.client.response.body.size:
545          attributes:
546            http.request.resend_count:
547              alias: example_alias
548            subgraph.graphql.document:
549              alias: example_alias
550            subgraph.graphql.operation.name:
551              alias: example_alias
552            subgraph.graphql.operation.type:
553              alias: example_alias
554            subgraph.name:
555              alias: example_alias
556      supergraph:
557        cost.actual:
558          attributes:
559            cost.actual:
560              alias: example_alias
561            cost.delta:
562              alias: example_alias
563            cost.estimated:
564              alias: example_alias
565            cost.result:
566              alias: example_alias
567            graphql.document:
568              alias: example_alias
569            graphql.operation.name:
570              alias: example_alias
571            graphql.operation.type:
572              alias: example_alias
573        cost.delta:
574          attributes:
575            cost.actual:
576              alias: example_alias
577            cost.delta:
578              alias: example_alias
579            cost.estimated:
580              alias: example_alias
581            cost.result:
582              alias: example_alias
583            graphql.document:
584              alias: example_alias
585            graphql.operation.name:
586              alias: example_alias
587            graphql.operation.type:
588              alias: example_alias
589        cost.estimated:
590          attributes:
591            cost.actual:
592              alias: example_alias
593            cost.delta:
594              alias: example_alias
595            cost.estimated:
596              alias: example_alias
597            cost.result:
598              alias: example_alias
599            graphql.document:
600              alias: example_alias
601            graphql.operation.name:
602              alias: example_alias
603            graphql.operation.type:
604              alias: example_alias
605    spans:
606      connector:
607        attributes:
608          connector.http.method:
609            alias: example_alias
610          connector.source.name:
611            alias: example_alias
612          connector.url.template:
613            alias: example_alias
614          subgraph.name:
615            alias: example_alias
616      default_attribute_requirement_level: none
617      router:
618        attributes:
619          baggage: null
620          dd.trace_id:
621            alias: example_alias
622          error.type:
623            alias: example_alias
624          http.request.body.size:
625            alias: example_alias
626          http.request.method:
627            alias: example_alias
628          http.response.body.size:
629            alias: example_alias
630          http.response.status_code:
631            alias: example_alias
632          http.route:
633            alias: example_alias
634          network.local.address:
635            alias: example_alias
636          network.local.port:
637            alias: example_alias
638          network.peer.address:
639            alias: example_alias
640          network.peer.port:
641            alias: example_alias
642          network.protocol.name:
643            alias: example_alias
644          network.protocol.version:
645            alias: example_alias
646          network.transport:
647            alias: example_alias
648          network.type:
649            alias: example_alias
650          server.address:
651            alias: example_alias
652          server.port:
653            alias: example_alias
654          trace_id:
655            alias: example_alias
656          url.path:
657            alias: example_alias
658          url.query:
659            alias: example_alias
660          url.scheme:
661            alias: example_alias
662          user_agent.original:
663            alias: example_alias
664      subgraph:
665        attributes:
666          http.request.resend_count:
667            alias: example_alias
668          subgraph.graphql.document:
669            alias: example_alias
670          subgraph.graphql.operation.name:
671            alias: example_alias
672          subgraph.graphql.operation.type:
673            alias: example_alias
674          subgraph.name:
675            alias: example_alias
676      supergraph:
677        attributes:
678          cost.actual:
679            alias: example_alias
680          cost.delta:
681            alias: example_alias
682          cost.estimated:
683            alias: example_alias
684          cost.result:
685            alias: example_alias
686          graphql.document:
687            alias: example_alias
688          graphql.operation.name:
689            alias: example_alias
690          graphql.operation.type:
691            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