EDXLookup

Minimum Agent Version: v1.22.0

Overview

EDXLookup performs safe map lookups with default value fallback. While OTTL provides direct map access using bracket notation (e.g., attributes["key"]), accessing a non-existent key results in a null value that can cause errors in subsequent operations. This Edge Delta extension provides a safe way to look up values in maps with a default value that’s returned when the key doesn’t exist, similar to the get() method with defaults in many programming languages.

Syntax

EDXLookup(map, key, default_value)

• map: The map to perform the lookup on (typically attributes, resource, or a nested map field).
• key: The key to look up in the map (can be a field reference or literal string).
• default_value: The value to return if the key doesn’t exist in the map.

Examples

Input

{
  "_type": "log",
  "timestamp": 1735789900000,
  "body": "User event logged",
  "resource": {...},
  "attributes": {
    "status_codes": {
      "200": "OK",
      "404": "Not Found",
      "500": "Internal Server Error"
    },
    "current_status": "200",
    "missing_status": "999",
    "severity_map": {
      "error": "high",
      "warn": "medium",
      "info": "low"
    },
    "log_level": "debug"
  }
}

Statement

set(attributes["status_message"], EDXLookup(attributes["status_codes"], attributes["current_status"], "Unknown Status"))
set(attributes["unknown_status_message"], EDXLookup(attributes["status_codes"], attributes["missing_status"], "Unknown Status"))
set(attributes["severity"], EDXLookup(attributes["severity_map"], attributes["log_level"], "low"))
set(attributes["priority"], EDXLookup(attributes["severity_map"], "critical", "unknown"))

Output

{
  "_type": "log",
  "timestamp": 1735789930000,
  "body": "User event logged",
  "resource": {...},
  "attributes": {
    "status_codes": {
      "200": "OK",
      "404": "Not Found",
      "500": "Internal Server Error"
    },
    "current_status": "200",
    "missing_status": "999",
    "severity_map": {
      "error": "high",
      "warn": "medium",
      "info": "low"
    },
    "log_level": "debug",
    "status_message": "OK",
    "unknown_status_message": "Unknown Status",
    "severity": "low",
    "priority": "unknown"
  }
}

The EDXLookup function has safely performed map lookups: found “OK” for status code 200, returned “Unknown Status” for non-existent status code 999, returned “low” default for missing “debug” key in severity map, and returned “unknown” default for missing “critical” key.

Pattern Matching with Lookup Tables

Minimum Agent Version: v2.11.0

EDXLookup can also perform pattern-based lookups against lookup tables with configurable match modes. This is useful for alert normalization, log categorization, and dynamic enrichment where exact matching is insufficient.

Extended Syntax

EDXLookup(lookup_name, key_column, key_value, value_column, additional_columns, config)

• lookup_name: The lookup table path (e.g., "ed://alerts.csv").
• key_column: The column in the lookup table to match against.
• key_value: The value to match (typically from the log body or an attribute).
• value_column: The column to return on a match.
• additional_columns: Optional list of additional columns to return (e.g., ["severity", "category"]).
• config: Optional configuration map for match behavior.

Configuration Options

Match Modes

Regex Match Mode

In regex mode, the lookup table cells contain regex patterns, and the key_value (typically a log message) is matched against those patterns. This is useful for alert normalization where you want to categorize log messages based on pattern matching.

Example Lookup Table (alerts.csv)

Example OTTL

set(cache["alert"], EDXLookup("ed://alerts.csv", "pattern", body, "alert_name",
    ["severity"],
    {"match_mode": "regex"}))

For a log message like "error: connection timeout occurred", this matches the first row (pattern error.*timeout) and returns:

{
  "alert_name": "Connection Timeout",
  "severity": "high"
}

Case-Insensitive Matching

Enable case-insensitive matching with the ignore_case option.

set(cache["matches"], EDXLookup("ed://errors.csv", "keyword", body, "category",
    [],
    {"match_mode": "contain", "ignore_case": true}))

Returning Multiple Matches

By default, EDXLookup returns the first matching row. Set return_all: true to return all matching rows as an array.

set(cache["all_matches"], EDXLookup("ed://patterns.csv", "pattern", body, "category",
    ["severity"],
    {"match_mode": "contain", "return_all": true}))

This returns an array of all matching results:

[
  {"category": "network", "severity": "high"},
  {"category": "timeout", "severity": "medium"}
]

Performance Considerations

• Regex caching: Compiled regex patterns are cached for performance. Repeated lookups against the same patterns do not recompile.
• Exact match optimization: When using exact match mode, lookups use a pre-built index for O(1) performance.
• Pattern scanning: regex, contain, prefix, and suffix modes scan all rows, which may be slower for very large lookup tables.

Use Cases

Alert Normalization

Normalize diverse log messages into standardized alert schemas:

set(attributes["normalized_alert"], EDXLookup("ed://alert-patterns.csv", "pattern", body, "alert_schema",
    ["severity", "category", "normalized_message"],
    {"match_mode": "regex"}))

Log Categorization

Categorize logs based on keyword matching:

set(attributes["log_category"], EDXLookup("ed://categories.csv", "keyword", body, "category",
    [],
    {"match_mode": "contain", "ignore_case": true}))

Error Code Lookup with Prefix

Match error codes by prefix:

set(attributes["error_info"], EDXLookup("ed://error-codes.csv", "code_prefix", attributes["error_code"], "description",
    ["severity"],
    {"match_mode": "prefix"}))