공통 표현식 언어: CEL 입력을 사용해 Elastic에서 데이터 수집 기능 향상

Agent Builder는 이제 이제 정식 버전으로 이용 가능합니다. Elastic Cloud 체험판으로 시작하고, 여기에서 Agent Builder 문서를 확인 해 보세요.

사용자는 Elastic Agent 통합을 통해 다양한 소스에서 Elasticsearch로 데이터를 수집할 수 있습니다. 수집 논리, 인제스트 파이프라인, 대시보드 및 기타 아티팩트를 Kibana 웹 인터페이스에서 설치 및 관리 가능한 패키지로 결합할 수 있습니다.

통합은 데이터 수집을 수행하도록 Filebeat 입력을 구성합니다. HTTP API에서 데이터를 수집하는 데 종종 HTTP JSON 입력이 사용되었습니다. 그러나 기본적인 목록 조회 API도 세부 사항에서 크게 차이가 날 수 있으며, HTTP JSON 입력의 YAML 기반 변환 모델에서는 필요한 수집 논리를 표현하는 것이 불편하거나 불가능한 경우가 있습니다.

공통 표현식 언어(CEL) 입력은 HTTP API와 보다 유연한 상호 작용을 촉진하기 위해 도입되었습니다. CEL은 빠르고 안전하며 확장 가능한 방식으로 조건과 데이터 변환을 표현해야 하는 애플리케이션에 내장되도록 설계된 언어입니다. 통합 빌더는 CEL 입력을 통해 설정을 읽고, 자체 상태를 추적하고, 요청을 생성하고, 응답을 처리하고, 궁극적으로 수집할 준비가 된 이벤트를 반환하는 하나의 표현식을 작성할 수 있습니다.

이 글에서는 CEL이 다른 프로그래밍 언어와 어떻게 다른지, CEL 입력을 위해 어떻게 확장되었는지, 또 데이터 수집 논리를 표현하는 데 어떤 유연성과 장점을 제공하는지 살펴보겠습니다.

CEL과 입력에서의 작동 원리

CEL은 표현식 언어입니다. 진술이 아닙니다. CEL을 작성할 때는 명령문으로 무엇을 할지 지시하는 것이 아니라, 표현식으로 어떤 값을 생성할지 정의합니다. 모든 CEL 표현식은 값을 생성하며, 더 작은 표현식을 결합하여 복잡한 규칙에 따른 결과를 만들어낼 수 있습니다. 다른 언어에서 명령문으로 작성되는 기능을 표현식으로 구현하는 방법을 나중에 살펴보겠습니다.

CEL은 의도적으로 튜링 완전 언어가 아닙니다. 무제한 루프를 허용하지 않습니다. 매크로를 사용하여 리스트와 맵을 처리하는 방법을 후에 살펴보겠지만, 무한 루프를 방지함으로써 개별 표현식에 대해 예측 가능하고 제한된 실행 시간을 보장합니다.

CEL 입력은 CEL 프로그램(표현식)과 몇 가지 초기 상태로 구성됩니다. 상태는 프로그램에 대한 입력으로 제공되고, 프로그램은 평가를 통해 출력 상태를 생성합니다. 출력 상태에 이벤트 목록이 포함되어 있으면 해당 이벤트가 제거되고 게시됩니다. 나머지 출력 상태는 다음 평가를 위한 입력으로 사용됩니다. 출력 상태에 하나 이상의 이벤트와 플래그 want_more: true가 포함되어 있으면 즉시 다음 평가가 수행되고, 포함되어 있지 않은 경우에는 구성된 시간 동안 대기한 후 진행됩니다. 다음은 입력의 제어 흐름을 간략하게 나타낸 다이어그램입니다.

각 평가의 출력은 입력이 실행되는 동안 다음 평가의 입력으로 전달됩니다. "cursor" 키 아래의 출력 데이터는 디스크에 보존되어 입력이 재시작된 후 다시 로드되지만, 나머지 상태는 재시작 시 보존되지 않습니다.

CEL 언어 자체는 기능이 제한적이며 부작용을 방지하지만, 확장 가능합니다. cel-go 구현은 선택적 구문 및 유형과 같은 기능을 추가합니다. Mito 라이브러리는 cel-go를 기반으로 빌드되어 HTTP 요청 기능을 포함한 더 많은 기능을 추가합니다. CEL 입력은 Mito의 CEL 버전을 사용합니다.

Mito와 함께 작동

CEL 입력을 사용하여 통합을 빌드하거나 디버깅할 때는 CEL 프로그램이 주어진 입력 상태에 대해 생성할 출력 상태를 이해하는 것이 가장 중요합니다. 개발 중에는 전체 Elastic 스택 환경에서 입력을 통해 CEL 프로그램을 실행하는 것이 번거로울 수 있습니다. Mito의 명령줄 도구를 사용하면 더 빠른 피드백 루프를 구현해 CEL 프로그램을 직접 실행하고 주어진 입력에 대한 출력 결과를 바로 확인할 수 있습니다.

