apollographql · bonnici · Apr 3, 2025 · Apr 3, 2025 · Apr 4, 2025 · Apr 4, 2025
@@ -0,0 +1,5 @@
+### Brief but complete sentence that stands on its own ([PR #7166](https://github.com/apollographql/router/pull/7166))
+
+Enables reporting of persisted query usage by PQ ID to Apollo.
+
+By [@bonnici](https://github.com/bonnici) in https://github.com/apollographql/router/pull/7166
@@ -28,6 +28,7 @@ use apollo_compiler::schema::ExtendedType;
 use apollo_compiler::validation::Valid;
 use serde::Deserialize;
 use serde::Serialize;
+use sha2::Digest;
 
 use crate::json_ext::Object;
 use crate::json_ext::Value as JsonValue;
@@ -165,15 +166,97 @@ impl AddAssign<ReferencedEnums> for AggregatedExtendedReferenceStats {
 #[derive(Deserialize, Serialize, Debug, PartialEq, Eq, Clone)]
 #[serde(rename_all = "camelCase")]
 pub(crate) struct UsageReporting {
-    /// The `stats_report_key` is a unique identifier derived from schema and query.
-    /// Metric data  sent to Studio must be aggregated
-    /// via grouped key of (`client_name`, `client_version`, `stats_report_key`).
-    pub(crate) stats_report_key: String,
+    /// The operation name, or None if there is no operation name
+    pub(crate) operation_name: Option<String>,
+    /// The normalized operation signature, or None if there is no valid signature
+    pub(crate) operation_signature: Option<String>,
+    /// The error key to use for the stats report, or None if there is no error
+    pub(crate) error_key: Option<String>,
+    /// The persisted query ID used to request this operation, or None if the query was not requested via PQ ID
+    pub(crate) pq_id: Option<String>,
     /// a list of all types and fields referenced in the query
     #[serde(default)]
     pub(crate) referenced_fields_by_type: HashMap<String, ReferencedFieldsForType>,
 }
 
+impl UsageReporting {
+    pub(crate) fn for_error(error_key: String) -> UsageReporting {
+        UsageReporting {
+            operation_name: None,
+            operation_signature: None,
+            error_key: Some(error_key),
+            pq_id: None,
+            referenced_fields_by_type: HashMap::new(),
+        }
+    }
+
+    pub(crate) fn with_pq_id(&self, pq_id: Option<String>) -> UsageReporting {
+        let mut updated_usage_report = self.clone();
+        updated_usage_report.pq_id = pq_id;
+        updated_usage_report
+    }
+
+    /// The `stats_report_key` is a unique identifier derived from schema and query.
+    /// Metric data sent to Studio must be aggregated
+    /// via grouped key of (`client_name`, `client_version`, `stats_report_key`).
+    /// For errors, the report key is of the form "## <error name>\n".
+    /// For operations requested by PQ, the report key is of the form "pq# <pq id>".
+    /// For operations not requested by PQ, the report key is of the form "# <op name>\n<op sig>".
+    /// Note that this combination of operation name and signature is sometimes referred to in code as
+    /// "operation signature" even though it also contains the operation name as the first line.
+    pub(crate) fn get_stats_report_key(&self) -> String {
+        if let Some(error_key) = &self.error_key {
+            format!("## {}\n", error_key)
+        } else if let Some(persisted_query_id) = &self.pq_id {
+            format!("pq# {}", persisted_query_id)
+        } else {
+            let stats_report_key_op_name =
+                self.operation_name.as_deref().unwrap_or("-").to_string();
+            format!(
+                "# {}\n{}",
+                stats_report_key_op_name,
+                self.get_operation_signature()
+            )
+        }
+    }
+
+    pub(crate) fn get_operation_signature(&self) -> String {
+        self.operation_signature
+            .as_deref()
+            .unwrap_or("")
+            .to_string()
+    }
+
+    pub(crate) fn get_operation_id(&self) -> String {
+        let sig_to_hash = if self.error_key.is_some() {
+            // To match the logic of Apollo's error key handling, we need to handle error keys specially.
+            // The correct string to hash in this case is e.g. "# # GraphQLParseFailure\n".
+            format!("# # {}\n", self.error_key.as_ref().unwrap())
+        } else {
+            self.get_stats_report_key()
+        };
+
+        let mut hasher = sha1::Sha1::new();
+        hasher.update(sig_to_hash.as_bytes());
+        let result = hasher.finalize();
+        hex::encode(result)
+    }
+
+    pub(crate) fn get_operation_name(&self) -> String {
+        if let Some(op_name) = &self.operation_name {
+            op_name.clone()
+        } else if let Some(err_key) = &self.error_key {
+            format!("# {}", err_key)
+        } else {
+            "".to_string()
+        }
+    }
+
+    pub(crate) fn is_error(&self) -> bool {
+        self.error_key.is_some()
+    }
+}
+
 /// A list of fields that will be resolved for a given type
 #[derive(Deserialize, Serialize, Debug, PartialEq, Eq, Clone)]
 #[serde(rename_all = "camelCase")]
@@ -186,9 +269,10 @@ pub(crate) struct ReferencedFieldsForType {
     pub(crate) is_interface: bool,
 }
 
-/// Generate a UsageReporting containing the stats_report_key (a normalized version of the operation signature)
-/// and referenced fields of an operation. The document used to generate the signature and for the references can be
-/// different to handle cases where the operation has been filtered, but we want to keep the same signature.
+/// Generate a UsageReporting containing the data required to generate a stats_report_key (either a normalized version of
+/// the operation signature or an error key or a PQ ID) and referenced fields of an operation. The document used to
+/// generate the signature and for the references can be different to handle cases where the operation has been filtered,
+/// but we want to keep the same signature.
 pub(crate) fn generate_usage_reporting(
     signature_doc: &ExecutableDocument,
     references_doc: &ExecutableDocument,
@@ -362,12 +446,23 @@ struct UsageGenerator<'a> {
 impl UsageGenerator<'_> {
     fn generate_usage_reporting(&mut self) -> UsageReporting {
         UsageReporting {
-            stats_report_key: self.generate_stats_report_key(),
+            operation_name: self.get_operation_name(),
+            operation_signature: self.generate_normalized_signature(),
+            error_key: None,
+            pq_id: None,
             referenced_fields_by_type: self.generate_apollo_reporting_refs(),
         }
     }
 
-    fn generate_stats_report_key(&mut self) -> String {
+    fn get_operation_name(&self) -> Option<String> {
+        self.signature_doc
+            .operations
+            .get(self.operation_name.as_deref())
+            .ok()
+            .and_then(|operation| operation.name.as_ref().map(|node| node.to_string()))
+    }
+
+    fn generate_normalized_signature(&mut self) -> Option<String> {
         self.fragments_map.clear();
 
         match self
@@ -376,10 +471,10 @@ impl UsageGenerator<'_> {
             .get(self.operation_name.as_deref())
             .ok()
         {
-            None => "".to_string(),
+            None => None,
             Some(operation) => {
                 self.extract_signature_fragments(&operation.selection_set);
-                self.format_operation_for_report(operation)
+                Some(self.format_operation_signature_for_report(operation))
             }
         }
     }
@@ -410,15 +505,10 @@ impl UsageGenerator<'_> {
         }
     }
 
-    fn format_operation_for_report(&self, operation: &Node<Operation>) -> String {
-        // The result in the name of the operation
-        let op_name = match &operation.name {
-            None => "-".into(),
-            Some(node) => node.to_string(),
-        };
-        let mut result = format!("# {}\n", op_name);
+    fn format_operation_signature_for_report(&self, operation: &Node<Operation>) -> String {
+        let mut result = String::new();
 
-        // Followed by a sorted list of fragments
+        // The signature starts with a sorted list of fragments
         let mut sorted_fragments: Vec<_> = self.fragments_map.iter().collect();
         sorted_fragments.sort_by_key(|&(k, _)| k);
 

@@ -5,7 +5,7 @@ use super::*;
 use crate::Configuration;
 
 fn assert_expected_signature(actual: &UsageReporting, expected_sig: &str) {
-    assert_eq!(actual.stats_report_key, expected_sig);
+    assert_eq!(actual.get_stats_report_key(), expected_sig);
 }
 
 macro_rules! assert_extended_references {
@@ -300,3 +300,115 @@ async fn test_enums_from_response_fragments() {
     let generated = enums_from_response(query_str, op_name, schema_str, response_str);
     assert_enums_from_response!(&generated);
 }
+
+#[test]
+fn apollo_operation_id_hash() {
+    let usage_reporting = UsageReporting {
+        operation_name: Some("IgnitionMeQuery".to_string()),
+        operation_signature: Some("query IgnitionMeQuery{me{id}}".to_string()),
+        error_key: None,
+        pq_id: None,
+        referenced_fields_by_type: HashMap::new(),
+    };
+
+    assert_eq!(
+        "d1554552698157b05c2a462827fb4367a4548ee5",
+        usage_reporting.get_operation_id()
+    );
+}
+
+// The Apollo operation ID hash for these errors is based on a slightly different string. E.g. instead of hashing
+// "## GraphQLValidationFailure\n" we should hash "# # GraphQLValidationFailure".
+#[test]
+fn apollo_error_operation_id_hash() {
+    assert_eq!(
+        "ea4f152696abedca148b016d72df48842b713697",
+        UsageReporting::for_error("GraphQLValidationFailure".into()).get_operation_id()
+    );
+    assert_eq!(
+        "3f410834f13153f401ffe73f7e454aa500d10bf7",
+        UsageReporting::for_error("GraphQLParseFailure".into()).get_operation_id()
+    );
+    assert_eq!(
+        "7486043da2085fed407d942508a572ef88dc8120",
+        UsageReporting::for_error("GraphQLUnknownOperationName".into()).get_operation_id()
+    );
+}
+
+#[test]
+fn test_get_stats_report_key() {
+    let usage_reporting_for_errors = UsageReporting::for_error("GraphQLParseFailure".into());
+    assert_eq!(
+        "## GraphQLParseFailure\n",
+        usage_reporting_for_errors.get_stats_report_key()
+    );
+
+    let usage_reporting_for_pq = UsageReporting {
+        operation_name: Some("SomeQuery".into()),
+        operation_signature: Some("query SomeQuery{thing{id}}".into()),
+        error_key: None,
+        pq_id: Some("SomePqId".into()),
+        referenced_fields_by_type: HashMap::new(),
+    };
+    assert_eq!(
+        "pq# SomePqId",
+        usage_reporting_for_pq.get_stats_report_key()
+    );
+
+    let usage_reporting_for_named_operation = UsageReporting {
+        operation_name: Some("SomeQuery".into()),
+        operation_signature: Some("query SomeQuery{thing{id}}".into()),
+        error_key: None,
+        pq_id: None,
+        referenced_fields_by_type: HashMap::new(),
+    };
+    assert_eq!(
+        "# SomeQuery\nquery SomeQuery{thing{id}}",
+        usage_reporting_for_named_operation.get_stats_report_key()
+    );
+
+    let usage_reporting_for_unnamed_operation = UsageReporting {
+        operation_name: None,
+        operation_signature: Some("query{thing{id}}".into()),
+        error_key: None,
+        pq_id: None,
+        referenced_fields_by_type: HashMap::new(),
+    };
+    assert_eq!(
+        "# -\nquery{thing{id}}",
+        usage_reporting_for_unnamed_operation.get_stats_report_key()
+    );
+}
+
+#[test]
+fn test_get_operation_name() {
+    let usage_reporting_for_errors = UsageReporting::for_error("GraphQLParseFailure".into());
+    assert_eq!(
+        "# GraphQLParseFailure",
+        usage_reporting_for_errors.get_operation_name()
+    );
+
+    let usage_reporting_for_named_operation = UsageReporting {
+        operation_name: Some("SomeQuery".into()),
+        operation_signature: Some("query SomeQuery{thing{id}}".into()),
+        error_key: None,
+        pq_id: None,
+        referenced_fields_by_type: HashMap::new(),
+    };
+    assert_eq!(
+        "SomeQuery",
+        usage_reporting_for_named_operation.get_operation_name()
+    );
+
+    let usage_reporting_for_unnamed_operation = UsageReporting {
+        operation_name: None,
+        operation_signature: Some("query{thing{id}}".into()),
+        error_key: None,
+        pq_id: None,
+        referenced_fields_by_type: HashMap::new(),
+    };
+    assert_eq!(
+        "",
+        usage_reporting_for_unnamed_operation.get_operation_name()
+    );
+}
@@ -1,5 +1,4 @@
 //! Router errors.
-use std::collections::HashMap;
 use std::ops::Deref;
 use std::sync::Arc;
 
@@ -271,7 +270,7 @@ pub(crate) enum QueryPlannerError {
     JoinError(String),
 
     /// empty query plan. This behavior is unexpected and we suggest opening an issue to apollographql/router with a reproduction.
-    EmptyPlan(UsageReporting), // usage_reporting_signature
+    EmptyPlan(String), // usage_reporting stats_report_key
 
     /// unhandled planner result
     UnhandledPlannerResult,
@@ -434,10 +433,9 @@ impl IntoGraphQLErrors for QueryPlannerError {
 impl QueryPlannerError {
     pub(crate) fn usage_reporting(&self) -> Option<UsageReporting> {
         match self {
-            QueryPlannerError::SpecError(e) => Some(UsageReporting {
-                stats_report_key: e.get_error_key().to_string(),
-                referenced_fields_by_type: HashMap::new(),
-            }),
+            QueryPlannerError::SpecError(e) => {
+                Some(UsageReporting::for_error(e.get_error_key().to_string()))
+            }
             _ => None,
         }
     }

@@ -26,10 +26,6 @@ use crate::plugins::telemetry::CLIENT_VERSION;
 use crate::plugins::telemetry::apollo::ErrorsConfiguration;
 use crate::plugins::telemetry::apollo::ExtendedErrorMetricsMode;
 use crate::query_planner::APOLLO_OPERATION_ID;
-use crate::query_planner::stats_report_key_hash;
-use crate::spec::GRAPHQL_PARSE_FAILURE_ERROR_KEY;
-use crate::spec::GRAPHQL_UNKNOWN_OPERATION_NAME_ERROR_KEY;
-use crate::spec::GRAPHQL_VALIDATION_FAILURE_ERROR_KEY;
 
 pub(crate) mod aggregation;
 pub(crate) mod filter;
@@ -1297,30 +1293,19 @@ pub(crate) fn count_operation_errors(
     let client_name = unwrap_context_string(CLIENT_NAME);
     let client_version = unwrap_context_string(CLIENT_VERSION);
 
-    // Try to get operation ID from the stats report key if it's not in context (e.g. on parse/validation error)
-    if operation_id.is_empty() {
-        let maybe_stats_report_key = context.extensions().with_lock(|lock| {
-            lock.get::<Arc<UsageReporting>>()
-                .map(|u| u.stats_report_key.clone())
-        });
-        if let Some(stats_report_key) = maybe_stats_report_key {
-            operation_id = stats_report_key_hash(stats_report_key.as_str());
-
-            // If the operation name is empty, it's possible it's an error and we can populate the name by skipping the
-            // first character of the stats report key ("#") and the last newline character. E.g.
-            // "## GraphQLParseFailure\n" will turn into "# GraphQLParseFailure".
-            if operation_name.is_empty() {
-                operation_name = match stats_report_key.as_str() {
-                    GRAPHQL_PARSE_FAILURE_ERROR_KEY
-                    | GRAPHQL_UNKNOWN_OPERATION_NAME_ERROR_KEY
-                    | GRAPHQL_VALIDATION_FAILURE_ERROR_KEY => stats_report_key
-                        .chars()
-                        .skip(1)
-                        .take(stats_report_key.len() - 2)
-                        .collect(),
-                    _ => "".to_string(),
-                }
-            }
+    let maybe_usage_reporting = context
+        .extensions()
+        .with_lock(|lock| lock.get::<Arc<UsageReporting>>().cloned());
+
+    if let Some(usage_reporting) = maybe_usage_reporting {
+        // Try to get operation ID from usage reporting if it's not in context (e.g. on parse/validation error)
+        if operation_id.is_empty() {
+            operation_id = usage_reporting.get_operation_id();
+        }
+
+        // Also try to get operation name from usage reporting if it's not in context
+        if operation_name.is_empty() {
+            operation_name = usage_reporting.get_operation_name();
         }
     }