Node Function Tracing

Maximum flexibility for programmatic tracing. Node function tracing allows you to trace any function call with complete control over when and how the tracing happens, perfect for custom tracking patterns, dynamic function calls, and integrating tracing into existing codebases.

This approach gives you the ultimate flexibility to trace functions programmatically, including functions you can’t modify directly or need conditional tracing.

Node function tracing gives you the most flexibility to trace functions programmatically, including functions you can’t modify directly or need conditional tracing.

How It Works

Node function tracing provides programmatic control through:

Programmatic control - Call tracing functions directly in your code
Dynamic tracing - Decide at runtime what to trace
Custom keys - Use custom identifiers for tracking
Flexible input handling - Works with any function signature
Error capture - Automatically handles and reports errors

Implementation

Python: `trace_agent_node_func` & `trace_agent_node_func_sync`

Sync

sync_node_function.py


from handit import HanditTracker
 
tracker = HanditTracker()
tracker.config(api_key="your-api-key")
 
# Example: Conditional tracing based on environment
def process_data_pipeline(data, stage, enable_tracing=True):
    """Process data through different pipeline stages"""
    
    if stage == "validation" and enable_tracing:
        # Trace validation step
        result = tracker.trace_agent_node_func_sync(
            validate_data,
            data,
            key="data-validation"
        )
        
    elif stage == "transformation":
        # Always trace transformation (critical step)
        result = tracker.trace_agent_node_func_sync(
            transform_data,
            data,
            key="data-transformation"
        )
        
    elif stage == "enrichment":
        # Trace with custom metadata
        result = tracker.trace_agent_node_func_sync(
            enrich_data,
            data,
            key="data-enrichment",
            metadata={"stage": stage, "data_size": len(data)}
        )
    
    return result
 
# Example: Tracing external library functions
def process_with_external_lib(input_data):
    """Process data using external library with tracing"""
    
    # Trace external library function
    processed_data = tracker.trace_agent_node_func_sync(
        external_ml_library.process,
        input_data,
        key="external-ml-processing"
    )
    
    # Trace post-processing
    final_result = tracker.trace_agent_node_func_sync(
        post_process_results,
        processed_data,
        key="post-processing"
    )
    
    return final_result
 
def validate_data(data):
    """Validate input data"""
    # Validation logic
    if not data or len(data) == 0:
        raise ValueError("Empty data provided")
    return {"status": "valid", "record_count": len(data)}
 
def transform_data(data):
    """Transform data to required format"""
    # Transformation logic
    transformed = [transform_record(record) for record in data]
    return {"transformed_data": transformed, "success_rate": 0.98}

JavaScript: `captureAgentNode`

node_function.js


const { config, captureAgentNode } = require('handit-sdk');
 
config({ apiKey: 'your-api-key' });
 
// Example: Dynamic function tracing
async function processUserRequest(userId, requestType, data) {
    let result;
    
    if (requestType === 'analysis') {
        // Trace the analysis function
        const analysisResult = await analyzeData(data);
        
        // Manually capture the execution
        await captureAgentNode({
            agentNodeSlug: 'data-analysis',
            requestBody: { userId, data },
            responseBody: analysisResult
        });
        
        result = analysisResult;
        
    } else if (requestType === 'recommendation') {
        // Trace with custom key based on user
        const recommendations = await generateRecommendations(userId, data);
        
        await captureAgentNode({
            agentNodeSlug: `recommendations-${userId}`,
            requestBody: { userId, preferences: data },
            responseBody: recommendations
        });
        
        result = recommendations;
        
    } else if (requestType === 'search') {
        // Trace with error handling
        try {
            const searchResults = await searchKnowledgeBase(data.query, data.filters);
            
            await captureAgentNode({
                agentNodeSlug: 'knowledge-search',
                requestBody: { query: data.query, filters: data.filters, userId },
                responseBody: searchResults,
                error: false
            });
            
            result = searchResults;
            
        } catch (error) {
            // Capture error case
            await captureAgentNode({
                agentNodeSlug: 'knowledge-search',
                requestBody: { query: data.query, filters: data.filters, userId },
                responseBody: { error: error.message },
                error: true
            });
            
            throw error;
        }
    }
    
    return result;
}
 
