Docs
Launch GraphOS Studio

Operation signatures

Understand how GraphOS identifies equivalent operations


When you're viewing your 's operation metrics, groups based on the set of they include, not based on . That means that operations with the same name but different sets of fields are displayed separately:

Separate operations with same name in Studio

Though each in the above example is named MyQuery, treats them as different because they request different .

To help identify functionally identical , your generates an operation signature for each it reports to Studio. This signature is a normalized representation for an operation with deterministic order, whitespace, and values for in-line values.

Why do we need an operation signature?

Consider the following :

query GetPostDetails($postId: String!) {
post(id: $postId) {
author
content
}
}
query GetPostDetails($postId: String!) {
post(id: $postId) {
content # Different field order
author
}
}
query GetPostDetails($postId: String!) {
post(id: $postId) {
writer: author # Field alias
content
}
}

Despite some cosmetic differences (including comments), all these execute identically on a particular . Therefore, Studio should group them when displaying performance metrics.

Apollo libraries use a signature algorithm to generate the exact same for all these operations, allowing Studio to group them.

Signature algorithm

NOTE

This algorithm is subject to change. This article describes the signature algorithm as of the release of 3.6.1. It is provided here for informational purposes, not as a canonical specification.

Feel free to jump to an example or view the source.

The signature algorithm performs the following modifications on an to generate its signature:

1. Transform in-line argument values

If an includes any in-line values, the algorithm transforms those values according to their type:

  • Boolean and enum values are preserved.
  • Int and Float values are replaced with 0.
  • String, list, and object values are replaced with their "empty" counterpart ("", [], or {}).

NOTE

values provided as names are preserved.

2. Remove extraneous characters

The algorithm removes most unnecessary characters in the definition, including comments and redundant whitespace.

If the includes multiple operations, then operations besides the executed operation are removed.

If the includes that aren't used by the executed operation, then those fragments are removed (other fragments are preserved).

3. Reorder definitions

Any preserved definitions appear first, sorted alphanumerically by fragment name. The definition of the executed appears after all fragment definitions.

NOTE

Whenever the names of two sorted items are identical, the algorithm preserves the original order of those items relative to each other.

Fields

For a given object or 's , field selections are sorted in the following order:

  1. Individually listed s
  2. Named spreads
  3. In-line s

Within each of these, sorting is alphanumeric by name or name.

Field aliases

All are removed. If an includes three instances of the same field with different aliases, then that field is listed in the signature three times with its non-aliased name.

Directives and arguments

If multiple are applied to the same location in the , those directives are sorted alphanumerically.

If a single accepts multiple , those arguments are sorted alphanumerically by name.

Example signature

Consider this :

# Operation definition needs to appear after all fragment definitions
query GetUser {
user(id: "hello") {
# Replace string argument value with empty string
...NameParts # Spread fragment needs to appear after individual fields
timezone # Needs to appear alphanumerically after `name`
aliased: name # Need to remove alias
}
}
# Excessive characters (including this comment!) need to be removed
fragment NameParts on User {
firstname
lastname
}

The signature algorithm generates the following signature for this :

fragment NameParts on User {
firstname
lastname
}
query GetUser {
user(id: "") {
name
timezone
...NameParts
}
}

Signatures and sensitive data

The signature algorithm's primary purpose is to group that differ only cosmetically in terms of whitespace, order, , etc. As an additional effect, the algorithm does remove most in-line argument values, which, in theory, helps maintain data privacy.

However, you should not rely on this! Ideally, your sensitive data should never reach in the first place. Whenever possible, use GraphQL variables instead of in-line values for . This helps you control exactly which values are reported to Apollo. For details, see GraphOS Studio data privacy and compliance.

Logging signatures at runtime

To view hashes in your own logging tools, you can create an Apollo Server plugin that accesses hash values from the shared context. The relevant values are available in the queryHash and operationName properties:

index.ts
const logOperationSignaturePlugin = {
async requestDidStart() {
return {
async didResolveOperation(ctx) {
console.log({
queryHash: ctx.queryHash,
operationName: ctx.operationName,
});
},
};
},
};
const server = new ApolloServer({
schema,
plugins: [logOperationSignaturePlugin],
});
index.js
const logOperationSignaturePlugin = {
async requestDidStart() {
return {
async didResolveOperation(ctx) {
console.log({
queryHash: ctx.queryHash,
operationName: ctx.operationName,
});
},
};
},
};
const server = new ApolloServer({
schema,
plugins: [logOperationSignaturePlugin],
});
Previous
Sending metrics to GraphOS
Next
Datadog forwarding
Edit on GitHubEditForumsDiscord

© 2024 Apollo Graph Inc.

Privacy Policy

Company