Skip to main content

​
Overview

Keywords AI Parameters are special attributes you can attach to spans for enhanced filtering, grouping, and metadata in the Keywords AI dashboard.

​
Parameters

​
customer_identifier

Identifies the customer or user associated with the trace. Useful for filtering traces by customer. 
await keywordsAi.withWorkflow(
    { name: 'user_request' },
    async () => {
        const client = keywordsAi.getClient();
        
        client.updateCurrentSpan({
            keywordsai_params: {
                customer_identifier: 'user-123'
            }
        });
        
        return await processUserRequest();
    }
);

​
trace_group_identifier

Groups related traces together. Useful for organizing traces by feature, team, or project. 
await keywordsAi.withWorkflow(
    { name: 'order_processing' },
    async () => {
        const client = keywordsAi.getClient();
        
        client.updateCurrentSpan({
            keywordsai_params: {
                trace_group_identifier: 'ecommerce-orders'
            }
        });
        
        return await processOrder();
    }
);

​
metadata

Arbitrary key-value pairs for additional context. Useful for business-specific information. 
await keywordsAi.withWorkflow(
    { name: 'api_request' },
    async () => {
        const client = keywordsAi.getClient();
        
        client.updateCurrentSpan({
            keywordsai_params: {
                metadata: {
                    order_id: 'ORDER-789',
                    payment_method: 'credit_card',
                    shipping_country: 'US',
                    cart_total: 99.99,
                    is_premium_user: true
                }
            }
        });
        
        return await processApiRequest();
    }
);

​
Complete Example

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

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

await keywordsAi.initialize();

await keywordsAi.withWorkflow(
    { 
        name: 'checkout_workflow',
        associationProperties: {
            'workflow_version': '2.0'
        }
    },
    async () => {
        const client = keywordsAi.getClient();
        
        client.updateCurrentSpan({
            keywordsai_params: {
                customer_identifier: 'customer-abc123',
                trace_group_identifier: 'checkout',
                metadata: {
                    cart_id: 'CART-456',
                    items_count: 3,
                    subtotal: 89.97,
                    tax: 7.20,
                    total: 97.17,
                    payment_method: 'visa',
                    shipping_method: 'express',
                    promo_code: 'SAVE10',
                    is_first_purchase: false
                }
            }
        });
        
        // Process checkout
        await validateCart();
        await processPayment();
        await createOrder();
        
        return 'checkout_complete';
    }
);

await keywordsAi.shutdown();

​
Use Cases

​
Customer Support

Filter traces by customer ID when investigating support tickets: 
client.updateCurrentSpan({
    keywordsai_params: {
        customer_identifier: supportTicket.customerId,
        metadata: {
            ticket_id: supportTicket.id,
            issue_type: supportTicket.category,
            priority: supportTicket.priority
        }
    }
});

​
Feature Tracking

Group traces by feature for usage analytics: 
client.updateCurrentSpan({
    keywordsai_params: {
        trace_group_identifier: 'new-search-feature',
        metadata: {
            feature_flag: 'search_v2',
            ab_test_variant: 'B',
            feature_enabled_at: new Date().toISOString()
        }
    }
});

​
Business Metrics

Track business-relevant information: 
client.updateCurrentSpan({
    keywordsai_params: {
        customer_identifier: order.customerId,
        trace_group_identifier: 'orders',
        metadata: {
            order_value: order.total,
            product_category: order.category,
            revenue_type: 'subscription',
            conversion_source: 'email_campaign'
        }
    }
});

​
Multi-Tenant Applications

Identify traces by tenant: 
client.updateCurrentSpan({
    keywordsai_params: {
        customer_identifier: tenant.id,
        trace_group_identifier: `tenant-${tenant.plan}`,
        metadata: {
            tenant_name: tenant.name,
            plan_tier: tenant.plan,
            region: tenant.region,
            custom_domain: tenant.domain
        }
    }
});

​
Association Properties vs Keywords AI Params

FeatureassociationPropertieskeywordsai_params
Set viaMethod optionsupdateCurrentSpan()
When to setAt span creationDuring span execution
Use caseStatic metadataDynamic runtime metadata
LocationwithWorkflow, withTask, etc.getClient().updateCurrentSpan()

​
Using Both Together

await keywordsAi.withWorkflow(
    { 
        name: 'user_workflow',
        associationProperties: {
            'app_version': '2.1.0',
            'environment': 'production'
        }
    },
    async () => {
        const client = keywordsAi.getClient();
        
        // Add dynamic runtime metadata
        client.updateCurrentSpan({
            keywordsai_params: {
                customer_identifier: userId,
                metadata: {
                    action: 'purchase',
                    timestamp: Date.now()
                }
            }
        });
        
        return await processAction();
    }
);

​
Best Practices

  • Always include customer_identifier for user-specific traces
  • Use trace_group_identifier to organize traces by feature or team
  • Store business-relevant information in metadata
  • Keep metadata values simple (strings, numbers, booleans)
  • Avoid sensitive information (passwords, tokens) in metadata
  • Use consistent naming conventions for metadata keys
  • Update params early in the span lifecycle for complete context