// Example: Tracing external API calls
async function callExternalService(endpoint, payload) {
    const startTime = Date.now();
    
    try {
        const response = await fetch(`https://api.external-service.com/${endpoint}`, {
            method: 'POST',
            headers: { 'Content-Type': 'application/json' },
            body: JSON.stringify(payload)
        });
        
        const result = await response.json();
        const duration = Date.now() - startTime;
        
        // Capture successful API call
        await captureAgentNode({
            agentNodeSlug: `external-api-${endpoint}`,
            requestBody: { endpoint, payload, timestamp: startTime },
            responseBody: { ...result, duration, status: response.status }
        });
        
        return result;
        
    } catch (error) {
        const duration = Date.now() - startTime;
        
        // Capture failed API call
        await captureAgentNode({
            agentNodeSlug: `external-api-${endpoint}`,
            requestBody: { endpoint, payload, timestamp: startTime },
            responseBody: { 
                error: error.message, 
                duration, 
                failed: true 
            },
            error: true
        });
        
        throw error;
    }
}
 
// Example functions
async function analyzeData(data) {
    // Complex analysis logic
    const analysis = await performComplexAnalysis(data);
    return { analysis, confidence: 0.95 };
}
 
async function generateRecommendations(userId, preferences) {
    const userProfile = await getUserProfile(userId);
    const recommendations = await mlRecommendationEngine(userProfile, preferences);
    return recommendations;
}
 
async function searchKnowledgeBase(query, filters) {
    const results = await vectorSearch(query, filters);
    return { results, count: results.length };
}

Advanced Use Cases

Conditional Tracing Based on Context

JavaScript

conditional_tracing.js


const { config, captureAgentNode } = require('handit-sdk');
 
config({ apiKey: 'your-api-key' });
 
// Environment-based tracing
const ENABLE_DETAILED_TRACING = process.env.DETAILED_TRACING === 'true';
const PRODUCTION_ENV = process.env.NODE_ENV === 'production';
 
async function smartProcessingPipeline(data, userTier = 'basic') {
    // Intelligent tracing decisions
    const shouldTrace = (PRODUCTION_ENV && userTier === 'premium') || ENABLE_DETAILED_TRACING;
    
    // Step 1: Preprocessing (always trace critical steps)
    const preprocessed = await preprocessData(data);
    
    await captureAgentNode({
        agentNodeSlug: 'preprocessing',
        requestBody: { originalData: data },
        responseBody: preprocessed
    });
    
    // Step 2: Main processing (conditional tracing)
    let result;
    if (shouldTrace) {
        const startTime = Date.now();
        result = await mainProcessing(preprocessed);
        
        await captureAgentNode({
            agentNodeSlug: `main-processing-${userTier}`,
            requestBody: { preprocessedData: preprocessed, userTier },
            responseBody: { ...result, processingTime: Date.now() - startTime }
        });
    } else {
        result = await mainProcessing(preprocessed);
    }
    
    // Step 3: Post-processing (trace only errors in production)
    let finalResult;
    if (PRODUCTION_ENV) {
        try {
            finalResult = await postProcess(result);
        } catch (error) {
            // Trace the error case
            await captureAgentNode({
                agentNodeSlug: 'post-processing-error',
                requestBody: { input: result },
                responseBody: { error: error.message },
                error: true
            });
            throw error;
        }
    } else {
        // Trace everything in development
        finalResult = await postProcess(result);
        
        await captureAgentNode({
            agentNodeSlug: 'post-processing',
            requestBody: { input: result },
            responseBody: finalResult
        });
    }
    
    return finalResult;
}

Tracing Third-Party Libraries

JavaScript

third_party_tracing.js


const { config, captureAgentNode } = require('handit-sdk');
const axios = require('axios');
const tf = require('@tensorflow/tfjs');
 
config({ apiKey: 'your-api-key' });
 
