Router YAML Configuration Reference

This reference covers the YAML configuration file properties for configuring an Apollo Router.

YAML configuration properties

The router can be configured by a YAML configuration file. This file enables you to declaratively configure various runtime properties of your router's behavior.

At startup, you set the config file for your router by providing its path with the --config option:

Bash

1./router --config router.yaml

tip

Enable your text editor to validate the format and content of your router YAML configuration file by configuring it with the router's configuration schema.

Example YAML with all properties

Expand the code block to view an example YAML config file containing all properties.

Example router YAML config file with all properties

YAML

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

Properties

`apq`

YAML

apq

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

Learn more in Automatic Persisted Queries.

`authentication`

authentication YAML snippet

YAML

authentication

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

To learn about JWT authentication, go to JWT authentication in the GraphOS Router.
To learn about subgraph authentication with AWS SigV4, go to a subgraph authentication configuration example.

`authorization`

YAML

authorization

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

To configure authorization directives, see Authorization directives.
To configure the authorization plugin, see Configuration options.

`batching`

YAML

batching

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

Learn more in query batching.

`connectors`

YAML

connectors

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

Learn more in Working with router for Apollo Connectors.

`coprocessor`

coprocessor YAML snippet

YAML

coprocessor

1coprocessor:
2  client:
3    dns_resolution_strategy: ipv4_only
4    experimental_http2: enable
5  connector:
6    all:
7      request:
8        body: false
9        condition:
10          eq:
11          - false
12          - false
13        context: false
14        headers: false
15        method: false
16        service_name: false
17        uri: false
18      response:
19        body: false
20        condition:
21          eq:
22          - false
23          - false
24        context: false
25        headers: false
26        service_name: false
27        status_code: false
28  execution:
29    request:
30      body: false
31      context: false
32      headers: false
33      method: false
34      query_plan: false
35      sdl: false
36    response:
37      body: false
38      context: false
39      headers: false
40      sdl: false
41      status_code: false
42  router:
43    request:
44      body: false
45      condition:
46        eq:
47        - false
48        - false
49      context: false
50      headers: false
51      method: false
52      path: false
53      sdl: false
54    response:
55      body: false
56      condition:
57        eq:
58        - false
59        - false
60      context: false
61      headers: false
62      sdl: false
63      status_code: false
64  subgraph:
65    all:
66      request:
67        body: false
68        condition:
69          eq:
70          - false
71          - false
72        context: false
73        headers: false
74        method: false
75        service_name: false
76        subgraph_request_id: false
77        uri: false
78      response:
79        body: false
80        condition:
81          eq:
82          - false
83          - false
84        context: false
85        headers: false
86        service_name: false
87        status_code: false
88        subgraph_request_id: false
89  supergraph:
90    request:
91      body: false
92      condition:
93        eq:
94        - false
95        - false
96      context: false
97      headers: false
98      method: false
99      sdl: false
100    response:
101      body: false
102      condition:
103        eq:
104        - false
105        - false
106      context: false
107      headers: false
108      sdl: false
109      status_code: false
110  timeout:
111    nanos: 0
112    secs: 1
113  url: http://service.example.com/url

Learn more in External coprocessing in the GraphOS Router.

`cors`

YAML

cors

1cors:
2  allow_any_origin: false
3  allow_credentials: false
4  allow_headers: []
5  expose_headers: null
6  max_age: null
7  methods:
8  - GET
9  - POST
10  - OPTIONS
11  policies:
12  - origins:
13    - https://studio.apollographql.com
14    - https://myapp.com
15    allow_credentials: false
16    allow_headers: []
17    expose_headers: []
18    private_network_access:
19      access_id:
20    # methods not specified - uses global defaults [GET, POST, OPTIONS]
21  - origins:
22    - https://restricted.com
23    methods: []  # Explicitly no methods allowed
24  - origins:
25    - https://api.example.com
26    match_origins:
27    - "^https://.*\\.example\\.com$"
28    allow_headers:
29    - content-type
30    - authorization
31    methods:
32    - GET
33    - POST
34    private_network_access:
35      access_id: "01:23:45:67:89:0A"
36      access_name: "mega-corp device"
37    # Specific methods override global defaults

By default, the router only allows GraphOS Studio to initiate browser connections to it. If your supergraph serves data to other browser-based applications, you need to update its Cross-Origin Resource Sharing (CORS) configuration.

Learn more in CORS.

`csrf`

YAML

csrf