Mito는 Go 언어로 작성되었으며 다음과 같이 설치할 수 있습니다.

Mito로 CEL 프로그램을 실행할 때 일반적으로 두 개의 파일을 제공해야 합니다. 하나는 초기 입력 상태를 포함한 JSON 파일이고, 다른 하나는 CEL 프로그램의 소스 코드가 포함된 파일입니다.

쉽게 복사하여 붙여넣을 수 있도록 이 글의 예시는 각 파일의 내용을 <(echo '...content...') 로 감싸서 셸이 임시 파일을 즉시 생성하도록 하는 단일 명령으로 작성되었습니다. 자체 개발 시에는 실제 파일을 다루는 것이 더 쉬울 수 있습니다.

GitHub에서 이슈 데이터 가져오기

다음 예시에서는 GitHub API에서 이슈 데이터를 가져오는 전체 CEL 프로그램을 볼 수 있습니다. 초기 입력 상태에는 API 엔드포인트의 URL과 페이지네이션 처리 방식에 대한 정보가 포함되어 있습니다. CEL 프로그램은 입력 상태의 데이터를 사용하여 요청을 생성합니다. 응답을 디코딩하고, 그로부터 이벤트를 생성한 다음, 이를 출력 상태의 일부로 반환합니다.

첫 번째 평가는 다음과 같은 출력을 생성합니다.

이벤트가 제거되고 CEL 입력에서 실행되면 수집을 위해 게시됩니다. 나머지 출력 결과는 다음 CEL 프로그램 평가의 입력 상태로 제공됩니다.

CEL 프로그램의 작동 방식을 이해하기 위해, 몇 가지 쉬운 CEL 예시시를 살펴보면서CEL 입력이 작동하는 방식에 대해 자세히 알아보겠습니다.

CEL 기본 사항

CEL 언어에는 문이 없고 표현식만 있습니다. 모든 성공적인 CEL 표현식은 최종 값으로 평가됩니다. 다음은 출력과 함께 작성할 수 있는 가장 간단한 CEL 표현식 중 하나입니다.

간단한 표현식은 대개 직관적입니다. 수학적 연산은 같은 유형의 값(예시: int를 가진 int)에만 지원되므로 필요에 따라 (여기에서는int 에서 double로) 유형을 변환합니다.

CEL 언어에는 변수가 없지만, Mito의 as 매크로를 이용해 표현식에 이름을 부여하고 더 큰 표현식에서 사용할 수 있습니다. 이 예시에서 (1 + 1) 표현식은 2 값으로 평가되고 .as(n, ...)는 해당 값에 n 라는 이름을 부여하여 "one plus one is "+string(n) 표현식에서 사용합니다.

또한 with 를 사용한 예처럼 맵에 정보를 축적하고 나중에 표현식에서 사용할 수도 있습니다.

이 예시를 다시 살펴보세요. 중첩된 부분 ({ "data": data, "size": size(data), })은 최종 값의 형태를 제공합니다. "data" 및 "size" 키를 포함한 맵입니다. 이러한 키의 값은 표현식의 외부 부분에 정의된 data에 따라 달라집니다. CEL 표현식을 안쪽에서 바깥쪽으로 읽으면 반환되는 내용을 빠르게 파악하는 데 도움이 됩니다.

CEL에는 if와 같은 제어 흐름 문이 없지만, 삼항 연산자를 사용해 조건부 분기를 수행할 수 있습니다:

CEL은 튜링 완전 언어가 아니기 때문에 무한 루프와 재귀가 지원되지 않습니다. 따라서 실행 시간을 예측할 수 있으며 , 이는 입력 데이터의 크기와 표현식의 복잡성에 비례합니다.

개별 CEL 표현식에서는 무한 루프가 불가능하지만, map 과 같은 매크로를 사용해 목록과 맵을 처리할 수 있습니다.

이 섹션에서는 다음과 같은 내용을 다룹니다.

스트링, 숫자, 리스트, 맵
스트링 연결
수학 연산
유형 캐스팅
조건문
하위 표현식의 이름 지정
컬렉션 처리

다음으로 HTTP 요청을 하는 방법을 살펴보겠습니다.

요청

Mito는 CEL을 확장해 HTTP 요청을 만드는 기능을 추가합니다.

실행되기 전에 명시적으로 요청을 구성할 수 있습니다. 이를 통해 다양한 HTTP 메서드를 사용하고 헤더와 본문을 추가할 수 있습니다.

