본문 바로가기
WIKI 기술 지식 베이스

로그 검색 구문 (Log Search Syntax)

원문 보기 위키 갱신

로그 쿼리 필터는 용어(term)와 연산자(operator)로 구성돼요.

출처: 문서

본문

용어에는 두 가지 유형이 있어요:

  • 단일 용어(single term) 는 test나 hello 같은 단어 하나예요.
  • 시퀀스(sequence) 는 "hello dolly"처럼 큰따옴표로 감싼 단어 그룹이에요.

여러 용어를 결합해 복잡한 쿼리를 만들려면 다음 대소문자 구분 부울 연산자 중 하나를 사용할 수 있어요:

| 연산자 | 설명 | 예시 | | AND | 교집합: 두 용어 모두 선택된 이벤트에 있음 (아무것도 추가하지 않으면 기본적으로 AND가 적용) | authentication AND failure | | OR | 합집합: 두 용어 중 하나가 선택된 이벤트에 포함됨 | authentication OR password | | - | 제외: 다음 용어가 이벤트에 없음 (각 개별 원시 텍스트 검색에 적용) | authentication AND -password |

전체 텍스트 검색

⚠️ 전체 텍스트 검색 기능은 Log Management에서만 사용할 수 있고, 모니터, 대시보드, 노트북 쿼리에서 작동해요. 전체 텍스트 검색 구문은 인덱스 필터, 아카이브 필터, 로그 파이프라인 필터, 재수화 필터, 로그 기반 메트릭 필터를 정의하거나 Live Tail에서 사용할 수 없어요.

*:search_term 구문을 사용해 로그 메시지를 포함한 모든 로그 속성에서 전체 텍스트 검색을 수행해요.

단일 용어 예시

검색 구문 검색 유형 설명
*:hello Full-text 모든 로그 속성에서 정확히 hello 문자열을 검색.
hello Free text message, @title, @error.message, @error.stack 속성에서만 정확히 hello 문자열을 검색.

와일드카드가 있는 검색 용어 예시

검색 구문 검색 유형 설명
*:hello Full-text 모든 로그 속성에서 정확히 hello 문자열을 검색.
*:hello* Full-text 모든 로그 속성에서 hello로 시작하는 문자열(예: hello_world)을 검색.

여러 용어의 정확한 일치 예시

검색 구문 검색 유형 설명
*:"hello world" Full-text 모든 로그 속성에서 정확히 hello world 문자열을 검색.
hello world Free text 로그 메시지에서만 hello와 world 단어를 검색. 예: hello beautiful world.

특수 문자와 공간 이스케이프하기

다음 문자는 특수 문자로 간주되며 \ 문자로 이스케이프가 필요해요: - ! && || > >= < <= ( ) { } [ ] " * ? : \ #, 그리고 공백.

  • /는 특수 문자가 아니므로 이스케이프할 필요가 없어요.
  • @는 Attribute Search용으로 예약되어 있으므로 Logs Explorer의 검색 쿼리에서 사용할 수 없어요.

로그 메시지에서 특수 문자를 검색할 수 없어요. 특수 문자는 속성 안에 있을 때만 검색할 수 있어요.

특수 문자를 검색하려면 Grok Parser로 속성에 파싱한 다음, 그 속성을 포함하는 로그를 검색해요.

특정 속성을 검색하려면 @를 추가해 속성에서 검색하고 있음을 지정해요.

예를 들어 속성 이름이 url이고 url 값 www.datadoghq.com으로 필터링하려면:

@url:www.datadoghq.com

예약 속성 (Reserved attributes)

host, source, status, service, trace_id, message 같은 예약 속성은 @ 접두사가 필요 없어요. 이런 속성을 직접 검색할 수 있어요:

service:web-app
status:error
host:i-1234567890abcdef0

참고:

  1. 속성과 태그를 검색하기 위해 패싯을 정의할 필요는 없어요.
  2. 속성 검색은 대소문자를 구분해요. 대소문자 구분 없는 결과를 얻으려면 전체 텍스트 검색을 사용해요. 또 다른 옵션은 파싱 중 Grok 파서와 함께 lowercase 필터를 사용해 검색 중 대소문자 구분 없는 결과를 얻는 것이에요.
  3. 특수 문자를 포함하는 속성 값을 검색하려면 이스케이프 또는 큰따옴표가 필요해요.
    • 예를 들어 값이 hello:world인 my_attribute 속성은 @my_attribute:hello\:world 또는 @my_attribute:"hello:world"로 검색해요.
    • 단일 특수 문자 또는 공백과 일치시키려면 ? 와일드카드를 사용해요. 예를 들어 값이 hello world인 my_attribute 속성은 @my_attribute:hello?world로 검색해요.

