Merge pull request #211 from observerr411/feat/tracing-span-parent-child

feat(tracing): add parent-child span hierarchy and get_trace function

Author: abore9769

src/contract.rs

@@ -89,6 +89,18 @@ pub struct TracingSpan {
     pub started_at: u64,
     pub completed_at: u64,
     pub status: String,
+    /// Raw bytes of the parent span's request_id.id, or empty Bytes if this is a root span.
+    pub parent_request_id_bytes: Bytes,
+    /// Zero-based index of this span within the trace, used for ordering.
+    pub span_index: u32,
+}
+
+/// Holds the root request ID bytes and the current span index counter for a trace.
+#[contracttype]
+#[derive(Clone)]
+pub struct TracingContext {
+    pub root_request_id_bytes: Bytes,
+    pub next_span_index: u32,
 }
 
 #[contracttype]
@@ -1024,6 +1036,93 @@ pub fn is_attestor(env: Env, attestor: Address) -> bool {
             .get::<_, TracingSpan>(&(symbol_short!("SPAN"), request_id_bytes))
     }
 
+    /// Create a child span under a parent span, setting parent_request_id and
+    /// incrementing the span_index from the TracingContext stored for the root.
+    ///
+    /// The TracingContext for the root must have been initialised by a prior
+    /// `submit_with_request_id` call (which stores span_index = 0).
+    pub fn propagate_span(
+        env: Env,
+        parent_request_id: RequestId,
+        child_request_id: RequestId,
+        operation: String,
+        actor: Address,
+    ) {
+        actor.require_auth();
+        let now = env.ledger().timestamp();
+
+        // Load or create the TracingContext for this root trace
+        let ctx_key = (symbol_short!("TRACECTX"), parent_request_id.id.clone());
+        let mut ctx: TracingContext = env
+            .storage()
+            .temporary()
+            .get(&ctx_key)
+            .unwrap_or(TracingContext {
+                root_request_id_bytes: parent_request_id.id.clone(),
+                next_span_index: 1,
+            });
+
+        let span_index = ctx.next_span_index;
+        ctx.next_span_index += 1;
+        env.storage().temporary().set(&ctx_key, &ctx);
+        env.storage().temporary().extend_ttl(&ctx_key, SPAN_TTL, SPAN_TTL);
+
+        // Register child span ID under the root so get_trace can find it
+        let child_list_key = (symbol_short!("TRACEIDS"), parent_request_id.id.clone(), span_index);
+        env.storage().temporary().set(&child_list_key, &child_request_id.id.clone());
+        env.storage().temporary().extend_ttl(&child_list_key, SPAN_TTL, SPAN_TTL);
+
+        Self::store_span_with_parent(
+            &env,
+            &child_request_id,
+            operation,
+            actor,
+            now,
+            String::from_str(&env, "success"),
+            parent_request_id.id.clone(),
+            span_index,
+        );
+    }
+
+    /// Retrieve all spans associated with a root request ID, ordered by span_index.
+    /// Returns the root span first, followed by child spans in creation order.
+    pub fn get_trace(env: Env, root_request_id_bytes: Bytes) -> Vec<TracingSpan> {
+        let mut spans = Vec::new(&env);
+
+        // Root span (span_index = 0)
+        if let Some(root_span) = env
+            .storage()
+            .temporary()
+            .get::<_, TracingSpan>(&(symbol_short!("SPAN"), root_request_id_bytes.clone()))
+        {
+            spans.push_back(root_span);
+        }
+
+        // Child spans registered via propagate_span
+        let ctx_key = (symbol_short!("TRACECTX"), root_request_id_bytes.clone());
+        let ctx: Option<TracingContext> = env.storage().temporary().get(&ctx_key);
+        if let Some(ctx) = ctx {
+            for i in 1..ctx.next_span_index {
+                let child_list_key = (symbol_short!("TRACEIDS"), root_request_id_bytes.clone(), i);
+                if let Some(child_id) = env
+                    .storage()
+                    .temporary()
+                    .get::<_, Bytes>(&child_list_key)
+                {
+                    if let Some(child_span) = env
+                        .storage()
+                        .temporary()
+                        .get::<_, TracingSpan>(&(symbol_short!("SPAN"), child_id))
+                    {
+                        spans.push_back(child_span);
+                    }
+                }
+            }
+        }
+
+        spans
+    }
+
     // -----------------------------------------------------------------------
     // Attestation retrieval
     // -----------------------------------------------------------------------