// Trace TensorFlow.js operations
async function traceMLPipeline(inputData) {
    // Trace data preprocessing
    const preprocessedData = await preprocessData(inputData);
    
    await captureAgentNode({
        agentNodeSlug: 'data-preprocessing',
        requestBody: { rawData: inputData },
        responseBody: { processedData: preprocessedData }
    });
    
    // Trace model inference
    const model = await tf.loadLayersModel('/path/to/model.json');
    const predictions = model.predict(tf.tensor(preprocessedData));
    const predictionData = await predictions.data();
    
    await captureAgentNode({
        agentNodeSlug: 'tensorflow-inference',
        requestBody: { inputShape: preprocessedData.shape },
        responseBody: { predictions: Array.from(predictionData) }
    });
    
    return predictionData;
}
 
// Trace external API calls with retry logic
async function traceExternalAPIWithRetry(endpoint, payload, maxRetries = 3) {
    let lastError;
    
    for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
            const startTime = Date.now();
            const response = await axios.post(endpoint, payload);
            const duration = Date.now() - startTime;
            
            // Trace successful call
            await captureAgentNode({
                agentNodeSlug: 'external-api-call',
                requestBody: { 
                    endpoint, 
                    payload, 
                    attempt, 
                    maxRetries 
                },
                responseBody: { 
                    data: response.data, 
                    status: response.status,
                    duration,
                    success: true 
                }
            });
            
            return response.data;
            
        } catch (error) {
            lastError = error;
            const duration = Date.now() - startTime;
            
            // Trace failed attempt
            await captureAgentNode({
                agentNodeSlug: 'external-api-call',
                requestBody: { 
                    endpoint, 
                    payload, 
                    attempt, 
                    maxRetries 
                },
                responseBody: { 
                    error: error.message,
                    status: error.response?.status,
                    duration,
                    willRetry: attempt < maxRetries 
                },
                error: true
            });
            
            if (attempt === maxRetries) break;
            
            // Wait before retry
            await new Promise(resolve => setTimeout(resolve, 1000 * attempt));
        }
    }
    
    throw lastError;
}
 
// Trace WebSocket operations
function traceWebSocketCommunication(websocket, messageType, data) {
    websocket.on('message', async (message) => {
        await captureAgentNode({
            agentNodeSlug: 'websocket-message-received',
            requestBody: { messageType, expectedData: data },
            responseBody: { receivedMessage: message }
        });
    });
    
    websocket.on('error', async (error) => {
        await captureAgentNode({
            agentNodeSlug: 'websocket-error',
            requestBody: { messageType, data },
            responseBody: { error: error.message },
            error: true
        });
    });
}

Best Practices

When to Use Node Function Tracing:

Use Case	Why Node Function Tracing
Dynamic function selection	Choose which functions to trace based on runtime conditions
Third-party library integration	Trace external libraries and APIs without modifying their code
Conditional tracing logic	Implement complex tracing rules based on environment or user context
Custom tracking patterns	Create specialized tracing workflows for unique requirements
Error-specific tracing	Focus tracing on error scenarios and edge cases

Implementation Guidelines:

Use descriptive keys for tracking - Choose meaningful identifiers that help with debugging and analysis
Include relevant context in captures - Add metadata that provides useful debugging information
Handle errors explicitly - Implement proper error handling and capture error scenarios
Consider performance impact - Balance tracing detail with system performance requirements
Add metadata for debugging - Include timing, user context, and other relevant information

⚠️

Node function tracing requires more manual work but provides maximum flexibility. Use it when decorators and wrappers don’t fit your use case.

Node function tracing is perfect for integrating Handit.ai into existing codebases without major refactoring.

Next Steps

Learn about Agent Wrapper/Decorator for simpler automation
Explore Node Wrapper/Decorator for function-level tracing
Check Manual Agent Tracing for complete control

Node Function Tracing

How It Works

Implementation

Python: trace_agent_node_func & trace_agent_node_func_sync

Async

Sync

JavaScript: captureAgentNode

Advanced Use Cases

Conditional Tracing Based on Context

Python

JavaScript

Tracing Third-Party Libraries

Python

JavaScript

Best Practices

Next Steps

Python: `trace_agent_node_func` & `trace_agent_node_func_sync`

JavaScript: `captureAgentNode`