getClient() | Respan Docs

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

Method	Description
`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