updateCurrentSpan() | Respan Docs

Overview

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

Signature

updateCurrentSpan(options: {
    respan_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 { RespanTelemetry } from '@respan/tracing';
const respanAi = new RespanTelemetry({
    apiKey: process.env.RESPAN_API_KEY,
    appName: 'my-app'
});
await respanAi.initialize();
await respanAi.withWorkflow(
    { name: 'user_request' },
    async () => {
        const client = respanAi.getClient();
        
        client.updateCurrentSpan({
            respan_params: {
                customer_identifier: 'user-123',
                metadata: { 
                    environment: 'production',
                    version: '2.0'
                }
            }
        });
        
        return await processRequest();
    }
);

Update Status

await respanAi.withTask(
    { name: 'validation' },
    async () => {
        const client = respanAi.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 respanAi.withWorkflow(
    { name: 'data_pipeline' },
    async () => {
        const client = respanAi.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);
    }
);

Respan Parameters

await respanAi.withWorkflow(
    { name: 'customer_interaction' },
    async () => {
        const client = respanAi.getClient();
        
        client.updateCurrentSpan({
            respan_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 respanAi.withTask(
    { name: 'api_call' },
    async () => {
        const client = respanAi.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 respanAi.withWorkflow(
    { name: 'order_processing' },
    async () => {
        const client = respanAi.getClient();
        
        const orderId = 'ORDER-789';
        const customerId = 'CUST-123';
        
        client.updateCurrentSpan({
            name: `order_processing:${orderId}`,
            respan_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

respan_params

object

Respan-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 Respan metadata for business context (order IDs, ticket numbers, etc.)
Update spans early in the function with identifying information
Only call within an active span