이 예시에서는 format_query의 도움을 받아 URL을 만들고, 요청에 헤더를 추가한 뒤, 응답 본문을 decode_json으로 구문 분석합니다. -log_requests 옵션이 주어지면 Mito는 각 요청 및 응답에 대한 자세한 정보를 JSON 형식으로 로그에 기록합니다.

상태 관리 및 평가

이제 요청 방법과 원하는 출력 상태를 생성하는 데 필요한 CEL 기본 사항을 알아보았으니 출력 상태에 무엇을 넣어야 하는지, 그리고 이것이 이후 처리를 어떻게 지시하는지 자세히 살펴보겠습니다.

통합의 CEL 프로그램은 출력 상태가 다음 평가의 입력으로 적합하게 사용될 수 있도록 해야 합니다. 구성은 초기 상태를 설정하며, 적절한 변경이 있을 경우 출력에서 이를 반복해야 합니다. 이를 수행하는 쉬운 방법은 state.with({ ... }) 를 사용해 일부 재정의와 함께 상태 맵을 반복하는 것입니다. 작은 프로그램에서는 전체 프로그램을 state.with()로 감싸서 상태 전파가 출력 데이터를 생성하는 각 분기(예시: 성공, 오류)에서 반복되지 않도록 하는 패턴이 자주 사용됩니다.

상태 값이 초기 입력 상태에 하드코딩되지 않고 평가를 통해 초기화되는 경우, 프로그램은 초기값을 설정하기 전에 기존 값이 있는지 확인해야 합니다. 선택적 구문 및 유형에 대한 지원이 이러한 문제를 해결하는 데 도움이 될 수 있습니다. 맵 키에서 필드 이름 앞에 물음표를 사용하면 액세스가 선택 사항이 됩니다. 값으로 확인될 수도 있고 확인되지 않을 수도 있지만, 추가 선택적 액세스가 가능하며 값이 없는 경우 기본값을 쉽게 제공할 수 있습니다:

이 예시의 상태에서 읽은 카운터 값은 JSON과 JavaScript의 Number 유형이 정한 관례에 따라 부동소수점 숫자로 직렬화되어 있으므로 int로 캐스팅됩니다. 또한 여기서 "want_more": true는 Mito에 의해 존중되지만, CEL 입력에서 실행될 때는 출력에 이벤트가 포함될 때만 평가가 반복된다는 점에 유의해야 합니다.

CEL 입력으로 실행되는 CEL 프로그램의 경우 출력 맵에 "events" 키를 반환해야 합니다. 이 값은 이벤트 맵의 목록, 빈 목록 또는 단일 이벤트 맵일 수 있습니다. 단일 이벤트 사례는 일반적으로 오류 처리에 사용됩니다. 이벤트는 입력에 의해 게시되지만 해당 값도 로그에 기록되며, error.message 값이 설정되면 해당 값이 통합의 Fleet 상태를 업데이트하는 데 사용됩니다. 프로그램에서 오류가 아닌 단일 이벤트를 생성하는 경우 목록으로 래핑하는 것이 가장 좋습니다.

앞서 살펴본 GitHub 이슈 프로그램의 결과를 다시 한 번 살펴보세요.

이 프로그램은 다음과 같은 방법으로 상태를 효과적으로 관리했습니다.

url, per_page, max_pages에서 초기 상태 값을 반복합니다.
cursor.page에서 재시작 후 지속되어야 할 상태를 추가합니다.
events 목록에 게시할 준비가 된 이벤트를 반환합니다.
want_more: true를 사용해 즉각적인 재평가를 요청합니다.

선택적 액세스 및 상태 관리, CEL 기본 사항 및 HTTP 요청에 대해 배워보았으니, 이제 전체 GitHub 이슈 프로그램을 읽을 수 있습니다. Mito로 실행하고 몇 가지 변경 사항을 실험해 보세요.

검토 및 리소스

이 글에서는 CEL 언어가 무엇인지, 그리고 Mito 라이브러리에서 CEL 입력에 사용하기 위해 어떻게 확장되었는지 알아봤습니다. GitHub API에서 이슈 정보를 가져오는 예제 프로그램에서 CEL의 유연성을 살펴보고, 초기 상태의 설정 액세스, HTTP API와의 상호작용, 수집할 이벤트 반환, 이후 프로그램 실행을 위한 상태 관리 등 해당 프로그램을 이해하는 데 필요한 모든 세부 사항을 살펴봤습니다.

CEL 입력을 사용하여 통합 기능을 구축하고 자세히 알아보려면 다음과 같은 여러 자료를 살펴보시기 바랍니다.

CEL 입력을 활용한 통합 구축에 있어 가장 유용한 리소스 중 하나는 GitHub에서 찾아볼 수 있는 기존 Elastic 통합의 CEL 코드입니다.

cel.yml.hbs Elastic 통합 리포지토리에 저장된 파일 - GitHub

문제 신고하기