Router YAML Configuration Reference

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

YAML configuration properties

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

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

Bash

1./router --config router.yaml

tip

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

Example YAML with all properties

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

Example router YAML config file with all properties

YAML

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

Properties

`apq`

YAML

apq

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

Learn more in Automatic Persisted Queries.

`authentication`

authentication YAML snippet

YAML

authentication

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

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

`authorization`

YAML

authorization

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

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

`batching`

YAML

batching

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

Learn more in query batching.

`connectors`

YAML

connectors

1connectors:
2  debug_extensions: false
3  expose_sources_in_context: false
4  max_requests_per_operation_per_source: null
5  sources: {}
6  subgraphs: {} # Deprecated. Use `sources` instead.

Learn more in Working with router for Apollo Connectors.

`coprocessor`

coprocessor YAML snippet

YAML

coprocessor

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

Learn more in External coprocessing in the GraphOS Router.

`cors`

YAML

cors

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

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

Learn more in CORS.

`csrf`

YAML

csrf

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

Learn more in CSRF prevention in the router.

`demand_control`

YAML

demand_control

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

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

Learn more in Demand Control

`experimental_hoist_orphan_errors`

YAML

experimental_hoist_orphan_errors

1experimental_hoist_orphan_errors:
2  all:
3    enabled: false
4  subgraphs: {}

Experimental Feature

When the entity-resolution process for a subgraph returns errors that apply to multiple entities in a list, the router defaults to propagating each error to every matching entity path. That results in a multiplicative increase in the size of the returned error array.

The experimental_hoist_orphan_errors option changes that behavior on a per-subgraph basis. When enabled, the router attaches each orphaned subgraph error to a single parent path instead of duplicating the error across every entity path, which can significantly reduce the number of errors in the response.

caution

The experimental_hoist_orphan_errors option isn't compliant with the GraphQL spec. The option changes how errors are associated with paths in the response, compared to the behavior described in the GraphQL specification. Only use the feature for your subgraphs when the reduction in error volume is more desirable than strict compliance.

To target a specific subgraph:

YAML

router.yaml

1experimental_hoist_orphan_errors:
2  subgraphs:
3    my_subgraph:
4      enabled: true

To target all subgraphs:

YAML

router.yaml

1experimental_hoist_orphan_errors:
2  all:
3    enabled: true

To target all subgraphs except one:

YAML

router.yaml

1experimental_hoist_orphan_errors:
2  all:
3    enabled: true
4  subgraphs:
5    spec_compliant_one:
6      enabled: false

Per-subgraph settings override all.

note

Although the experimental_hoist_orphan_errors option can reduce the number of propagated errors, the option doesn't limit the total number of errors. If a subgraph returns a large number of errors, the router still processes all of them. For subgraphs that are likely to produce an unbounded number of errors, consider additional mitigation strategies at the subgraph level.

`experimental_type_conditioned_fetching`

YAML

experimental_type_conditioned_fetching

1experimental_type_conditioned_fetching: false

`fleet_detector`

YAML

fleet_detector

1fleet_detector: {}

`forbid_mutations`

YAML

forbid_mutations

1forbid_mutations: false

`headers`

YAML

headers

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

Learn more in Sending HTTP headers to subgraphs.

`health_check`

YAML

health_check

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

Learn more in Health Checks.

`homepage`

YAML

homepage

1homepage:
2  enabled: true
3  graph_ref: null

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

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

YAML

router.yaml

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

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

`include_subgraph_errors`

YAML

include_subgraph_errors

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

`limits`

YAML

limits

1limits:
2  connector:
3    all:
4      http_max_response_size: null
5    sources: {}
6  router:
7    http1_max_request_buf_size: null
8    http1_max_request_headers: null
9    http2_max_headers_list_bytes: null
10    http_max_request_bytes: 2000000
11    introspection_max_depth: true
12    max_aliases: null
13    max_depth: null
14    max_height: null
15    max_root_fields: null
16    max_recursive_selections: 10000000
17    parser_max_recursion: 500
18    parser_max_tokens: 15000
19    warn_only: false
20  subgraph:
21    all:
22      http_max_response_size: null
23    subgraphs: {}

Learn more in Request Limits.

`override_subgraph_url`

YAML

override_subgraph_url

1override_subgraph_url: {}

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

note

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

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

YAML

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

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

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

YAML

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

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

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

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

`persisted_queries`

YAML

persisted_queries

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

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

Learn more about safelisting with persisted queries.

`plugins`

YAML

plugins

1plugins: unknown_type_plugins

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

YAML

example-plugin-router.yaml

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

Learn more in Native Plugins for router.

`response_cache`

response_cache YAML snippet

YAML

response_cache.router.yaml

1response_cache:
2  enabled: false
3  debug: false
4  include_cache_control_header_on_router_response: true # set to false to suppress Cache-Control header on client responses
5  private_queries_buffer_size: 2048
6  invalidation:
7    listen: 127.0.0.1:4000
8    path: /invalidation
9  cdn_invalidation:
10    enabled: false
11    header_name: Cache-Tag
12    header_delimiter: ','
13    max_bytes: 16384
14    experimental_on_overflow: truncate
15  subgraph:
16    all:
17      enabled: true
18      ttl: 30s
19      private_id: null
20      redis:
21        urls:
22        - redis://127.0.0.1:6379
23        username: example_username
24        password: example_password
25        fetch_timeout: 150ms
26        insert_timeout: 500ms
27        invalidate_timeout: 1s
28        maintenance_timeout: 500ms
29        namespace: example_namespace
30        tls:
31          certificate_authorities: null
32          client_authentication:
33            certificate_chain: example_certificate_chain
34            key: example_key
35        required_to_start: false
36        pool_size: 5
37        metrics_interval: 1s
38      invalidation:
39        enabled: false
40        shared_key: ''
41    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        max_overhead_size: example_max_overhead_size
10        operation_body_timeout: 30s
11      mode: stream

