v1.55.0-rc.1

1.55.0-rc.1

v1.55.0-rc.0

1.55.0-rc.0

v2.0.0-alpha.6

2.0.0-alpha.6

v1.54.0

🚀 Features

Add configurability of span attributes in logs (Issue #5540)

The router supports a new telemetry.exporters.logging.stdout.format.json.span_attributes option that enables you to choose a subset of all span attributes to display in your logs.

When span_attributes is specified, the router searches for the first attribute in its input list of span attributes from the root span to the current span and attaches it to the outermost JSON object for the log event. If you set the same attribute name for different spans at different levels, the router chooses the attributes of child spans before the attributes of parent spans.

For example, if you have spans that contains span_attr_1 attribute and you only want to display this span attribute:

telemetry:
  exporters:
     logging:
       stdout:
         enabled: true
         format: 
           json:
             display_span_list: false
             span_attributes:
               - span_attr_1

Example output with a list of spans:

{
  "timestamp": "2023-10-30T14:09:34.771388Z",
  "level": "INFO",
  "fields": {
    "event_attr_1": "event_attr_1",
    "event_attr_2": "event_attr_2"
  },
  "target": "event_target",
  "span_attr_1": "span_attr_1"
}

To learn more, go to span_attributes docs.
By @bnjjj in #5867

Add a histogram metric tracking evaluated query plans (PR #5875)

The router supports the new apollo.router.query_planning.plan.evaluated_plans histogram metric to track the number of evaluated query plans.

You can use it to help set an optimal supergraph.query_planning.experimental_plans_limit option that limits the number of query plans evaluated for a query and reduces the time spent planning.

By @Geal in #5875

🐛 Fixes

Fix Datadog sampling (PR #5788)

The router's Datadog exporter has been fixed so that traces are sampled as intended.

Previously, the Datadog exporter's context may not have been set correctly, causing traces to be undersampled.

By @BrynCooke & @bnjjj in #5788

📃 Configuration

General availability of Apollo usage report generation (#5807)

The router's Apollo usage report generation feature that was previously experimental is now generally available.

If you used its experimental configuration, you should migrate to the new configuration options:

• telemetry.apollo.experimental_apollo_metrics_reference_mode is now telemetry.apollo.metrics_reference_mode
• telemetry.apollo.experimental_apollo_signature_normalization_algorithm is now telemetry.apollo.signature_normalization_algorithm
• experimental_apollo_metrics_generation_mode has been removed because the Rust implementation (the default since router v1.49.0) is generating reports identical to the previous router-bridge implementation

The experimental configuration options are now deprecated. They are functional but will log warnings.

By @bonnici in #5807

Helm: Enable easier Kubernetes debugging with heaptrack (Issue #5789)

The router's Helm chart has been updated to help make debugging with heaptrack easier.

Previously, when debugging multiple Pods with heaptrack, all Pods wrote to the same file, so they'd overwrite each others' results. This issue has been fixed by adding a hostname to each output data file from heaptrack.

Also, the Helm chart now supports a restartPolicy that enables you to configure a Pod's restart policy. The default value of restartPolicy is Always (the same as the Kubernetes default).

By @cyberhck in #5850

📚 Documentation

Document OpenTelemetry information for operation limits (PR #5884)

The router's docs for operation limits now describe using telemetry to set operation limits and logging values.

By @andrewmcgivery in #5884

v1.54.0-rc.4

1.54.0-rc.4

v2.0.0-alpha.5

2.0.0-alpha.5

v1.54.0-rc.2

1.54.0-rc.2

v1.54.0-rc.1

1.54.0-rc.1

v1.54.0-rc.0

1.54.0-rc.0

v1.53.0

Important

If you have enabled Distributed query plan caching, this release changes the hashing algorithm used for the cache keys. On account of this, you should anticipate additional cache regeneration cost when updating between these versions while the new hashing algorithm comes into service.

🚀 Features

Support demand control directives (PR #5777)

⚠️ This is a GraphOS Router feature.

The router supports two new demand control directives, @cost and @listSize, that you can use to provide more accurate estimates of GraphQL operation costs to the router's demand control plugin.

Use the @cost directive to customize the weights of operation cost calculations, particularly for expensive resolvers.

type Product {
  id: ID!
  name: String
  expensiveField: Int @cost(weight: 20)
}

Use the @listSize directive to provide a more accurate estimate for the size of a specific list field, particularly for those that differ greatly from the global list size estimate.

type Magazine {
  # This is assumed to always return 5 items
  headlines: [Article] @listSize(assumedSize: 5)

  # This is estimated to return as many items as are requested by the parameter named "first"
  getPage(first: Int!, after: ID!): [Article]
    @listSize(slicingArguments: ["first"])
}

To learn more, go to Demand Control docs.

By @tninesling in #5777

General Availability (GA) of Demand Control (PR #5868)

Demand control in the router is now a generally available (GA) feature.

GA compatibility update: if you used demand control during its preview, to use it in GA you must update your configuration from preview_demand_control to demand_control.

To learn more, go to Demand Control docs.

By @tninesling in #5868

Enable native query planner to run in the background (PR #5790, PR #5811, PR #5771, PR #5860)

The router now schedules background jobs to run the native (Rust) query planner to compare its results to the legacy implementation. This helps ascertain its correctness before making a decision to switch entirely to it from the legacy query planner.

To learn more, go to Experimental Query Planner Mode docs.

The router continues to use the legacy query planner to plan and execute operations, so there is no effect on the hot path.

To disable running background comparisons with the native query planner, you can configure the router to enable only the legacy query planner:

experimental_query_planner_mode: legacy

By @SimonSapin in (PR #5790, PR #5811, PR #5771 PR #5860)

Add warnings for invalid configuration of custom telemetry (PR #5759)

The router now logs warnings when running with telemetry that may have invalid custom configurations.

For example, you may customize telemetry using invalid conditions or inaccessible statuses:

telemetry:
  instrumentation:
    events:
      subgraph:
        my.event:
          message: "Auditing Router Event"
          level: info
          on: request
          attributes:
            subgraph.response.status: code
              # Warning: should use selector for subgraph_name: true instead of comparing strings of subgraph_name and product
          condition:
            eq:
            - subgraph_name
            - product

Although the configuration is syntactically correct, its customization is invalid, and the router now outputs warnings for such invalid configurations.

By @bnjjj in #5759

Add V8 heap usage metrics (PR #5781)

The router supports new gauge metrics for tracking heap memory usage of the V8 Javascript engine:

• apollo.router.v8.heap.used: heap memory used by V8, in bytes
• apollo.router.v8.heap.total: total heap allocated by V8, in bytes

By @Geal in #5781

Update Federation to v2.9.0 (PR #5902)

This updates the router to Federation v2.9.0.

By @tninesling in #5902

Helm: Support maxSurge and maxUnavailable for rolling updates (Issue #5664)

The router Helm chart now supports the configuration of maxSurge and maxUnavailable for the RollingUpdate deployment strategy.

By @theJC in #5665

Support new telemetry trace ID format (PR #5735)

The router supports a new UUID format for telemetry trace IDs.

The following formats are supported in router configuration for trace IDs:

• open_telemetry
• hexadecimal (same as opentelemetry)
• decimal
• datadog
• uuid (may contain dashes)

You can configure router logging to display the formatted trace ID with display_trace_id:

 telemetry:
  exporters:
    logging:
      stdout:
        format:
          json:
            display_trace_id: (true|false|open_telemetry|hexadecimal|decimal|datadog|uuid)

By @bnjjj in #5735

Add format for trace ID propagation. (PR #5803)

The router now supports specifying the format of trace IDs that are propagated to subgraphs via headers.

You can configure the format with the format option:

telemetry:
  exporters:
    tracing:
      propagation:
        request:
          header_name: "my_header"
          # Must be in UUID form, with or without dashes
          format: uuid

Note that incoming requests must be some form of UUID, either with or without dashes.

To learn about supported formats, go to request configuration reference docs.

By @BrynCooke in #5803

New apollo.router.cache.storage.estimated_size gauge (PR #5770)

The router supports the new metric apollo.router.cache.storage.estimated_size that helps users understand and monitor the amount of memory that query planner cache entries consume.

The apollo.router.cache.storage.estimated_size metric gives an estimated size in bytes of a cache entry. It has the following attributes:

• kind: query planner.
• storage: memory.

Before using the estimate to decide whether to update the cache, users should validate that the estimate correlates with their pod's memory usage.

To learn how to troubleshoot with this metric, see the Pods terminating due to memory pressure guide in docs.

By @BrynCooke in #5770

🐛 Fixes

Fix GraphQL query directives validation bug (PR #5753)

The router now supports GraphQL queries where a variable is used in a directive on the same operation where the variable is declared.

For example, the following query both declares and uses $var:

query GetSomething(: Int!) @someDirective(argument: $var) {
  something
}

By @goto-bus-stop in #5753

Evaluate selectors in response stage when possible (PR #5725)

The router now supports having various supergraph selectors on response events.

Because events are triggered at a specific event (request|response|error), you usually have only one condition for a related event. You can however have selectors that can be applied to several events, like subgraph_name to get the subgraph name).

Example of an event to log the raw subgraph response only on a subgraph named products, this was not working before.

telemetry:
  instrumentation:
    events:
      subgraph:
        response:
          level: info
          condition:
            eq:
            - subgraph_name: true
            - "products"

By @bnjjj in #5725

Fix trace propagation via header (PR #5802)

The router now correctly propagates trace IDs when using the propagation.request.header_name configuration option.

telemetry:
  exporters:
    tracing:
      propagation:
        request:
          header_name: "id_from_header"

Previously, trace IDs weren't transferred to the root span of the ...