Performance & Limitations

Performance considerations, type conversions, known limitations, and best practices.

Performance Considerations

JavaScript execution adds overhead compared to native OTTL operations. Measured performance impact from testing complex transformations (including nested objects, arrays, conditionals, and JSON operations):

  • CPU impact: +0.3% (measured: baseline 5.0% → 5.3%)
  • Memory impact: +1MB (measured: baseline 125MB → 126MB)
  • Latency impact: +3ms p95 (measured: baseline 88ms → 91ms p95)
  • Throughput: No measurable impact in testing

Performance may vary with:

  • Complexity of JavaScript operations
  • Volume and frequency of events
  • Agent resource allocation
  • Concurrent pipeline processing

For high-volume pipelines (>1000 logs/sec), prefer native OTTL for simple operations and reserve edx_code for transformations that genuinely require JavaScript capabilities.

Type Conversion

Fields from parsed JSON may arrive as strings and require explicit type conversion before numeric operations:

// Convert string to integer before use
set(attributes["test_id"], Int(body["test_id"]))

// Then use in edx_code
edx_code("item['attributes']['ab_flag'] = item['attributes']['test_id'] % 2 === 0 ? 'A' : 'B';")

Syntax Validation and Error Handling

Syntax Validation (v2.6.0)

Edge Delta validates JavaScript syntax at configuration time, before deployment. Invalid syntax is caught by both CLI and GUI interfaces and prevents configuration from being saved or deployed:

// ❌ This will be REJECTED during validation
edx_code("item['attributes']['test'] = ;")  // SyntaxError: Unexpected token ;

// Validation error message:
// "JavaScript compilation failed: SyntaxError: (anonymous): Line 7:34 Unexpected token ;"

Both CLI and GUI validation consistently block syntax-invalid JavaScript from reaching agents.

Runtime Error Handling

While syntax errors are blocked at validation time, runtime errors (accessing undefined properties, type mismatches, etc.) are not yet fully tested. Best practices for error handling:

  1. Check for field existence before accessing:

    edx_code("if (item['attributes']['field']) { /* use field */ }")
    
  2. Initialize fields with OTTL where clauses:

    set(attributes["field"], "default") where attributes["field"] == nil
    
  3. Use null-safe operators:

    edx_code("item['attributes']['result'] = item['attributes']['field'] || 'default';")
    

Template Literal Escaping

Template literals work correctly but be mindful of escaping in YAML:

# Works - using ${} inside template literal
edx_code("item['attributes']['msg'] = `Value: ${item['attributes']['value']}`;")

# Also works - explicit escaping if needed
edx_code("item['attributes']['msg'] = `It\\'s working`;")

Comparison with Native OTTL

FeatureNative OTTLedx_codeAdvantage
Simple field assignment✅ Easy✅ EasyEqual
Numeric operations✅ Supported✅ SupportedEqual
String concatenation⚠️ Limited✅ Full supportedx_code
Conditional logic⚠️ where clauses only✅ Full if/else/ternaryedx_code
Array manipulation❌ Very limited✅ All array methodsedx_code
Nested object creation❌ Difficult✅ Easy with null-safe checksedx_code
Multi-step operations⚠️ Multiple statements✅ Single blockedx_code
JSON operations❌ Not available✅ Full JSON supportedx_code
Date/time operations⚠️ Limited✅ Full Date APIedx_code
Performance✅ Native Go speed⚠️ JavaScript overheadOTTL

When to Use edx_code

Use edx_code when:

  • You need conditional logic beyond simple where clauses
  • Array manipulation is required
  • Complex multi-step transformations would require many OTTL statements
  • You need to create nested objects dynamically
  • JSON parsing/stringifying is necessary

When to Use Native OTTL

Use native OTTL when:

  • Simple field operations are sufficient
  • Performance is critical and operations can be done natively
  • You want to avoid JavaScript syntax complexity

Areas Under Active Development

The following aspects of edx_code are under active testing and development:

Runtime Error Handling

  • Behavior when accessing undefined properties
  • Timeout handling for infinite loops
  • Type mismatch error handling

Additional Syntax Patterns

  • Various quote escaping patterns
  • Complex nested expressions
  • Edge cases in YAML formatting

Performance at Scale

  • High-volume processing (1000+ logs/sec)
  • Memory efficiency optimizations
  • Throughput improvements

Check the Edge Delta release notes for updates as these capabilities mature.

Best Practices

  • Start Simple: Begin with basic operations and gradually add complexity as you understand the behavior
  • Type Convert Early: Use OTTL Int(), Double(), or String() functions to convert types before edx_code operations
  • Null Safety: Always check for field existence before accessing nested properties
  • Avoid Reinventing: Use native OTTL for simple operations; reserve edx_code for complex transformations
  • Test Incrementally: Deploy changes to a test environment and verify output before production
  • Monitor Performance: Track pipeline latency and throughput when introducing edx_code transformations
  • Document Intent: Add comments to explain complex JavaScript logic for future maintainers
  • Validate Output: Ensure transformed data meets downstream system requirements
  • Keep Blocks Small: Break complex logic into multiple edx_code calls for easier debugging
  • Use Block Syntax: For multi-step operations, use {} to group statements and declare local variables