@@ -2438,6 +2537,19 @@ pub fn is_attestor(env: Env, attestor: Address) -> bool {
         actor: Address,
         now: u64,
         status: String,
+    ) {
+        Self::store_span_with_parent(env, request_id, operation, actor, now, status, Bytes::new(env), 0);
+    }
+
+    fn store_span_with_parent(
+        env: &Env,
+        request_id: &RequestId,
+        operation: String,
+        actor: Address,
+        now: u64,
+        status: String,
+        parent_request_id_bytes: Bytes,
+        span_index: u32,
     ) {
         let span = TracingSpan {
             request_id: request_id.clone(),
@@ -2446,6 +2558,8 @@ pub fn is_attestor(env: Env, attestor: Address) -> bool {
             started_at: now,
             completed_at: now,
             status,
+            parent_request_id_bytes,
+            span_index,
         };
         let key = (symbol_short!("SPAN"), request_id.id.clone());
         env.storage().temporary().set(&key, &span);

tests/tracing_span_tests.rs

@@ -28,6 +28,61 @@ mod tracing_span_tests {
 
     #[test]
     fn test_span_propagates_across_operations() {
+        let env = make_env();
+        env.ledger().set(LedgerInfo {
+            timestamp: 1000,
+            protocol_version: 21,
+            sequence_number: 0,
+            network_id: Default::default(),
+            base_reserve: 0,
+            min_persistent_entry_ttl: 4096,
+            min_temp_entry_ttl: 16,
+            max_entry_ttl: 6312000,
+        });
+        let contract_id = env.register_contract(None, AnchorKitContract);
+        let client = AnchorKitContractClient::new(&env, &contract_id);
+
+        let admin = Address::generate(&env);
+        let attestor = Address::generate(&env);
+        let subject = Address::generate(&env);
+
+        client.initialize(&admin);
+        let sk = SigningKey::generate(&mut OsRng);
+        register_attestor_with_sep10(&env, &client, &attestor, &attestor, &sk);
+
+        // Root span
+        let root_id = client.generate_request_id();
+        client.submit_with_request_id(
+            &root_id,
+            &attestor,
+            &subject,
+            &1000u64,
+            &payload(&env, 0x01),
+            &Bytes::new(&env),
+        );
+
+        // Child span
+        let child_id = client.generate_request_id();
+        client.propagate_span(
+            &root_id,
+            &child_id,
+            &String::from_str(&env, "fetch_transaction_status"),
+            &attestor,
+        );
+
+        // Verify child references parent
+        let child_span = client.get_tracing_span(&child_id.id).unwrap();
+        assert_eq!(child_span.parent_request_id_bytes, root_id.id);
+        assert_eq!(child_span.span_index, 1);
+
+        // Root span has no parent (empty bytes)
+        let root_span = client.get_tracing_span(&root_id.id).unwrap();
+        assert!(root_span.parent_request_id_bytes.is_empty());
+        assert_eq!(root_span.span_index, 0);
+    }
+
+    #[test]
+    fn test_root_span_has_no_parent() {
         let env = make_env();
         env.ledger().set(LedgerInfo {
             timestamp: 0,
@@ -44,14 +99,186 @@ mod tracing_span_tests {
 
         let admin = Address::generate(&env);
         let attestor = Address::generate(&env);
+        let subject = Address::generate(&env);
 
         client.initialize(&admin);
+        let sk = SigningKey::generate(&mut OsRng);
+        register_attestor_with_sep10(&env, &client, &attestor, &attestor, &sk);
+
         let req_id = client.generate_request_id();
+        client.submit_with_request_id(
+            &req_id,
+            &attestor,
+            &subject,
+            &1000u64,
+            &payload(&env, 0x02),
+            &Bytes::new(&env),
+        );
+
+        let span = client.get_tracing_span(&req_id.id).unwrap();
+        assert!(span.parent_request_id_bytes.is_empty(), "root span must have no parent");
+        assert_eq!(span.span_index, 0);
+    }
+
+    #[test]
+    fn test_sibling_spans_share_same_parent() {
+        let env = make_env();
+        env.ledger().set(LedgerInfo {
+            timestamp: 500,
+            protocol_version: 21,
+            sequence_number: 0,
+            network_id: Default::default(),
+            base_reserve: 0,
+            min_persistent_entry_ttl: 4096,
+            min_temp_entry_ttl: 16,
+            max_entry_ttl: 6312000,
+        });
+        let contract_id = env.register_contract(None, AnchorKitContract);
+        let client = AnchorKitContractClient::new(&env, &contract_id);
+
+        let admin = Address::generate(&env);
+        let attestor = Address::generate(&env);
+        let subject = Address::generate(&env);
+
+        client.initialize(&admin);
         let sk = SigningKey::generate(&mut OsRng);
         register_attestor_with_sep10(&env, &client, &attestor, &attestor, &sk);
 
-        let span = client.get_tracing_span(&req_id.id);
-        assert!(span.is_none());
+        let root_id = client.generate_request_id();
+        client.submit_with_request_id(
+            &root_id,
+            &attestor,
+            &subject,
+            &1000u64,
+            &payload(&env, 0x03),
+            &Bytes::new(&env),
+        );
+
+        let child_a = client.generate_request_id();
+        let child_b = client.generate_request_id();
+
+        client.propagate_span(
+            &root_id,
+            &child_a,
+            &String::from_str(&env, "step_a"),
+            &attestor,
+        );
+        client.propagate_span(
+            &root_id,
+            &child_b,
+            &String::from_str(&env, "step_b"),
+            &attestor,
+        );
+
+        let span_a = client.get_tracing_span(&child_a.id).unwrap();
+        let span_b = client.get_tracing_span(&child_b.id).unwrap();
+
+        // Both siblings reference the same parent
+        assert_eq!(span_a.parent_request_id_bytes, root_id.id);
+        assert_eq!(span_b.parent_request_id_bytes, root_id.id);
+        // Siblings have different span indices
+        assert_ne!(span_a.span_index, span_b.span_index);
+    }
+
+    #[test]
+    fn test_get_trace_returns_all_spans_in_order() {
+        let env = make_env();
+        env.ledger().set(LedgerInfo {
+            timestamp: 100,
+            protocol_version: 21,
+            sequence_number: 0,
+            network_id: Default::default(),
+            base_reserve: 0,
+            min_persistent_entry_ttl: 4096,
+            min_temp_entry_ttl: 16,
+            max_entry_ttl: 6312000,
+        });
+        let contract_id = env.register_contract(None, AnchorKitContract);
+        let client = AnchorKitContractClient::new(&env, &contract_id);
+
+        let admin = Address::generate(&env);
+        let attestor = Address::generate(&env);
+        let subject = Address::generate(&env);
+
+        client.initialize(&admin);
+        let sk = SigningKey::generate(&mut OsRng);
+        register_attestor_with_sep10(&env, &client, &attestor, &attestor, &sk);
+
+        let root_id = client.generate_request_id();
+        client.submit_with_request_id(
+            &root_id,
+            &attestor,
+            &subject,
+            &1000u64,
+            &payload(&env, 0x04),
+            &Bytes::new(&env),
+        );
+
+        let child1 = client.generate_request_id();
+        let child2 = client.generate_request_id();
+
+        client.propagate_span(&root_id, &child1, &String::from_str(&env, "op1"), &attestor);
+        client.propagate_span(&root_id, &child2, &String::from_str(&env, "op2"), &attestor);
+
+        let trace = client.get_trace(&root_id.id);
+        assert_eq!(trace.len(), 3);
+        // First span is root (span_index 0)
+        assert_eq!(trace.get(0).unwrap().span_index, 0);
+        assert_eq!(trace.get(1).unwrap().span_index, 1);
+        assert_eq!(trace.get(2).unwrap().span_index, 2);
+    }
+
+    #[test]
+    fn test_structured_log_format_includes_parent_request_id() {
+        let env = make_env();
+        env.ledger().set(LedgerInfo {
+            timestamp: 200,
+            protocol_version: 21,
+            sequence_number: 0,
+            network_id: Default::default(),
+            base_reserve: 0,
+            min_persistent_entry_ttl: 4096,
+            min_temp_entry_ttl: 16,
+            max_entry_ttl: 6312000,
+        });
+        let contract_id = env.register_contract(None, AnchorKitContract);
+        let client = AnchorKitContractClient::new(&env, &contract_id);
+
+        let admin = Address::generate(&env);
+        let attestor = Address::generate(&env);
+        let subject = Address::generate(&env);
+
+        client.initialize(&admin);
+        let sk = SigningKey::generate(&mut OsRng);
+        register_attestor_with_sep10(&env, &client, &attestor, &attestor, &sk);
+
+        let root_id = client.generate_request_id();
+        client.submit_with_request_id(
+            &root_id,
+            &attestor,
+            &subject,
+            &1000u64,
+            &payload(&env, 0x05),
+            &Bytes::new(&env),
+        );
+
+        let child_id = client.generate_request_id();
+        client.propagate_span(
+            &root_id,
+            &child_id,
+            &String::from_str(&env, "sep6_deposit"),
+            &attestor,
+        );
+
+        let child_span = client.get_tracing_span(&child_id.id).unwrap();
+        // Structured log: parent_request_id_bytes is non-empty when span is a child
+        assert!(!child_span.parent_request_id_bytes.is_empty());
+        assert_eq!(
+            child_span.parent_request_id_bytes,
+            root_id.id,
+            "structured log must include parent_request_id"
+        );
+        assert_eq!(child_span.operation, String::from_str(&env, "sep6_deposit"));
     }
 
     #[test]