1csrf:
2  required_headers:
3  - x-apollo-operation-name
4  - apollo-require-preflight
5  unsafe_disabled: false

Learn more in CSRF prevention in the router.

`demand_control`

YAML

demand_control

1demand_control:
2  enabled: false
3  mode: measure
4  strategy:
5    static_estimated:
6      list_size: 0
7      max: 0.0
8      actual_cost_mode: by_subgraph
9      subgraph:
10        all:
11          list_size: 0
12          max: 0.0
13        subgraphs: {}

With demand control, the router analyzes the cost of operations and rejects requests with operations that exceed customizable cost limits.

Learn more in Demand Control

`experimental_chaos`

YAML

experimental_chaos

1experimental_chaos:
2  force_reload: null

`experimental_type_conditioned_fetching`

YAML

experimental_type_conditioned_fetching

1experimental_type_conditioned_fetching: false

`fleet_detector`

YAML

fleet_detector

1fleet_detector: {}

`forbid_mutations`

YAML

forbid_mutations

1forbid_mutations: false

`headers`

YAML

headers

1headers:
2  all:
3    request:
4    - insert:
5        name: example_name
6        value: example_value
7  subgraphs: {}

Learn more in Sending HTTP headers to subgraphs.

`health_check`

YAML

health_check

1health_check:
2  enabled: true
3  listen: example_listen
4  path: /health
5  readiness:
6    allowed: 100
7    interval:
8      sampling: 0s
9      unready: null

Learn more in Health Checks.

`homepage`

YAML

homepage

1homepage:
2  enabled: true
3  graph_ref: null

The router can serve a landing page to browsers that visit its endpoint path (supergraph.path):

A basic landing page that displays an example query curl command (default)

YAML

router.yaml

1# This is the default behavior. You don't need to include this config.
2homepage:
3  enabled: true

No landing page
YAML
router.yaml
1homepage: 2 enabled: false
Sending users to Apollo Explorer
YAML
router.yaml
1homepage: 2 graph_ref: my-org-graph@production
When you specify a graph_ref, the router's landing page includes an option for users to redirect to Apollo Explorer. Users can check a box that will remember their preference and automatically redirect them to Explorer on subsequent visits.
note
The graph_ref value should match the format organization-name@variant-name, which is the same format used with the APOLLO_GRAPH_REF environment variable. Note that the router does not automatically use the value from the APOLLO_GRAPH_REF environment variable for this setting - you must explicitly set graph_ref in your YAML configuration even if you're already using the environment variable.

`include_subgraph_errors`

YAML

include_subgraph_errors

1include_subgraph_errors:
2  all: false
3  subgraphs: {}

`license_enforcement`

YAML

license_enforcement

1license_enforcement: {}

`limits`

YAML

limits

1limits:
2  http1_max_request_buf_size: null
3  http1_max_request_headers: null
4  http_max_request_bytes: 2000000
5  introspection_max_depth: true
6  max_aliases: null
7  max_depth: null
8  max_height: null
9  max_root_fields: null
10  parser_max_recursion: 500
11  parser_max_tokens: 15000
12  warn_only: false

Learn more in Request Limits.

`override_subgraph_url`

YAML

override_subgraph_url

1override_subgraph_url: {}

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

note

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

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

YAML

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

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

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

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

`persisted_queries`

YAML

persisted_queries

1persisted_queries:
2  enabled: false
3  experimental_prewarm_query_plan_cache:
4    on_reload: true
5    on_startup: false
6  hot_reload: false
7  local_manifests: null
8  log_unknown: false
9  safelist:
10    enabled: false
11    require_id: false

You can enhance your graph's security with GraphOS Router by maintaining a persisted query list (PQL), an operation safelist made by your first-party apps. As opposed to automatic persisted queries (APQ) where operations are automatically cached, operations must be preregistered to the PQL. Once configured, the router checks incoming requests against the PQL.

Learn more about safelisting with persisted queries.

`plugins`

YAML

plugins

1plugins: unknown_type_plugins

You can customize the router's behavior with plugins. Each plugin can have its own section in the configuration file with arbitrary values:

YAML

example-plugin-router.yaml

1plugins:
2  example.plugin:
3    var1: "hello"
4    var2: 1

Learn more in Native Plugins for router.

`preview_entity_cache`

preview_entity_cache YAML snippet

YAML

preview_entity_cache

