Troubleshooting EDXRedis Function

Overview

The EDXRedis function provides Redis integration for Edge Delta pipelines, but various configuration and connectivity issues can prevent it from working correctly. This guide covers the most common problems and their solutions based on extensive testing and real-world usage.

For complete function documentation and examples, see:

• EDXRedis Complete Reference - Full documentation with all examples
• EDXRedis in OTTL Extensions - Quick overview and syntax

Quick Diagnostics

Before diving into specific issues, run these basic checks:

1. Test Redis Connectivity

- name: redis_connectivity_test
  type: ottl_transform
  statements: |-
    # Test basic connectivity with PING
    set(cache["ping_cmd"], [{"command": "ping", "outField": "pong"}])
    set(cache["ping_result"], EDXRedis({"url": "redis://your-redis-host:6379"}, cache["ping_cmd"]))
    set(attributes["redis.connected"], cache["ping_result"]["pong"] == "PONG")

    # Log for debugging
    set(attributes["debug.ping_result"], String(cache["ping_result"]))    

2. Verify outField Parameter

The outField parameter is mandatory for all Redis commands. Without it, operations may execute but results won’t be accessible:

❌ Incorrect (missing outField):

set(cache["cmd"], [{"command": "get", "key": "user:123"}])

✅ Correct:

set(cache["cmd"], [{"command": "get", "key": "user:123", "outField": "user_data"}])

Common Issues and Solutions

No Results Returned

Symptoms:

• Redis commands execute but attributes are empty
• No error messages in logs

Causes and Solutions:

1. Missing outField parameter

   # Always include outField in every command
   set(cache["cmd"], [{"command": "get", "key": "mykey", "outField": "result"}])
   

2. Accessing wrong field name

   # Make sure you use the same field name defined in outField
   set(cache["cmd"], [{"command": "get", "key": "mykey", "outField": "data"}])
   set(cache["result"], EDXRedis(config, cache["cmd"]))
   set(attributes["value"], cache["result"]["data"])  # Must match outField
   

3. Nil values not handled

   # Always check for nil before using results
   set(attributes["value"], cache["result"]["data"]) where cache["result"]["data"] != nil
   

Authentication Failures

Symptoms:

• “AUTH failed” errors
• “NOAUTH Authentication required” messages

Solutions:

1. Use Manual authentication (UserSecret not implemented)

   set(cache["config"], {
     "url": "redis://redis-host:6379",
     "auth": {
       "method": "Manual",
       "username": "myuser",
       "password": "mypassword"
     }
   })
   

2. Check credentials in connection URL

   # Format: redis://username:password@host:port
   set(cache["config"], {"url": "redis://default:mypassword@redis-host:6379"})
   

Note: UserSecret authentication method is not yet implemented and will return an error.

TLS/mTLS Connection Issues

Symptoms:

• “certificate verify failed” errors
• “TLS handshake failed” messages
• Silent failures with no data returned

Critical Requirements:

1. Certificates MUST include Subject Alternative Names (SANs)

   • Common Name (CN) alone is insufficient
   • Both server and client certificates need SANs

2. Correct field names for TLS configuration

   set(cache["config"], {
     "url": "rediss://redis-host:6379",  # Note: double 's' for TLS
     "tls": {
       "enabled": true,
       "validateCerts": true,
       "caCertPath": "/certs/ca.crt",     # NOT ca_cert
       "certPath": "/certs/client.crt",   # NOT client_cert
       "keyPath": "/certs/client.key"     # NOT client_key
     }
   })
   

3. Certificate generation with SANs

   # Example OpenSSL command with SANs
   openssl req -new -x509 -days 365 -nodes \
     -keyout server.key -out server.crt \
     -subj "/CN=redis-server" \
     -addext "subjectAltName = DNS:redis-host,DNS:*.redis.svc.cluster.local,IP:10.0.0.1"
   

4. Verify certificate mounting in Kubernetes

   # Certificates typically mounted at /certs/
   volumeMounts:
   - name: redis-certs
     mountPath: /certs
     readOnly: true
   

Hash Operations Return Arrays Instead of Maps

Symptoms:

• HGETALL returns ["key1", "val1", "key2", "val2"] instead of {key1: val1, key2: val2}

Solution:

# HGETALL returns a flat array in Redis format
set(cache["cmd"], [{"command": "hgetall", "key": "myhash", "outField": "data"}])
set(cache["result"], EDXRedis(config, cache["cmd"]))

# Option 1: Use individual HGET commands
set(cache["cmd"], [{"command": "hget", "key": "myhash", "args": ["field1"], "outField": "value1"}])

