Update GraphQL Recommended vs Opt-In requirements

[abernix]

Fixes #2985

Changes

Changes the firmness for graphql.document from Recommended to Opt-In.

Context

The graphql.document is user-inputted, often contains sensitive information, is potentially unbounded in length and is also high-cardinality in the same way as the existing graphql.operation.name (which is already warned about).

Put another way, graphql.document is a general liability to have listed as Recommended without serious infrastructure considerations and needs. This makes it a better candidate for being an Opt-In attribute. In our customer adoption of OpenTelemetry and GraphQL, we've found GraphQL customers following this configuration/instruction purely based on its naming in this (still, experimental) specification and not understanding the implications (or just not thinking them through).

In most all cases, the lesser liability of graphql.operation.name (The actual operation name) is sufficient, as in many GraphQL deployments there is a link between the two which can be correlated out of band (e.g., client code-bases, operation manifests, etc.). While the operation name isn't without its risk, but it's more likely to be dozens of bytes of a limited character set rather than dozens, hundreds or potentially thousands of kilobytes. In that regard, it's reasonable that graphql.operation.name be left as Recommended for user experience (though the argument could easily be made that it should also be Opt-In).

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• Links to the prototypes or existing instrumentations (when adding or changing conventions)

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: abernix / name: Jesse Rosenberger (05695a8)

[joaopgrassi]

Note you will have to change the model file, and then generate the update commands. The markdown is not to be modified manually.

Also, consider adding a note to the opt_in explaining the rationaly. See an example here:

semantic-conventions/model/http/spans.yaml

Line 130 in 2e68756

requirement_level: opt_in

[github-actions]

This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:

• graphql

Such changes may be rejected or put on hold until a new SIG/project is established.

Please refer to the Semantic Convention Areas
document to see the current active SIGs and also to learn how to kick start a new one.

[abernix]

Note you will have to change the model file, and then generate the update commands. The markdown is not to be modified manually.

Thanks! And sorry, I realized that just after I opened it and shortly after I signed the CLA, which was the first thing I wanted to tackle.

I'm not sure why this PR was just auto-closed though — do you have suggestions on that @joaopgrassi ?

[abernix]

@joaopgrassi It looks like some relatively new automation auto-closed this, so ping again on the above if you get a chance. I guess this needs triage:accepted:ready if you're willing to do that for this change. I recognize that would be outside of a SIG group's coverage if i'm understanding the state of graphql right now. I can see what it would look like to spin up that group, but would also prefer to decouple it from this change if at all possible! :)

[github-actions]

This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:

• graphql

Such changes may be rejected or put on hold until a new SIG/project is established.

Please refer to the Semantic Convention Areas
document to see the current active SIGs and also to learn how to kick start a new one.

[github-actions]

This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:

• graphql

Such changes may be rejected or put on hold until a new SIG/project is established.

Please refer to the Semantic Convention Areas
document to see the current active SIGs and also to learn how to kick start a new one.

[joaopgrassi]

Suggested change

	change_type: enhancement
	change_type: breaking

Right? because now it won't be recorded by default anymore.