1preview_entity_cache:
2  enabled: false
3  expose_keys_in_context: false
4  invalidation:
5    concurrent_requests: 10
6    listen: example_listen
7    path: example_path
8    scan_count: 1000
9  metrics:
10    enabled: false
11    separate_per_type: false
12    ttl: 30s
13  subgraph:
14    all:
15      enabled: true
16      invalidation:
17        enabled: false
18        shared_key: ''
19      private_id: null
20      redis:
21        namespace: example_namespace
22        password: example_password
23        pool_size: 1
24        required_to_start: false
25        reset_ttl: true
26        timeout: null
27        tls:
28          certificate_authorities: null
29          client_authentication:
30            certificate_chain: example_certificate_chain
31            key: example_key
32        ttl: null
33        urls:
34        - http://example.com/urls_item
35        username: example_username
36      ttl: 30s
37    subgraphs: {}

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

Connection metrics: Track Redis connection establishment and health
Command metrics: Monitor Redis command execution, queue length, and redelivery counts
Performance metrics: Measure average latency, network latency, and request/response sizes
Operational metrics: Help identify connection issues, network problems, or performance bottlenecks

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

note

For new projects, Apollo recommends using Response Caching instead.

Learn more in Entity Caching.

`response_cache`

response_cache YAML snippet

YAML

response_cache.router.yaml

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

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

Connection metrics: Track Redis connection establishment and health
Command metrics: Monitor Redis command execution, queue length, and redelivery counts
Performance metrics: Measure average latency, network latency, and request/response sizes
Operational metrics: Help identify connection issues, network problems, or performance bottlenecks

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

Learn more in Response Caching.

`preview_file_uploads`

YAML

preview_file_uploads

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

Learn more in File Uploads.

`rhai`

YAML

rhai

1rhai:
2  main: example_main
3  scripts: example_scripts

Learn more in Rhai customization for router.

`sandbox`

YAML

sandbox

1sandbox:
2  enabled: false

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

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

YAML

router.yaml

1sandbox:
2  enabled: true
3
4# Sandbox uses introspection to obtain your router's schema.
5supergraph:
6  introspection: true
7
8# Sandbox requires the default landing page to be disabled.
9homepage:
10  enabled: false

caution

Do not enable Sandbox in production. Sandbox requires enabling introspection, which is strongly discouraged in production environments.

Learn more in Apollo Sandbox.

`server`

YAML

server

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

Header Read Timeout

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

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

TLS handshake timeout

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

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

`subscription`

YAML

subscription

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

Learn more in Subscriptions.

`supergraph`

supergraph YAML snippet

YAML

supergraph

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

Supergraph listen address

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

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

IPv4

YAML

router.yaml

1supergraph:
2  # The socket address and port to listen on (default: 127.0.0.1:400)
3  listen: 127.0.0.1:4000

IPv6

YAML

router.yaml

1supergraph:
2  # The socket address and port to listen on. (default: [::1]:4000)
3  # Note that this must be quoted to avoid interpretation as an array in YAML.
4  listen: "[::1]:4000"

Unix socket

YAML

router_unix.yaml

1supergraph:
2  # Absolute path to a Unix socket
3  listen: /tmp/router.sock

note

Listening on a Unix socket is not supported on Windows.

Supergraph endpoint path

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

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

YAML

router.yaml

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

The path must start with /.

A path can contain parameters and wildcards:

/{parameter} matches a single segment. For example:
- /abc/{my_param}/def matches /abc/1/def and /abc/whatever/def, but it doesn't match /abc/1/2/def or /abc/def
/{*parameter} matches all segments in the rest of a path. For example:
- /abc/{*wildcard} matches /abc/1/def and /abc/w/h/a/t/e/v/e/r, but it doesn't match /abc/ or /not_abc_at_all

note

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

Introspection

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

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

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

YAML

router.yaml

1# Do not enable introspection in production!
2supergraph:
3  introspection: true

Introspection recursion limit

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

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

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

YAML

router.yaml

1# Do not enable introspection in production!
2supergraph:
3  introspection: true
4limits:
5  introspection_max_depth: false

Redacting query validation errors

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

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

YAML

router.yaml

1supergraph:
2  redact_query_validation_errors: true

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

JSON

1{
2  "message": "invalid query",
3  "extensions": {
4    "code": "UNKNOWN_ERROR"
5  }
6}

note

Enabling this option will make debugging more difficult, as clients won't receive specific information about what's wrong with their queries. Consider enabling it only in production environments where schema details should remain private.

