배열 맵 프로세서 (Array Map Processor)

배열 맵 프로세서를 이용하면 소스 배열의 각 요소에 일련의 하위 프로세서를 적용해서 대상 배열을 만들어 낼 수 있어요. Attribute Remapper, String Builder, Arithmetic Processor, Category Processor 같은 하위 프로세서를 조합해 배열의 요소별로 변환을 수행해요.

출처: 문서

본문

개요

배열 맵 프로세서는 소스 배열의 각 요소에 일련의 하위 프로세서를 적용해 대상 배열을 만들어요. Datadog는 다음 하위 프로세서를 지원해요.

• Attribute Remapper
• String Builder
• Arithmetic Processor
• Category Processor

참고:

• source와 target이 같은 속성이면 프로세서가 요소를 제자리(in place)에서 변환해요.
• target 배열이 이미 존재하면 프로세서가 기존 요소의 속성을 덮어써요.
• 처리는 소스 배열의 처음 50개 요소로 제한돼요.

설정

배열 맵 프로세서는 Pipelines 페이지에서 정의해요:

1. Source array attribute에 반복 처리할 배열 속성의 경로를 입력해요.
2. Preserve source array 체크박스를 선택하거나 해제해서 처리 후 원본 소스 배열을 유지하거나 제거해요.
3. Target array attribute에 출력 배열을 쓸 경로를 입력해요.
4. 각 요소에 적용할 하위 프로세서를 하나 이상 추가해요.

로그의 전후 상태

예시: 네트워크 연결 배열 정규화하기

Before (변환 전):

{
  "connections": [
    { "src_ip": "10.0.0.1", "dst_port": 443, "proto": "tcp" },
    { "src_ip": "10.0.0.2", "dst_port": 22,  "proto": "tcp" }
  ]
}

Array Map Processor (배열 맵 프로세서)

source가 connections, target이 network.connections인 Array Map Processor를 만들어요. $sourceElem.src_ip를 $targetElem.source로 매핑하는 Attribute Remapper 하위 프로세서와, %{$sourceElem.proto}/%{$sourceElem.dst_port} 템플릿을 $targetElem.service에 쓰는 String Builder 하위 프로세서를 추가해요.

After (변환 후):

{
  "connections": [...],
  "network": {
    "connections": [
      {"source": "10.0.0.1", "service": "tcp/443"},
      {"source": "10.0.0.2", "service": "tcp/22"}
    ]
  }
}

API

Datadog Log Pipeline API 엔드포인트에 다음 Array Map 프로세서 JSON 페이로드를 사용하세요:

{
  "type": "array-map-processor",
  "name": "<PROCESSOR_NAME>",
  "is_enabled": true,
  "source": "<SOURCE_ARRAY_ATTRIBUTE>",
  "target": "<TARGET_ARRAY_ATTRIBUTE>",
  "preserve_source": true,
  "processors": [
    {"type": "<SUB_PROCESSOR_TYPE>", ...},
    {"type": "<SUB_PROCESSOR_TYPE>", ...}
  ]
}

Parameter	Type	Required	Description
type	String	Yes	프로세서 유형이에요.
name	String	No	프로세서 이름이에요.
is_enabled	Boolean	No	프로세서 활성화 여부예요. 기본값: false.
source	String	Yes	소스 배열 속성 이름이에요.
target	String	Yes	대상 배열 속성 이름이에요. source와 같으면 요소가 제자리에서 변환돼요.
preserve_source	Boolean	No	처리 후 소스 배열을 보존할지 여부예요. 기본값: true.
processors	Array of Objects	Yes	각 요소에 순서대로 적용되는 하위 프로세서예요. 최소 1개가 필요해요.

하위 프로세서

하위 프로세서를 정의할 때는 다음 규칙이 적용돼요:

• 각 하위 프로세서 안에서 다음을 사용해요:
  • $sourceElem — 현재 입력 요소를 참조할 때.
  • $targetElem — 현재 출력 요소에 쓸 때.
• 속성이 $sourceElem으로 시작하지 않으면 프로세서는 요소 자체가 아니라 상위 로그에서 값을 읽어요.
• $sourceElem.<field>/$targetElem.<field>는 요소 객체의 중첩 속성을, $sourceElem/$targetElem는 기본형 요소(예: 문자열, 정수, double, Boolean)를 가리켜요.
• 모든 대상은 $targetElem으로 시작해야 해요.

Attribute Remapper

기존 필드를 출력 요소의 필드로 리매핑해요.

UI

Example input (입력 예시):

{
  "items": ["10.0.0.1", "10.0.0.2"]
}

Configuration steps (구성 단계):

• Source attributes: $sourceElem
• Target attribute: $targetElem.ip
• Preserve source: enabled

Result (결과):

{
  "items": [...],
  "out": [
    {"ip": "10.0.0.1"},
    {"ip": "10.0.0.2"}
  ]
}

API

