Skip to main content

​
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