예시:

검색 쿼리 설명
@http.url_details.path:"/api/v1/test" http.url_details.path 속성에서 /api/v1/test와 일치하는 모든 로그를 검색.
@http.url:/api\-v1/* http.url 속성에 /api-v1/로 시작하는 값을 포함하는 모든 로그를 검색.
@http.status_code:[200 TO 299] @http.url_details.path:/api\-v1/* http.status_code 값이 200~299 사이이고, http.url_details.path 속성에 /api-v1/로 시작하는 값을 포함하는 모든 로그를 검색.
[email protected]_code:* http.status_code 속성을 포함하지 않는 모든 로그를 검색.

CIDR 표기법으로 검색하기

Classless Inter Domain Routing (CIDR)은 IP 주소 범위(CIDR 블록이라고도 함)를 간결하게 정의할 수 있게 하는 표기법이에요. CIDR은 네트워크(예: VPC)나 서브네트워크(예: VPC 내 공용/사설 서브넷)를 정의하는 데 가장 흔히 쓰여요.

사용자는 CIDR() 함수로 CIDR 표기법을 사용해 로그의 속성을 쿼리할 수 있어요. CIDR() 함수는 필터링할 로그 속성을 매개변수로 전달한 다음, 하나 또는 여러 CIDR 블록을 이어서 전달해야 해요.

예시
  • CIDR(@network.client.ip,13.0.0.0/8)는 network.client.ip 필드에서 13.0.0.0/8 CIDR 블록 아래에 속하는 IP 주소가 있는 로그와 일치·필터링해요.
  • CIDR(@network.ip.list,13.0.0.0/8, 15.0.0.0/8)는 배열 속성 network.ip.list에서 13.0.0.0/8 또는 15.0.0.0/8 CIDR 블록 아래에 속하는 IP 주소가 있는 로그와 일치·필터링해요.
  • source:pan.firewall evt.name:reject CIDR(@network.client.ip, 13.0.0.0/8)는 13.0.0.0/8 서브넷에서 시작된 Palo Alto 방화벽의 reject 이벤트와 일치·필터링해요.
  • source:vpc NOT(CIDR(@network.client.ip, 13.0.0.0/8)) CIDR(@network.destination.ip, 15.0.0.0/8)는 13.0.0.0/8 서브넷에서 시작되지 않고 15.0.0.0/8 대상 서브넷으로 지정된 모든 VPC 로그를 보여줘요. 환경의 서브넷 간 네트워크 트래픽을 분석하고 싶을 때 쓸 수 있어요.

CIDR() 함수는 IPv4와 IPv6 CIDR 표기법을 모두 지원하며, Log Explorer, Live Tail, 대시보드의 로그 위젯, 로그 모니터, 로그 구성에서 작동해요.

와일드카드

자유 텍스트 검색에서 와일드카드를 사용할 수 있어요. 하지만 로그 메시지(Log Explorer의 content 컬럼 텍스트)의 용어만 검색해요. 로그 속성의 값을 검색하려면 Full-text search를 참고해요.

다중 문자 와일드카드

로그 메시지(Log Explorer의 content 컬럼)에서 다중 문자 와일드카드 검색을 수행하려면 * 기호를 다음과 같이 사용해요:

  • service:web*는 web로 시작하는 서비스를 가진 모든 로그 메시지와 일치해요.
  • web*는 web로 시작하는 모든 로그 메시지와 일치해요.
  • *web는 web으로 끝나는 모든 로그 메시지와 일치해요.

참고: 와일드카드는 큰따옴표 밖에서만 와일드카드로 작동해요. 예를 들어 "*test*"는 메시지에 *test* 문자열이 있는 로그와 일치해요. *test*는 메시지 어디든 test 문자열이 있는 로그와 일치해요.

와일드카드 검색은 이 구문으로 태그와 속성(패싯 여부와 무관)에서 작동해요. 이 쿼리는 mongo 문자열로 끝나는 모든 서비스를 반환해요:

service:*mongo

와일드카드 검색은 로그 속성이 아닌 로그의 일반 텍스트에서도 검색할 수 있어요. 예를 들어 이 쿼리는 NETWORK 문자열을 포함하는 콘텐츠(메시지)가 있는 모든 로그를 반환해요:

*NETWORK*

다만 이 검색 용어는 NETWORK 문자열이 로그 메시지가 아닌 로그 속성에 있을 때는 그 로그를 반환하지 않아요.

검색 와일드카드

특수 문자를 포함하거나 이스케이프·큰따옴표가 필요한 속성 또는 태그 값을 검색할 때는 ? 와일드카드를 사용해 단일 특수 문자나 공백과 일치시켜요. 예를 들어 값이 hello world인 my_attribute 속성을 검색하려면: @my_attribute:hello?world.

숫자 값 (Numerical values)

숫자 속성을 검색하려면 먼저 패싯으로 추가해요. 그런 다음 숫자 연산자(<, >, <=, >=)를 사용해 숫자 패싯을 검색할 수 있어요. 예를 들어 응답 시간이 100ms를 초과하는 모든 로그를 가져오려면:

@http.response_time:>100

특정 범위 내의 숫자 속성을 검색할 수 있어요. 예를 들어 4xx 오류를 모두 가져오려면:

@http.status_code:[400 TO 499]

태그 (Tags)

로그는 태그를 만든 호스트와 통합에서 태그를 상속받아요. 검색과 패싯으로도 사용할 수 있어요:

  • test는 문자열 "test"를 검색해요.
  • env:(prod OR test)는 env:prod 태그 또는 env:test 태그가 있는 모든 로그와 일치해요.
  • (env:prod AND -version:beta)는 env:prod 태그를 포함하고 version:beta 태그는 포함하지 않는 모든 로그와 일치해요.

태그가 태그 모범 사례를 따르지 않고 key:value 구문을 사용하지 않으면 이 검색 쿼리를 사용해요:

  • tags:<MY_TAG>

배열 (Arrays)

다음 예시에서 패싯에서 Peter 값을 클릭하면 users.names 속성을 포함하고, 그 값이 Peter이거나 Peter를 포함하는 배열인 모든 로그가 반환돼요.

참고: 패싯화되지 않은 배열 속성에서도 동일한 구문으로 검색할 수 있어요.

다음 예시에서 Windows용 CloudWatch 로그는 @Event.EventData.Data 아래에 JSON 객체 배열을 포함해요. JSON 객체 배열에는 패싯을 만들 수 없지만 다음 구문으로 검색할 수 있어요.

  • @Event.EventData.Data.Name:ObjectServer는 Name 키와 ObjectServer 값이 있는 모든 로그와 일치해요.

중첩 배열 검색

배열 속성의 중첩 필드를 검색하려면 전체 속성 경로와 함께 @ 접두사를 사용해요. Log Explorer는 배열의 어떤 항목이든 일치해요:

  • @network.ip.attributes.ip:2a02\:1810*는 network.ip.attributes 배열에서 어떤 항목이라도 2a02:1810으로 시작하는 ip 필드를 가진 모든 로그와 일치해요.

배열에 여러 특정 값이 포함된 로그를 일치시키려면 값을 괄호 안에 나열해요:

  • @user_perms:(4 6)는 user_perms 배열에 4와 6을 모두 포함하는 모든 로그와 일치해요.

배열에 범위 내의 값을 하나라도 포함하는 로그를 일치시키려면 범위 쿼리를 사용해요:

  • @user_perms:[2 TO 6]는 user_perms 배열에 2와 6 사이의 값을 하나 이상 포함하는 모든 로그와 일치해요.

계산 필드 (Calculated fields)

계산 필드는 로그 속성처럼 동작하며 검색, 집계, 시각화, 그리고 다른 계산 필드 정의에 사용할 수 있어요. 계산 필드 이름을 참조하려면 # 접두사를 사용해요.

저장된 검색 (Saved searches)

Saved Views는 검색 쿼리, 컬럼, 시간 범위, 패싯을 포함해요.

더 알아보기 (Learn more)