Exposing the delegation plan for debugging purposes

[ardatan]

Exposing the delegation plan;

When you enable the environment variable, EXPOSE_DELEGATION_PLAN, you can see the delegation plan in the console. This can be useful for debugging and understanding how the delegation works.

Also you can pass a different logger to it by using logFnForContext map from @graphql-tools/delegate package.

import { logFnForContext } from '@graphql-tools/delegate';
logFnForContext.set(MyGraphQLContext, console.log);

You can also add a contextId for that specific gateway request by using contextIdMap map from @graphql-tools/delegate package.

import { contextIdMap } from '@graphql-tools/delegate';
contextIdMap.set(MyGraphQLContext, 'my-request-id');

If you want to use those information instead of logging, you can get them by using the context object like below;

import { delegationPlanInfosByContext } from '@graphql-tools/delegate';
const delegationPlanInfos = delegationPlanInfosByContext.get(context);

The idea of exposing it via the context is to get the information to be used in other other places. Maybe putting it under extensions here;
https://github.com/ardatan/graphql-mesh/pull/6940/files#diff-5e5874cf986f5d1deeda6bec95633e4d1f45d2b59a022fec7e9cfbf878698042R165

You can find a full exposed plan example here below;
https://github.com/ardatan/graphql-tools/pull/6145/files#diff-9fe42f557cff42c58e7076d60567a7b9fce3798fd0c5882148b8e2bb398332df

The structure of each plan is like;

  {
    "operationName": "TestQuery", # Main operation name
    "contextId": "MY_CONTEXT_IDENTIFIER", # This can be from `x-request-id` header
    "planId": "AAAA",  # Identifier for the plan
    "source": "reviews", # Source subgraph
    "type": "Product", # Return type
    "path": [ # Path of this delegation
      "users",
      "reviews",
      "product",
      "reviews",
      "author",
      "reviews",
      "product"
    ],
    "fieldNodes": [ # Expected final selection set
      "product {\n  ...Product\n}"
    ],
    "fragments": [
      "fragment User on User {\n  id\n  username\n  name\n}",
      "fragment Review on Review {\n  id\n  body\n}",
      "fragment Product on Product {\n  inStock\n  name\n  price\n  shippingEstimate\n  upc\n  weight\n}"
    ],
    # Called sequentially
    "stages": [
      {
        "stageId": "BBBBB",
        "delegations": [ # Called in parallel then merged
          {
            "target": "inventory",
            "selectionSet": "{\n  inStock\n}"
          },
          {
            "target": "products",
            "selectionSet": "{\n  name\n  price\n  price\n  weight\n  weight\n}"
          }
        ]
      },
      {
        "stageId": "CCCC",
        "delegations": [
          {
            "target": "inventory",
            "selectionSet": "{\n  shippingEstimate\n}"
          }
        ]
      }
    ]
  }

[changeset-bot]

🦋 Changeset detected

Latest commit: 7dadd93

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@graphql-tools/delegate	Patch
@graphql-tools/stitch	Patch
federation-benchmark	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

🚀 Snapshot Release (alpha)

The latest changes of this PR are available as alpha on npm (based on the declared changesets):

Package	Version	Info
@graphql-tools/delegate	10.0.10-alpha-20240506163946-7dadd9316f1972bf8b60a304e51d33014b74c0dc	npm ↗︎ unpkg ↗︎
@graphql-tools/stitch	9.2.8-alpha-20240506163946-7dadd9316f1972bf8b60a304e51d33014b74c0dc	npm ↗︎ unpkg ↗︎

[github-actions]

✅ Benchmark Results

     ✓ no_errors
     ✓ expected_result

     checks.........................: 100.00% ✓ 324       ✗ 0  
     data_received..................: 38 MB   3.7 MB/s
     data_sent......................: 139 kB  14 kB/s
     http_req_blocked...............: avg=4.95µs   min=2.23µs   med=2.98µs   max=275.33µs p(90)=4.15µs   p(95)=4.88µs  
     http_req_connecting............: avg=996ns    min=0s       med=0s       max=161.39µs p(90)=0s       p(95)=0s      
     http_req_duration..............: avg=57.8ms   min=49.63ms  med=54.15ms  max=155.19ms p(90)=61.72ms  p(95)=87.12ms 
       { expected_response:true }...: avg=57.8ms   min=49.63ms  med=54.15ms  max=155.19ms p(90)=61.72ms  p(95)=87.12ms 
     http_req_failed................: 0.00%   ✓ 0         ✗ 162
     http_req_receiving.............: avg=134.63µs min=105.23µs med=132.84µs max=337.55µs p(90)=147.95µs p(95)=153.43µs
     http_req_sending...............: avg=25.88µs  min=16.68µs  med=23.43µs  max=126.81µs p(90)=31.81µs  p(95)=35.11µs 
     http_req_tls_handshaking.......: avg=0s       min=0s       med=0s       max=0s       p(90)=0s       p(95)=0s      
     http_req_waiting...............: avg=57.64ms  min=49.46ms  med=53.99ms  max=154.72ms p(90)=61.54ms  p(95)=86.96ms 
     http_reqs......................: 162     16.104882/s
     iteration_duration.............: avg=62.05ms  min=53.16ms  med=58.42ms  max=159.81ms p(90)=67.9ms   p(95)=91.71ms 
     iterations.....................: 162     16.104882/s
     vus............................: 1       min=1       max=1
     vus_max........................: 1       min=1       max=1

[github-actions]

💻 Website Preview

The latest changes are available as preview in: https://0a93dcb5.graphql-tools.pages.dev

[enisdenjo]

Instead of logging to the console, can we (also) maybe provide the plan through graphql's execution result extensions?

[ardatan]

@enisdenjo Since Stitching uses the regular executor, I expose the plan with delegationPlanInfosByContext.
So we can get it in Mesh for example like here;
https://github.com/ardatan/graphql-mesh/pull/6940/files#diff-5e5874cf986f5d1deeda6bec95633e4d1f45d2b59a022fec7e9cfbf878698042R165

[enisdenjo]

If a plan has an ID, it should be stable and not random otherwise the ID is useless.

[EmrysMyrddin]

Perhaps this should also be a cli option instead of an env variable only ?

Cli options are easier to discover since they are documented into the help of the cli itself :-)