Add semantic conventions for GraphQL (open-telemetry#2456)

Add semantic conventions for GraphQL span name and attributes.

Related issues open-telemetry#1670

CHANGELOG.md

@@ -23,6 +23,8 @@ release.
   ([#2602](https://github.com/open-telemetry/opentelemetry-specification/pull/2602)).
 - Adopt attribute requirement levels in semantic conventions
   ([#2594](https://github.com/open-telemetry/opentelemetry-specification/pull/2594))
+- Add semantic conventions for GraphQL
+  ([#2456](https://github.com/open-telemetry/opentelemetry-specification/pull/2456))
 
 ### Compatibility
 

semantic_conventions/trace/instrumentation/graphql.yml

@@ -0,0 +1,31 @@
+groups:
+  - id: graphql
+    prefix: graphql
+    brief: >
+      This document defines semantic conventions to apply when instrumenting the GraphQL implementation. They map
+      GraphQL operations to attributes on a Span.
+    attributes:
+      - id: operation.name
+        brief: "The name of the operation being executed."
+        type: string
+        examples: 'findBookById'
+      - id: operation.type
+        brief: "The type of the operation being executed."
+        type:
+          allow_custom_values: false
+          members:
+            - id: query
+              value: "query"
+              brief: "GraphQL query"
+            - id: mutation
+              value: "mutation"
+              brief: "GraphQL mutation"
+            - id: subscription
+              value: "subscription"
+              brief: "GraphQL subscription"
+        examples: ['query', 'mutation', 'subscription']
+      - id: document
+        brief: "The GraphQL document being executed."
+        type: string
+        note: The value may be sanitized to exclude sensitive information.
+        examples: 'query findBookById { bookById(id: ?) { name } }'

specification/trace/semantic_conventions/README.md

@@ -28,6 +28,7 @@ The following library-specific semantic conventions are defined:
 
 * [AWS Lambda](instrumentation/aws-lambda.md): For AWS Lambda spans.
 * [AWS SDK](instrumentation/aws-sdk.md): For AWS SDK spans.
+* [GraphQL](instrumentation/graphql.md): For GraphQL spans.
 
 Apart from semantic conventions for traces and [metrics](../../metrics/semantic_conventions/README.md),
 OpenTelemetry also defines the concept of overarching [Resources](../../resource/sdk.md) with their own

specification/trace/semantic_conventions/instrumentation/graphql.md

@@ -0,0 +1,29 @@
+# Semantic conventions for GraphQL Server
+
+**Status**: [Experimental](../../../document-status.md)
+
+This document defines semantic conventions to apply when instrumenting the GraphQL implementation. They map GraphQL
+operations to attributes on a Span.
+
+The **span name** MUST be of the format `<graphql.operation.type> <graphql.operation.name>` provided that
+`graphql.operation.type` and `graphql.operation.name` are available. If `graphql.operation.name` is not available, the
+span SHOULD be named `<graphql.operation.type>`. When `<graphql.operation.type>` is not available, `GraphQL Operation`
+MAY be used as span name.
+
+<!-- semconv graphql -->
+| Attribute  | Type | Description  | Examples  | Requirement Level |
+|---|---|---|---|---|
+| `graphql.operation.name` | string | The name of the operation being executed. | `findBookById` | Recommended |
+| `graphql.operation.type` | string | The type of the operation being executed. | `query`; `mutation`; `subscription` | Recommended |
+| `graphql.document` | string | The GraphQL document being executed. [1] | `query findBookById { bookById(id: ?) { name } }` | Recommended |
+
+**[1]:** The value may be sanitized to exclude sensitive information.
+
+`graphql.operation.type` MUST be one of the following:
+
+| Value  | Description |
+|---|---|
+| `query` | GraphQL query |
+| `mutation` | GraphQL mutation |
+| `subscription` | GraphQL subscription |
+<!-- endsemconv -->