# Option 2: Process the array in OTTL (if needed)
# The array format is: [field1, value1, field2, value2, ...]
set(attributes["hash_array"], cache["result"]["data"])

Redis Cluster Redirect Issues

Symptoms:

• “MOVED” or “ASK” errors
• Commands fail on cluster deployments

Solution:

set(cache["config"], {
  "url": "redis://node1:6379,node2:6379,node3:6379",
  "deploymentType": "Cluster"  # Must specify for cluster mode
})

Sentinel Connection Problems

Symptoms:

• “Can’t find master” errors
• Connection fails in Sentinel mode

Solution:

set(cache["config"], {
  "url": "redis://sentinel1:26379,sentinel2:26379",
  "deploymentType": "Sentinel",
  "sentinelMasterName": "mymaster"  # Must match Sentinel configuration
})

JSON Parsing Errors in HTTP Output

Symptoms:

• “SyntaxError: Unexpected token” in HTTP destinations
• Malformed JSON when enriched data is sent downstream

Solution: Add JSON encoder to HTTP output nodes:

- name: http_output
  type: http_output
  endpoint: http://destination/endpoint
  encoder: json  # Add this line

Silent Failures

Symptoms:

• No error messages
• No data enrichment
• Commands appear to not execute

Common Causes:

1. TLS configuration issues - TLS-only configs may fail silently

   • Solution: Use mTLS configuration or verify server certificates have proper SANs

2. Network connectivity - Firewall or network policies blocking Redis

   • Solution: Test with redis-cli from the same pod/namespace

3. Invalid OTTL syntax - Validation passes but runtime fails

   • Solution: Check Edge Delta agent logs for OTTL execution errors

Performance Optimization

Batch Operations for Better Performance

Instead of multiple individual calls:

# Inefficient - multiple round trips
set(cache["cmd1"], [{"command": "get", "key": "key1", "outField": "val1"}])
set(cache["result1"], EDXRedis(config, cache["cmd1"]))
set(cache["cmd2"], [{"command": "get", "key": "key2", "outField": "val2"}])
set(cache["result2"], EDXRedis(config, cache["cmd2"]))

Use batch operations:

# Efficient - single round trip
set(cache["cmds"], [
  {"command": "get", "key": "key1", "outField": "val1"},
  {"command": "get", "key": "key2", "outField": "val2"}
])
set(cache["results"], EDXRedis(config, cache["cmds"]))
set(attributes["value1"], cache["results"]["val1"])
set(attributes["value2"], cache["results"]["val2"])

Connection Pool Management

EDXRedis automatically manages connection pooling:

• Connections are reused based on configuration hash
• Unhealthy clients are automatically replaced
• No manual pool configuration needed

Debugging Techniques

Enable Verbose Logging

Add debug attributes to track execution:

- name: redis_debug
  type: ottl_transform
  statements: |-
    # Add debug markers
    set(attributes["debug.before"], "starting")
    set(attributes["debug.timestamp"], Now())

    # Execute Redis command
    set(cache["cmd"], [{"command": "get", "key": "test", "outField": "data"}])
    set(cache["result"], EDXRedis(config, cache["cmd"]))

    # Log results for debugging
    set(attributes["debug.result"], String(cache["result"]))
    set(attributes["debug.after"], "completed")    

Check Agent Logs

Look for EDXRedis-specific errors:

# In Kubernetes
kubectl logs -n edgedelta <pod-name> | grep -i redis

# Common error patterns to search for
kubectl logs -n edgedelta <pod-name> | grep -E "failed to get Redis client|AUTH failed|certificate verify|NOAUTH"

Validate Configuration Separately

Test your Redis configuration outside of Edge Delta:

# Test basic connectivity
redis-cli -h redis-host -p 6379 ping

# Test with authentication
redis-cli -h redis-host -p 6379 -a password ping

# Test TLS connection
redis-cli --tls --cert client.crt --key client.key --cacert ca.crt -h redis-host ping

Known Limitations

1. UserSecret authentication not implemented - Use Manual authentication method only
2. TLS-only configurations may fail silently - Use mTLS or ensure proper SAN configuration
3. HGETALL returns arrays not maps - Plan data processing accordingly
4. No automatic retry mechanism - Implement retry logic in OTTL if needed

Getting Help

If you continue to experience issues:

1. Check the main documentation: EDXRedis Function Reference
2. Review agent logs: Look for specific error messages
3. Test connectivity: Verify Redis is accessible from your Edge Delta deployment
4. Contact support: Provide your configuration (sanitized) and error messages

Related Documentation

• OTTL Language Guide
• Edge Delta Performance Tuning
• Redis Best Practices