Skip to main content

​
Overview

getClient() returns the tracing client instance for manual span operations. Use it to read IDs, update spans, add events, and manage traces.

​
Signature

getClient(): RespanClient

​
Basic Usage

import { RespanTelemetry } from '@respan/tracing';

const respanAi = new RespanTelemetry({
    apiKey: process.env.RESPAN_API_KEY,
    appName: 'my-app'
});

await respanAi.initialize();

await respanAi.withTask(
    { name: 'data_processing' },
    async () => {
        const client = respanAi.getClient();
        
        // Get current trace and span IDs
        const traceId = client.getCurrentTraceId();
        const spanId = client.getCurrentSpanId();
        
        console.log(`Processing in trace ${traceId}, span ${spanId}`);
        
        // Add event
        client.addSpanEvent('processing_started', { 
            records: 100 
        });
        
        // Your processing logic
        return 'processed';
    }
);

​
Update Current Span

await respanAi.withWorkflow(
    { name: 'user_request' },
    async () => {
        const client = respanAi.getClient();
        
        // Update span with custom attributes
        client.updateCurrentSpan({
            respan_params: {
                customer_identifier: 'user-123',
                metadata: { 
                    environment: 'production',
                    version: '2.0'
                }
            },
            attributes: {
                'custom.status': 'in_progress'
            }
        });
        
        return await processRequest();
    }
);

​
Record Exceptions

await respanAi.withTask(
    { name: 'risky_operation' },
    async () => {
        const client = respanAi.getClient();
        
        try {
            return await riskyApiCall();
        } catch (error) {
            // Manually record exception
            client.recordSpanException(error);
            throw error;
        }
    }
);

​
Add Events

await respanAi.withWorkflow(
    { name: 'batch_processing' },
    async () => {
        const client = respanAi.getClient();
        
        client.addSpanEvent('batch_started', { 
            batch_size: 1000 
        });
        
        for (let i = 0; i < 10; i++) {
            await processBatch(i);
            client.addSpanEvent('batch_completed', { 
                batch_number: i,
                records_processed: 100 
            });
        }
        
        client.addSpanEvent('all_batches_completed');
        
        return 'done';
    }
);

​
Available Client Methods

MethodDescription
getCurrentTraceId()Get the current trace ID
getCurrentSpanId()Get the current span ID
updateCurrentSpan()Update span attributes, status, metadata
addSpanEvent()Add a timestamped event to current span
recordSpanException()Record an error on current span
getContextValue()Get a context value by key
setContextValue()Set a context value by key
isRecording()Check if tracing is currently active
getTracer()Get the underlying OpenTelemetry tracer
flush()Manually flush pending spans

​
Best Practices

  • Use getClient() within traced functions (workflow, task, agent, tool)
  • Call client methods only when a span is active
  • Add events for significant milestones in your logic
  • Record exceptions for better error tracking
  • Update spans with custom metadata for filtering and analysis