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(): KeywordsAIClient

Basic Usage

import { KeywordsAITelemetry } from '@keywordsai/tracing';

const keywordsAi = new KeywordsAITelemetry({
    apiKey: process.env.KEYWORDSAI_API_KEY,
    appName: 'my-app'
});

await keywordsAi.initialize();

await keywordsAi.withTask(
    { name: 'data_processing' },
    async () => {
        const client = keywordsAi.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 keywordsAi.withWorkflow(
    { name: 'user_request' },
    async () => {
        const client = keywordsAi.getClient();
        
        // Update span with custom attributes
        client.updateCurrentSpan({
            keywordsai_params: {
                customer_identifier: 'user-123',
                metadata: { 
                    environment: 'production',
                    version: '2.0'
                }
            },
            attributes: {
                'custom.status': 'in_progress'
            }
        });
        
        return await processRequest();
    }
);

Record Exceptions

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

Add Events

await keywordsAi.withWorkflow(
    { name: 'batch_processing' },
    async () => {
        const client = keywordsAi.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