updateCurrentSpan()

Update name, status, attributes, and Keywords AI params on the current span

Overview

updateCurrentSpan() allows you to modify the currently active span’s metadata, status, attributes, and Keywords AI-specific parameters.

Signature

updateCurrentSpan(options: {
    keywordsai_params?: {
        customer_identifier?: string;
        trace_group_identifier?: string;
        metadata?: Record<string, any>;
    };
    attributes?: Record<string, any>;
    status?: 'OK' | 'ERROR';
    name?: string;
}): void

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.withWorkflow(
    { name: 'user_request' },
    async () => {
        const client = keywordsAi.getClient();
        
        client.updateCurrentSpan({
            keywordsai_params: {
                customer_identifier: 'user-123',
                metadata: { 
                    environment: 'production',
                    version: '2.0'
                }
            }
        });
        
        return await processRequest();
    }
);

Update Status

await keywordsAi.withTask(
    { name: 'validation' },
    async () => {
        const client = keywordsAi.getClient();
        
        try {
            const data = await validateInput();
            
            client.updateCurrentSpan({
                status: 'OK',
                attributes: {
                    'validation.result': 'success'
                }
            });
            
            return data;
        } catch (error) {
            client.updateCurrentSpan({
                status: 'ERROR',
                attributes: {
                    'validation.result': 'failed',
                    'error.message': error.message
                }
            });
            throw error;
        }
    }
);

Custom Attributes

await keywordsAi.withWorkflow(
    { name: 'data_pipeline' },
    async () => {
        const client = keywordsAi.getClient();
        
        client.updateCurrentSpan({
            attributes: {
                'pipeline.stage': 'extraction',
                'pipeline.source': 'database',
                'pipeline.records': 1000
            }
        });
        
        const data = await extractData();
        
        client.updateCurrentSpan({
            attributes: {
                'pipeline.stage': 'transformation',
                'pipeline.records_processed': data.length
            }
        });
        
        return await transformData(data);
    }
);

Keywords AI Parameters

await keywordsAi.withWorkflow(
    { name: 'customer_interaction' },
    async () => {
        const client = keywordsAi.getClient();
        
        client.updateCurrentSpan({
            keywordsai_params: {
                customer_identifier: 'customer-abc123',
                trace_group_identifier: 'support-tickets',
                metadata: {
                    ticket_id: 'TICKET-456',
                    priority: 'high',
                    category: 'billing'
                }
            }
        });
        
        return await handleTicket();
    }
);

Dynamic Span Naming

await keywordsAi.withTask(
    { name: 'api_call' },
    async () => {
        const client = keywordsAi.getClient();
        const endpoint = '/api/users';
        
        client.updateCurrentSpan({
            name: `api_call:${endpoint}`,
            attributes: {
                'http.endpoint': endpoint,
                'http.method': 'GET'
            }
        });
        
        return await fetch(`https://api.example.com${endpoint}`);
    }
);

Comprehensive Update

await keywordsAi.withWorkflow(
    { name: 'order_processing' },
    async () => {
        const client = keywordsAi.getClient();
        
        const orderId = 'ORDER-789';
        const customerId = 'CUST-123';
        
        client.updateCurrentSpan({
            name: `order_processing:${orderId}`,
            keywordsai_params: {
                customer_identifier: customerId,
                trace_group_identifier: 'orders',
                metadata: {
                    order_id: orderId,
                    payment_method: 'credit_card',
                    total_amount: 99.99
                }
            },
            attributes: {
                'order.id': orderId,
                'order.status': 'processing',
                'customer.id': customerId
            },
            status: 'OK'
        });
        
        return await processOrder(orderId);
    }
);

Parameters

keywordsai_params · object

Keywords AI-specific parameters for filtering and grouping

customer_identifier · string

Customer or user identifier for filtering traces by customer

trace_group_identifier · string

Group identifier for organizing related traces

metadata · Record<string, any>

Custom metadata for additional context

attributes · Record<string, any>

Custom OpenTelemetry attributes (key-value pairs)

status · string

Span status: "OK" or "ERROR"

name · string

New name for the span (useful for dynamic naming)

Best Practices

• Update spans with customer identifiers for user-specific filtering
• Set status to ERROR when operations fail
• Use attributes for technical details (HTTP status, DB queries, etc.)
• Use Keywords AI metadata for business context (order IDs, ticket numbers, etc.)
• Update spans early in the function with identifying information
• Only call within an active span