Early cancel

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

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

YAML

1supergraph:
2  early_cancel: true

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

YAML

router.yaml

1supergraph:
2  experimental_log_on_broken_pipe: true

Connection shutdown timeout

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

YAML

router.yaml

1supergraph:
2  connection_shutdown_timeout: 60s

The default value is 60 seconds.

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

YAML

router.yaml

1traffic_shaping:
2  router:
3    timeout: 60s

Automatic fragment generation

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

Opt out of this behavior by specifying supergraph.generate_query_fragments:

YAML

1supergraph:
2  generate_query_fragments: false

Variable validation modes

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

YAML

1supergraph:
2  strict_variable_validation: enforce

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

`telemetry`

telemetry YAML snippet (>= Router v2.7.0)

YAML

telemetry

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

telemetry YAML snippet (deprecated <= Router v2.6)

YAML

telemetry

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

Enhanced operation signature normalization

Requires ≥ Router v1.49.0

note

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

General availability in v1.54.0 and later
Experimental in v1.49.0 to v1.53.0

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

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

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

YAML

router.yaml

1telemetry:
2  apollo:
3    signature_normalization_algorithm: enhanced # Default is legacy

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

Input types

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

Given the following example operation:

GraphQL

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

The legacy normalization algorithm generates the following signature:

GraphQL

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

The enhanced normalization algorithm generates the following signature:

GraphQL

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

Aliases

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

Given the following example operation:

GraphQL

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

The legacy normalization algorithm generates the following signature:

GraphQL

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

The enhanced normalization algorithm generates the following signature:

GraphQL

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

Extended reference reporting

Requires ≥ Router v1.50.0

note

The router supports extended reference reporting in the following versions:

General availability in v1.54.0 and later
Experimental in v1.50.0 to v1.53.0

You can configure the router to report enum and input object references for enhanced insights and operation checks. Apollo's legacy reference reporting doesn't include data about enum values and input object fields, meaning you can't view enum and input object field usage in GraphOS Studio. Legacy reporting can also cause inaccurate operation checks.

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

YAML

router.yaml

1telemetry:
2  apollo:
3    metrics_reference_mode: extended # Default is legacy

Extended error reporting

Requires ≥ Router v2.1.2

PREVIEW

This feature is in preview. Your questions and feedback are highly valued—don't hesitate to get in touch with your Apollo contact.

note

The router supports extended error reporting in the following versions:

Preview in v2.1.2 and later
Experimental in v2.0.0

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

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

YAML

router.yaml

1telemetry:
2  apollo:
3    errors:
4      preview_extended_error_metrics: enabled # Default is disabled

Learn more.

Configuration effect timing

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

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

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

Enhanced operation checks

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

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

note

You won't see an immediate change in checks behavior when you first turn on extended reference reporting. Learn more.

`tls`

YAML

tls

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

Learn more in TLS for the router.

`traffic_shaping`

YAML

traffic_shaping

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

Learn more in Traffic Shaping.

YAML configuration utilities

Variable expansion

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

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

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

${env.ENV_VAR_NAME} expands to the value of environment variable ENV_VAR_NAME.
${env.ENV_VAR_NAME:-some_default} expands to the value of environment variable ENV_VAR_NAME, or falls back to the value some_default if the environment variable is not defined.
${file.a.txt} expands to the contents of the file a.txt.
${file.a.txt:-some_default} expands to the contents of the file a.txt, or falls back to the value some_default if the file does not exist.

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

Reusing configurations with YAML aliases

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

YAML

router.yaml

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

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

Escaping special characters

To include a literal $ character, double it as $$. The router converts each $$ to a single $:

Config value: prefix$$suffix
Result: prefix$suffix

Checklist for configuring the router for production

Telemetry Data

Metrics

Traces

Usage Guides

Subgraph Observability

Client Observability

Telemetry Exporters

Metrics Exporters

Log Exporters

Trace Exporters

APM Guides

Datadog

Connecting to Datadog

Datadog Agent

New Relic

Prometheus

Zipkin

Jaeger

Dynatrace

AWS Lattice

Telemetry Data

Metrics

Traces

Usage Guides

Subgraph Observability

Client Observability

Telemetry Exporters

Metrics Exporters

Log Exporters

Trace Exporters

APM Guides

Datadog

Connecting to Datadog

Datadog Agent

New Relic

Prometheus

Zipkin

Jaeger

Dynatrace

AWS Lattice