diff --git a/CHANGELOG.md b/CHANGELOG.md index a0072ed47ae..a942b463a63 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/semantic_conventions/trace/instrumentation/graphql.yml b/semantic_conventions/trace/instrumentation/graphql.yml new file mode 100644 index 00000000000..bb5de0e8278 --- /dev/null +++ b/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 } }' diff --git a/specification/trace/semantic_conventions/README.md b/specification/trace/semantic_conventions/README.md index 5fdb89716d9..34c54b40350 100644 --- a/specification/trace/semantic_conventions/README.md +++ b/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 diff --git a/specification/trace/semantic_conventions/instrumentation/graphql.md b/specification/trace/semantic_conventions/instrumentation/graphql.md new file mode 100644 index 00000000000..2a7e6107601 --- /dev/null +++ b/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 ` ` provided that +`graphql.operation.type` and `graphql.operation.name` are available. If `graphql.operation.name` is not available, the +span SHOULD be named ``. When `` is not available, `GraphQL Operation` +MAY be used as span name. + + +| 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 | +