Upgrading from Versions 1.x

Learn how to upgrade your GraphOS Router deployment from version 1.x to 2.x.

New configuration in GraphOS Router v2.0.0-preview.x

The router v2.x introduces some new features that can impact the configuration from v1.x.

Apollo operation usage reporting via OTLP

The router supports reporting operation usage metrics to GraphOS via OpenTelemetry Protocol (OTLP).

Prior to version 1.49.0 of the router, all GraphOS reporting was performed using a private tracing format. In v1.49.0, we introduced support for using OTel to perform this reporting. In v1.x, this is controlled using the experimental_otlp_tracing_sampler flag, and it's off by default.

Now in v2.x, this flag is renamed to otlp_tracing_sampler, and it's enabled by default.

Learn more about configuring usage reporting via OTLP.

Metrics reporting defaults

Default values of some GraphOS reporting metrics have been changed from v1.x to the following in v2.x:

• telemetry.apollo.signature_normalization_algorithm now defaults to enhanced. (In v1.x the default is legacy.)

• telemetry.apollo.metrics_reference_mode now defaults to extended. (In v1.x the default is standard.)

Removed features in GraphOS Router v2.x

Support for Scaffold

In Router v1.x Scaffold could be used to generate boilerplate source code for a Rust Plugin which extended functionality in a custom Router. This facility has been removed.

Source code generated using Scaffold will continue to compile; so existing Rust plugins will be unaffected by this change.

--apollo-uplink-poll-interval

The router no longer uses the --apollo-uplink-poll-interval command-line argument, or the APOLLO_UPLINK_POLL_INTERVAL environment variable. It already did something unusual in v1.x: the configured interval would only be used for the very first poll, and not any subsequent polls.

Upgrading to GraphOS Router v2.x

Upgrading from GraphOS Router v1.x to v2.x requires the following steps.

Configure your Apollo usage reporting protocol

If your router v1.x is configured with experimental_otlp_tracing_sampler, rename it to otlp_tracing_sampler.

To report operation usage metrics to GraphOS via OTLP, you can either remove your configuration of otlp_tracing_sampler and use its default value, or you can explicitly enable it by setting it to always_on or a sampling ratio.

Otherwise, to use the behavior of v1.x, turn off usage reporting via OTLP by setting otlp_tracing_sampler to always_off.

Configure metrics reporting defaults

If you plan to use the new metrics reporting defaults, then no changes are required.

Otherwise, to use the defaults from v1.x, set the following:

1telemetry:
2  apollo:
3    signature_normalization_algorithm: legacy
4    metrics_reference_mode: standard

Logging

If you used the experimental_when_header feature previously like this for example:

1telemetry:
2  exporters:
3    logging:
4      # If one of these headers matches we will log supergraph and subgraphs requests/responses
5      experimental_when_header: # REMOVED
6        - name: apollo-router-log-request
7          value: my_client
8          headers: true # default: false
9          body: true # default: false

This feature no longer exists and can be replaced with another one included in custom telemetry. Here is how you would configure custom telemetry to achieve the same result:

1telemetry:
2  instrumentation:
3    events:
4      router:
5        request: # Display router request log
6          level: info
7          condition:
8            eq:
9            - request_header: apollo-router-log-request
10            - my_client
11        response: # Display router response log
12          level: info
13          condition:
14            eq:
15            - request_header: apollo-router-log-request
16            - my_client
17      supergraph:
18        request: # Display supergraph request log
19          level: info
20          condition:
21            eq:
22            - request_header: apollo-router-log-request
23            - my_client
24        response:
25          level: info
26          condition:
27            eq:
28            - request_header: apollo-router-log-request
29            - my_client
30      subgraph:
31        request: # Display subgraph request log
32          level: info
33          condition:
34            eq:
35            - supergraph_request_header: apollo-router-log-request
36            - my_client
37        response: # Display subgraph response log
38          level: info
39          condition:
40            eq:
41            - supergraph_request_header: apollo-router-log-request
42            - my_client

Metrics

• apollo_router_http_request_retry_total has been removed and will be supported now by http.client.request.duration metrics with the http.request.resend_count attribute which is automatically set when default_requirement_level is set to recommended.

• apollo_router_timeout has been removed. This metric conflated timed-out requests from client to the router, and requests from the router to subgraphs. Timed-out requests have HTTP status code 504. Use the http.response.status_code attribute on the http.server.request.duration metric to identify timed-out router requests, and the same attribute on the http.client.request.duration metric to identify timed-out subgraph requests.

• apollo_router_http_requests_total has been removed and replaced by http.server.request.duration metric for requests from clients to router and http.client.request.duration for requests from router to subgraphs.

• apollo_router_http_request_duration_seconds_bucket has been removed and replaced by http.server.request.duration metric for requests from clients to router and http.client.request.duration for requests from router to subgraphs.

• apollo_router_session_count_total has been removed and replaced by http.server.active_requests.

Check CORS configuration

If you already configured CORS on the router, the configuration won't change but with v1.x it accepted bad configuration and displayed an error log when some header names or regexes were invalid. With v2.x it will end up with an error and it won't start at all to avoid confusions and misconfigurations.

Deploy your router

Make sure that you are referencing the correct router release: v2.0.0-preview.0

During upgrade, carefully monitor logs and resource consumption to ensure that your router has successfully upgraded and that your router has enough resources to perform as expected. The router will automatically migrate required configuration changes, but it is good practice to review the steps above and decide if you want to change your configuration.

For example, you may decide that you wish to change the way in which you sample OTLP traces in this new release and not simply preserve your existing configuration.

Reporting upgrade issues

If you encounter an upgrade issue that isn't resolved by this article, please search for existing GitHub discussions and start a new discussion if you don't find what you're looking for.