Learn more in File Uploads.

`reload`

YAML

router.yaml

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

Learn more about configuring reload retries.

`rhai`

YAML

rhai

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

Learn more in Rhai customization for router.

`sandbox`

YAML

sandbox

1sandbox:
2  enabled: false

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

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

YAML

router.yaml

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

caution

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

Learn more in Apollo Sandbox.

`server`

YAML

server

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

Header Read Timeout

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

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

TLS handshake timeout

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

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

`subscription`

YAML

subscription

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

Learn more in Subscriptions.

`supergraph`

supergraph YAML snippet

YAML

supergraph

1supergraph:
2  defer_support: true
3  early_cancel: false
4  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    incremental_planner:
35      enabled: false
36      beam_width: 16
37      fuel: 5000
38      timeout: null
39    warmed_up_queries: null
40  strict_variable_validation: enforce

Supergraph listen address

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

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

IPv4

YAML

router.yaml

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

IPv6

YAML

router.yaml

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

Unix socket

YAML

router_unix.yaml

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

note

Listening on a Unix socket is not supported on Windows.

Supergraph endpoint path

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

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

YAML

router.yaml

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

The path must start with /.

A path can contain parameters and wildcards:

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

note

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

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

Introspection

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

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

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

YAML

router.yaml

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

Introspection recursion limit

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

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

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

YAML

router.yaml

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

Redacting query validation errors

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

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

YAML

router.yaml

1supergraph:
2  redact_query_validation_errors: true

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

JSON

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

note

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

Early cancel

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

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

YAML

1supergraph:
2  early_cancel: true

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

YAML

router.yaml

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

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

YAML

telemetry

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

Enhanced operation signature normalization

Requires ≥ Router v1.49.0

note

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

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.

In Router 2.x and above, enhanced operation signature normalization is enabled by default. To configure the normalization algorithm, update telemetry.apollo.signature_normalization_algorithm in router.yaml:

YAML

router.yaml

1telemetry:
2  apollo:
3    signature_normalization_algorithm: enhanced # Default is `enhanced`; disable by setting to `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 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.extended_error_metrics option. It is enabled by default; to opt out, set it to disabled:

YAML

router.yaml

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

Learn more about GraphOS extended error reporting.

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 standard 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. Standard reporting can also cause inaccurate operation checks.

Configure reference reporting by updating telemetry.apollo.metrics_reference_mode in router.yaml:

YAML

router.yaml

1telemetry:
2  apollo:
3    metrics_reference_mode: extended # Default is `extended`; disable by setting to `standard`

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    http2: enable
7    experimental_http2_keep_alive_interval: null
8    experimental_http2_keep_alive_timeout: null
9    global_rate_limit:
10      capacity: 1
11      interval: 30s
12    timeout: null
13  connector:
14    all:
15      compression: gzip
16      dns_resolution_strategy: ipv4_only
17      experimental_http2: enable
18      experimental_http2_keep_alive_interval: null
19      experimental_http2_keep_alive_timeout: null
20      global_rate_limit:
21        capacity: 1
22        interval: 30s
23      timeout: null
24    sources: {}
25  deduplicate_variables: null
26  router:
27    concurrency_limit: 0
28    global_rate_limit:
29      capacity: 1
30      interval: 30s
31    timeout: null
32  subgraphs: {}

Learn more in Traffic Shaping.

YAML configuration utilities

Variable expansion

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

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

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

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

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

Reusing configurations with YAML aliases

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

YAML

router.yaml

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

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

Escaping special characters

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

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

Checklist for configuring the router for production

Give FeedbackFeedback

Edit on GitHub

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

Jaeger

Dynatrace

HTTP Callback Best Practices

Security

Authentication

Observability

Studio Insights

Router Telemetry (OTEL)

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

Jaeger

Dynatrace

Performance and Scaling

Response Caching

Client Features

GraphQL Subscriptions

HTTP Callback Best Practices

Query Planning

Customization

Coprocessors

Rhai Scripts

Custom Builds

Docker

Kubernetes

AWS

Azure

GCP

Managed Hosting

Tools

Router YAML Configuration Reference

YAML configuration properties

Example YAML with all properties

Properties

apq

authentication

authorization

batching

connectors

coprocessor

cors

csrf

demand_control

experimental_hoist_orphan_errors

experimental_type_conditioned_fetching

fleet_detector

forbid_mutations

headers

health_check

homepage

include_subgraph_errors

`apq`

`authentication`

`authorization`

`batching`

`connectors`

`coprocessor`

`cors`

`csrf`

`demand_control`

`experimental_hoist_orphan_errors`

`experimental_type_conditioned_fetching`

`fleet_detector`

`forbid_mutations`

`headers`

`health_check`

`homepage`

`include_subgraph_errors`

`limits`

`override_subgraph_url`

`persisted_queries`

`plugins`

`response_cache`

`preview_file_uploads`

`reload`

`rhai`

`sandbox`

`server`

`subscription`

`supergraph`

`telemetry`

`tls`

`traffic_shaping`