Federated tracing

[cappuc]

Resolves #2053
Resolves #2068

• Added or updated tests
• Documented user facing changes
• Updated CHANGELOG.md

Changes

This PR adds support for Apollo Federated tracing.

I used the apollo server implementation as reference.

Error reporting

Federated tracing spec supports errors reporting but we need to decide how to implement this feature in order to prevent exposing sensitive data (without user control), right now there is no setting for this.

Apollo server has this options:

• mask error (default)
• include the full error
• transform the error with a callback

Here the docs and implementation

Breaking changes

None. the old tracing implementation is enabled by default.
This new implementation must be manually enabled through config.

Some notes

The new tracing spec uses protobuf and the updated of the proto file is manual:

• copy the reports.proto file from the apollo-server repo
• remove the js specific directives (for example: [(js_use_toArray)=true] and [(js_preEncoded)=true]
• add the php options:

  option php_namespace = "Nuwave\\Lighthouse\\Tracing\\FederatedTracing\\Proto";
  option php_metadata_namespace = "Nuwave\\Lighthouse\\Tracing\\FederatedTracing\\Proto\\Metadata";

Then run make:proto and make:fix to generate (and fix sytle) the protobuf classes

[cappuc]

I've extracted the ftv1 string to a constant and replaced it inside the driver and in the headers value of the tests.

I'm not sure it is a good idea to replace it in the test assertions too because it should be replaced event in calls like $response->json('extensions.ftv1') if we want to always use the constant and I think it is worst for readability.

I also renamed the value of the config to federated-tracing so it is not confused with the header/extension value.

[spawnia]

Let's document the process for generating/updating the proto files in CONTRIBUTING.md at least. Preferrably, I would like to automate the process through GitHub actions.

[cappuc]

The workflow should work but I couldn't get it to work on pull request (the main problem is the commit part).
I enabled it only on push like the format workflow

[cappuc]

I've added a workflow to automatically update the reports.proto file from apollo. I set it to run weekly

[spawnia]

Apart from adding the changelog entry and updating the docs to say that federated tracing is supported, I am fine to go ahead and merge this. Excellent work!

Do you plan on updating the Apollo compatibility repository as well? I think we should just need to change tracing.driver in the configuration to make the example project there work?

[cappuc]

We should take a look at error reporting (I wrote some notes in the first comment).

Apart from that and changelog/docs update it, everything should be fine.

Yes I think the only required change for apollo compatibility is the change of tracing.driver. I will make a PR to update apollo compatibility when this PR is merged.

[spawnia]

I am not sure how error reporting in tracing is/should be different from error reporting for clients. Does https://lighthouse-php.com/master/digging-deeper/error-handling.html apply? It would be nice to keep things simple and just utilize the same mechanisms. See \Nuwave\Lighthouse\GraphQL::errorsHandler().

[cappuc]

Yes it apply all handlers.
I just changed the message to be "Internal server error" when error is not client safe and removed the json data, so we provide only message and location

[spawnia]

Ready to merge and release?

[cappuc]

Yes, I think it's ready

[cappuc]

Opened the PR to update the apollo compatibility

[Maxwell2022]

We need to update the doc too: https://lighthouse-php.com/6/federation/getting-started.html#federated-tracing

Experimental: not enabled by default, not guaranteed to be stable.

Is this still experimental?