{
  "type": "attribute-remapper",
  "name": "Map primitive IP to object field",
  "sources": ["$sourceElem"],
  "target": "$targetElem.ip",
  "target_format": "auto",
  "preserve_source": true,
  "override_on_conflict": false
}

Parameter	Type	Required	Description
type	String	Yes	하위 프로세서 유형이에요.
name	String	No	하위 프로세서 이름이에요.
sources	Array of strings	Yes	소스 속성 배열이에요.
target	String	Yes	대상 속성이에요.
target_format	String	No	속성 값을 다른 타입으로 캐스팅할지 정의해요. 가능한 값: auto, string, double, integer. 기본값: auto. auto로 설정하면 캐스팅하지 않아요.
preserve_source	Boolean	No	처리 후 리매핑된 소스 요소를 보존할지 여부예요. 기본값: false.
override_on_conflict	Boolean	No	대상 요소가 이미 설정되어 있을 때 덮어쓸지 여부예요. 기본값: false.

String Builder Processor

템플릿에서 출력 요소에 새 필드를 만들어요.

UI

Example input (입력 예시):

{
  "region": "us-east-1",
  "items": [
    {"name": "db-1"},
    {"name": "db-2"}
  ]
}

Configuration steps (구성 단계):

• Target attribute: $targetElem.fqdn
• Template: %{$sourceElem.name}.%{region}
• Replace missing: disabled

Result (결과):

{
  "region": "us-east-1",
  "items": [...],
  "out": [
    {"fqdn": "db-1.us-east-1"},
    {"fqdn": "db-2.us-east-1"}
  ]
}

API

{
  "type": "string-builder-processor",
  "name": "Build FQDN from element and parent attribute",
  "template": "%{$sourceElem.name}.%{region}",
  "target": "$targetElem.fqdn",
  "is_replace_missing": false
}

Parameter	Type	Required	Description
type	String	Yes	하위 프로세서 유형이에요.
name	String	No	하위 프로세서 이름이에요.
template	String	Yes	하나 이상의 속성과 원시 텍스트로 이루어진 수식이에요.
target	String	Yes	템플릿의 결과를 담는 속성 이름이에요.
is_replace_missing	Boolean	No	true면 template의 누락 속성을 모두 빈 문자열로 바꿔요. false면 누락 속성에 대해 연산을 건너뛰어요. 기본값: false.

Arithmetic Processor

요소 또는 로그 속성을 사용해 숫자 표현식을 계산하고 결과를 출력 요소에 써요.

UI

Example input (입력 예시):

{
  "items": [
    {"bytes": 1024},
    {"bytes": 2048}
  ]
}

Configuration steps (구성 단계):

• Target attribute: $targetElem.kb
• Formula: $sourceElem.bytes / 1024
• Replace missing value: disabled

Result (결과):

{
  "items": [...],
  "out": [
    {"kb": 1},
    {"kb": 2}
  ]
}

API

{
  "type": "arithmetic-processor",
  "name": "Convert bytes to KB",
  "expression": "$sourceElem.bytes / 1024",
  "target": "$targetElem.kb",
  "is_replace_missing": false
}

Parameter	Type	Required	Description
type	String	Yes	하위 프로세서 유형이에요.
name	String	No	하위 프로세서 이름이에요.
expression	String	Yes	하나 이상의 로그 속성 사이의 산술 연산이에요.
target	String	Yes	산술 연산의 결과를 담는 속성 이름이에요.
is_replace_missing	Boolean	No	true면 expression의 누락 속성을 모두 0으로 바꿔요. false면 속성이 없을 때 연산을 건너뛰어요. 기본값: false.

Category Processor

요소 속성과 일치하는 필터 쿼리를 기반으로 각 출력 요소에 카테고리를 할당해요.

UI

Example input (입력 예시):

{
  "items": [
    {"status": "critical"},
    {"status": "warning"}
  ]
}

Configuration steps (구성 단계):

• Target attribute: $targetElem.severity
• Categories:
  • @$sourceElem.status:critical과 일치하는 모든 이벤트는 값 high로 매핑돼요.
  • @$sourceElem.status:warning과 일치하는 모든 이벤트는 값 medium으로 매핑돼요.

Result (결과):

{
  "items": [...],
  "out": [
    {"severity": "high"},
    {"severity": "medium"}
  ]
}

API

{
  "type": "category-processor",
  "name": "Map status to severity",
  "target": "$targetElem.severity",
  "categories": [
    {"filter": {"query": "@$sourceElem.status:critical"}, "name": "high"},
    {"filter": {"query": "@$sourceElem.status:warning"},  "name": "medium"}
  ]
}

Parameter	Type	Required	Description
type	String	Yes	category-processor여야 해요.
name	String	No	하위 프로세서 이름이에요.
categories	Array of Object	Yes	로그에 매칭할 필터 배열과, 로그에 할당할 대응하는 사용자 지정 name 값이에요.
target	String	Yes	일치하는 카테고리가 값을 정의하는 대상 속성 이름이에요.

더 알아보기 (Learn more)

추가로 도움이 되는 문서, 링크, 아티클:

• 파이프라인 개요