PATTERNS 명령어

PATTERNS 명령어

patterns 명령어는 텍스트 필드에서 로그 패턴을 추출하고 결과를 검색 결과에 추가해요. 로그를 패턴별로 그룹화하면 대량의 로그 데이터에서 분석과 문제 해결을 위한 통계 집계를 단순화할 수 있어요.

출처: 문서

본문

patterns 명령어는 텍스트 필드에서 로그 패턴을 추출하고 결과를 검색 결과에 추가해요. 로그를 패턴별로 그룹화하면 대량의 로그 데이터에서 분석과 문제 해결을 위한 통계 집계를 단순화해요. 높은 패턴 그룹화 정확도를 얻기 위해 다음 로그 파싱 방법 중에서 선택할 수 있어요:

patterns 명령어는 다음 모드를 지원해요:

이 명령어는 로그 메시지의 변수 부분(타임스탬프, 숫자, IP 주소, 고유 식별자 등)을 식별하고 이를 <*> 자리 표시자로 대체해 재사용 가능한 패턴을 만들 수 있어요. 예를 들어 [email protected]과 [email protected] 같은 이메일 주소는 <*>@<*>.<*> 패턴으로 대체돼요.

patterns 명령어는 OpenSearch 데이터 노드에서 실행되지 않아요. 코디네이팅(coordinating) 노드로 반환된 로그 메시지에서만 로그 패턴을 그룹화해요.

구문 (Syntax)

patterns 명령어는 다음 구문 옵션을 지원해요.

Simple pattern 메서드 구문

simple_pattern 메서드의 patterns 명령어 구문은 다음과 같아요:

patterns <field> [by <byClause>] [method=simple_pattern] [mode=label | aggregation] [max_sample_count=integer] [show_numbered_token=boolean] [new_field=<new-field-name>] [pattern=<regex-pattern>]

Brain 메서드 구문

brain 메서드의 patterns 명령어 구문은 다음과 같아요:

patterns <field> [by <byClause>] [method=brain] [mode=label | aggregation] [max_sample_count=integer] [buffer_limit=integer] [show_numbered_token=boolean] [new_field=<new-field-name>] [variable_count_threshold=integer] [frequency_threshold_percentage=decimal]

매개변수 (Parameters)

patterns 명령어는 다음 매개변수를 지원해요.

매개변수 필수/선택 설명
<field> 필수 로그 패턴을 추출하기 위해 분석하는 텍스트 필드예요.
<byClause> 선택 라벨링이나 집계 전에 로그를 그룹화하는 데 사용되는 필드 또는 스칼라 함수예요.
method 선택 사용할 패턴 추출 메서드예요. 유효한 값은 simple_pattern과 brain이에요. 기본값은 simple_pattern이에요.
mode 선택 명령어의 출력 모드예요. 유효한 값은 label과 aggregation이에요. 기본값은 label이에요.
max_sample_count 선택 집계 모드에서 패턴당 반환되는 샘플 로그 항목의 최대 수예요. 기본값은 10이에요.
buffer_limit 선택 brain 메서드의 내부 임시 버퍼 크기를 제한하는 안전장치 설정이에요. 최소값은 50000이에요. 기본값은 100000이에요.
show_numbered_token 선택 기본 와일드카드 토큰 대신 출력에 번호가 매겨진 토큰 자리 표시자를 활성화해요. Placeholder behavior(자리 표시자 동작)를 참고해요. 기본값은 false예요.
<new_field> 선택 추출된 패턴이 포함된 출력 필드의 별칭이에요. 기본값은 patterns_field예요.

simple_pattern 메서드는 다음 매개변수를 허용해요.

매개변수 필수/선택 설명
<pattern> 선택 <*> 자리 표시자로 대체할 문자 또는 시퀀스를 식별하는 사용자 지정 Java 정규 표현식 패턴이에요. 지정하지 않으면 메서드는 알파벳 숫자 문자를 자동으로 제거하고 구조 요소를 보존하면서 변수 부분을 <*> 자리 표시자로 대체하는 기본 패턴을 사용해요.

brain 메서드는 다음 매개변수를 허용해요.

매개변수 필수/선택 설명
variable_count_threshold 선택 초기 로그 그룹의 특정 위치에서 서로 다른 단어를 세어 상수 단어 감지에 대한 알고리즘 민감도를 제어해요. 기본값은 5예요.
frequency_threshold_percentage 선택 최소 단어 빈도 비율 임계값을 설정해요. 이 값보다 낮은 빈도의 단어는 무시돼요. brain 알고리즘은 가장 긴 단어 조합을 기반으로 로그 패턴을 선택해요. 기본값은 0.3이에요.

자리 표시자 동작 (Placeholder behavior)

기본적으로 Apache Calcite 엔진은 <*> 자리 표시자를 사용해 변수를 라벨링해요. show_numbered_token 옵션이 활성화되면 Calcite 엔진의 label 모드는 텍스트 패턴을 라벨링할 뿐만 아니라 변수 토큰에도 번호가 매겨진 자리 표시자를 할당해요. 집계 모드에서는 각 패턴에 대해 라벨링된 패턴과 변수 토큰을 모두 출력해요. 이 경우 변수 자리 표시자는 <*> 대신 <token%d> 형식을 사용해요.

기본 패턴 메서드 변경하기

기본 패턴 매개변수를 재정의하려면 다음 명령어를 실행해요:

PUT _cluster/settings
{
  "persistent": {
    "plugins.ppl.pattern.method": "brain",
    "plugins.ppl.pattern.mode": "aggregation",
    "plugins.ppl.pattern.max.sample.count": 5,
    "plugins.ppl.pattern.buffer.limit": 50000,
    "plugins.ppl.pattern.show.numbered.token": true
  }
}

Simple pattern 예제

다음은 simple_pattern 메서드 사용 예제예요.

예제 1: 로그 메시지에서 패턴 추출하기

다음 쿼리는 오류 로그 메시지에서 패턴을 추출하고 변수 부분을 <*> 자리 표시자로 대체해요:

source=otellogs
| where severityText = 'ERROR'
| patterns body method=simple_pattern
| fields body, patterns_field
| head 3

쿼리는 다음과 같은 결과를 반환해요:

body patterns_field
Payment failed: connection timeout to payment gateway after 30000ms <*> <*>: <*> <*> <*> <*> <*> <*> <*>
NullPointerException in CheckoutService.placeOrder at line 142 <*> <*> <*>.<*> <*> <*> <*>
Out of memory: Java heap space - shutting down pod payment-6f8d4b-ht7q3 <*> <*> <*>: <*> <*> <*> - <*> <*> <*> <*>-<*>-<*>

예제 2: 로그 패턴 추출하기

다음 쿼리는 원시 로그 필드에서 기본 패턴을 추출해요:

source=apache
| patterns message method=simple_pattern
| fields message, patterns_field

쿼리는 다음과 같은 결과를 반환해요:

message patterns_field
177.95.8.74 - upton5450 [28/Sep/2022:10:15:57 -0700] “HEAD /e-business/mindshare HTTP/1.0” 404 19927 <*>.<*>.<*>.<*> - <*> [<*>/<*>/<*>:<*>:<*>:<*> -<*>] “<*> /<*>-<*>/<*> <*>/<*>.<*>” <*> <*>
127.45.152.6 - pouros8756 [28/Sep/2022:10:15:57 -0700] “GET /architectures/convergence/niches/mindshare HTTP/1.0” 100 28722 <*>.<*>.<*>.<*> - <*> [<*>/<*>/<*>:<*>:<*>:<*> -<*>] “<*> /<*>/<*>/<*>/<*> <*>/<*>.<*>” <*> <*>
118.223.210.105 - - [28/Sep/2022:10:15:57 -0700] “PATCH /strategize/out-of-the-box HTTP/1.0” 401 27439 <*>.<*>.<*>.<*> - - [<*>/<*>/<*>:<*>:<*>:<*> -<*>] “<*> /<*>/<*>-<*>-<*>-<*> <*>/<*>.<*>” <*> <*>
210.204.15.104 - - [28/Sep/2022:10:15:57 -0700] “POST /users HTTP/1.1” 301 9481 <*>.<*>.<*>.<*> - - [<*>/<*>/<*>:<*>:<*>:<*> -<*>] “<*> /<*> <*>/<*>.<*>” <*> <*>

예제 3: 사용자 지정 regex 패턴으로 로그 패턴 추출하기

다음 쿼리는 사용자 지정 패턴을 사용해 원시 로그 필드에서 패턴을 추출해요:

source=apache
| patterns message method=simple_pattern new_field='no_numbers' pattern='[0-9]'
| fields message, no_numbers

쿼리는 다음과 같은 결과를 반환해요:

message no_numbers
177.95.8.74 - upton5450 [28/Sep/2022:10:15:57 -0700] “HEAD /e-business/mindshare HTTP/1.0” 404 19927 <*><*><*>.<*><*>.<*>.<*><*> - upton<*><*><*><*> [<*><*>/Sep/<*><*><*><*>:<*><*>:<*><*>:<*><*> -<*><*><*><*>] “HEAD /e-business/mindshare HTTP/<*>.<*>” <*><*><*> <*><*><*><*><*>
127.45.152.6 - pouros8756 [28/Sep/2022:10:15:57 -0700] “GET /architectures/convergence/niches/mindshare HTTP/1.0” 100 28722 <*><*><*>.<*><*>.<*><*><*>.<*> - pouros<*><*><*><*> [<*><*>/Sep/<*><*><*><*>:<*><*>:<*><*>:<*><*> -<*><*><*><*>] “GET /architectures/convergence/niches/mindshare HTTP/<*>.<*>” <*><*><*> <*><*><*><*><*>
118.223.210.105 - - [28/Sep/2022:10:15:57 -0700] “PATCH /strategize/out-of-the-box HTTP/1.0” 401 27439 <*><*><*>.<*><*><*>.<*><*><*>.<*><*><*> - - [<*><*>/Sep/<*><*><*><*>:<*><*>:<*><*>:<*><*> -<*><*><*><*>] “PATCH /strategize/out-of-the-box HTTP/<*>.<*>” <*><*><*> <*><*><*><*><*>
210.204.15.104 - - [28/Sep/2022:10:15:57 -0700] “POST /users HTTP/1.1” 301 9481 <*><*><*>.<*><*><*>.<*><*>.<*><*><*> - - [<*><*>/Sep/<*><*><*><*>:<*><*>:<*><*>:<*><*> -<*><*><*><*>] “POST /users HTTP/<*>.<*>” <*><*><*> <*><*><*><*>

예제 4: 로그 패턴 집계 결과 반환하기

다음 쿼리는 원시 로그 필드에서 추출된 패턴을 집계해요:

source=apache
| patterns message method=simple_pattern mode=aggregation
| fields patterns_field, pattern_count, sample_logs

쿼리는 다음과 같은 결과를 반환해요:

patterns_field pattern_count sample_logs
<*>.<*>.<*>.<*> - - [<*>/<*>/<*>:<*>:<*>:<*> -<*>] “<*> /<*> <*>/<*>.<*>” <*> <*> 1 [210.204.15.104 - - [28/Sep/2022:10:15:57 -0700] “POST /users HTTP/1.1” 301 9481]
<*>.<*>.<*>.<*> - - [<*>/<*>/<*>:<*>:<*>:<*> -<*>] “<*> /<*>/<*>-<*>-<*>-<*> <*>/<*>.<*>” <*> <*> 1 [118.223.210.105 - - [28/Sep/2022:10:15:57 -0700] “PATCH /strategize/out-of-the-box HTTP/1.0” 401 27439]
<*>.<*>.<*>.<*> - <*> [<*>/<*>/<*>:<*>:<*>:<*> -<*>] “<*> /<*>-<*>/<*> <*>/<*>.<*>” <*> <*> 1 [177.95.8.74 - upton5450 [28/Sep/2022:10:15:57 -0700] “HEAD /e-business/mindshare HTTP/1.0” 404 19927]
<*>.<*>.<*>.<*> - <*> [<*>/<*>/<*>:<*>:<*>:<*> -<*>] “<*> /<*>/<*>/<*>/<*> <*>/<*>.<*>” <*> <*> 1 [127.45.152.6 - pouros8756 [28/Sep/2022:10:15:57 -0700] “GET /architectures/convergence/niches/mindshare HTTP/1.0” 100 28722]

예제 5: 감지된 변수 토큰과 함께 집계된 로그 패턴 반환하기

다음 쿼리는 감지된 변수 토큰과 함께 집계된 결과를 반환해요. show_numbered_token 옵션이 활성화되면 패턴 출력은 번호가 매겨진 자리 표시자(예: <token1>, <token2>)를 사용하고 각 자리 표시자가 나타내는 값에 대한 매핑을 반환해요:

source=apache
| patterns message method=simple_pattern mode=aggregation show_numbered_token=true
| fields patterns_field, pattern_count, tokens
| head 1

쿼리는 다음과 같은 결과를 반환해요:

patterns_field pattern_count tokens
<token1>.<token2>.<token3>.<token4> - - [<token5>/<token6>/<token7>:<token8>:<token9>:<token10> -<token11>] “<token12> /<token13> <token14>/<token15>.<token16>” <token17> <token18> 1 {‘’: [‘HTTP’], ‘’: [‘users’], ‘’: [‘1’], ‘’: [‘1’], ‘’: [‘9481’], ‘’: [‘301’], ‘’: [‘28’], ‘’: [‘104’], ‘’: [‘2022’], ‘’: [‘Sep’], ‘’: [‘15’], ‘’: [‘10’], ‘’: [‘57’], ‘’: [‘210’], ‘’: [‘POST’], ‘’: [‘15’], ‘’: [‘0700’], ‘’: [‘204’]}

Brain pattern 예제

다음은 brain 메서드 사용 예제예요.

예제 1: 로그 패턴 추출하기

다음 쿼리는 brain 알고리즘을 사용해 원시 로그 필드에서 의미적으로 의미 있는 로그 패턴을 추출해요. 이 쿼리는 기본 variable_count_threshold 값 5를 사용해요:

source=apache
| patterns message method=brain
| fields message, patterns_field

쿼리는 다음과 같은 결과를 반환해요:

message patterns_field
177.95.8.74 - upton5450 [28/Sep/2022:10:15:57 -0700] “HEAD /e-business/mindshare HTTP/1.0” 404 19927 <*IP*> - <*> [<*>/Sep/<*>:<*>:<*>:<*> <*>] “HEAD /e-business/mindshare HTTP/<*>” 404 <*>
127.45.152.6 - pouros8756 [28/Sep/2022:10:15:57 -0700] “GET /architectures/convergence/niches/mindshare HTTP/1.0” 100 28722 <*IP*> - <*> [<*>/Sep/<*>:<*>:<*>:<*> <*>] “GET /architectures/convergence/niches/mindshare HTTP/<*>” 100 <*>
118.223.210.105 - - [28/Sep/2022:10:15:57 -0700] “PATCH /strategize/out-of-the-box HTTP/1.0” 401 27439 <*IP*> - - [<*>/Sep/<*>:<*>:<*>:<*> <*>] “PATCH /strategize/out-of-the-box HTTP/<*>” 401 <*>
210.204.15.104 - - [28/Sep/2022:10:15:57 -0700] “POST /users HTTP/1.1” 301 9481 <*IP*> - - [<*>/Sep/<*>:<*>:<*>:<*> <*>] “POST /users HTTP/<*>” 301 <*>

예제 2: 사용자 지정 매개변수로 로그 패턴 추출하기

다음 쿼리는 brain 알고리즘의 사용자 지정 매개변수를 사용해 원시 로그 필드에서 의미적으로 의미 있는 로그 패턴을 추출해요:

source=apache
| patterns message method=brain variable_count_threshold=2
| fields message, patterns_field

쿼리는 다음과 같은 결과를 반환해요:

message patterns_field
177.95.8.74 - upton5450 [28/Sep/2022:10:15:57 -0700] “HEAD /e-business/mindshare HTTP/1.0” 404 19927 <*IP*> - <*> [<*>/Sep/<*>:<*>:<*>:<*> <*>] <*> <*> HTTP/<*>” <*> <*>
127.45.152.6 - pouros8756 [28/Sep/2022:10:15:57 -0700] “GET /architectures/convergence/niches/mindshare HTTP/1.0” 100 28722 <*IP*> - <*> [<*>/Sep/<*>:<*>:<*>:<*> <*>] <*> <*> HTTP/<*>” <*> <*>
118.223.210.105 - - [28/Sep/2022:10:15:57 -0700] “PATCH /strategize/out-of-the-box HTTP/1.0” 401 27439 <*IP*> - <*> [<*>/Sep/<*>:<*>:<*>:<*> <*>] <*> <*> HTTP/<*>” <*> <*>
210.204.15.104 - - [28/Sep/2022:10:15:57 -0700] “POST /users HTTP/1.1” 301 9481 <*IP*> - <*> [<*>/Sep/<*>:<*>:<*>:<*> <*>] <*> <*> HTTP/<*>” <*> <*>

예제 3: 로그 패턴 집계 결과 반환하기

다음 쿼리는 brain 알고리즘을 사용해 원시 로그 필드에서 추출된 패턴을 집계해요:

source=apache
| patterns message method=brain mode=aggregation variable_count_threshold=2
| fields patterns_field, pattern_count, sample_logs

쿼리는 다음과 같은 결과를 반환해요:

patterns_field pattern_count sample_logs
<*IP*> - <*> [<*>/Sep/<*>:<*>:<*>:<*> <*>] <*> <*> HTTP/<*>” <*> <*> 4 [177.95.8.74 - upton5450 [28/Sep/2022:10:15:57 -0700] “HEAD /e-business/mindshare HTTP/1.0” 404 19927,127.45.152.6 - pouros8756 [28/Sep/2022:10:15:57 -0700] “GET /architectures/convergence/niches/mindshare HTTP/1.0” 100 28722,118.223.210.105 - - [28/Sep/2022:10:15:57 -0700] “PATCH /strategize/out-of-the-box HTTP/1.0” 401 27439,210.204.15.104 - - [28/Sep/2022:10:15:57 -0700] “POST /users HTTP/1.1” 301 9481]

예제 4: 감지된 변수 토큰과 함께 집계된 로그 패턴 반환하기

다음 쿼리는 brain 메서드를 사용해 감지된 변수 토큰과 함께 집계된 결과를 반환해요. show_numbered_token 옵션이 활성화되면 패턴 출력은 번호가 매겨진 자리 표시자(예: <token1>, <token2>)를 사용하고 각 자리 표시자가 나타내는 값에 대한 매핑을 반환해요:

source=apache
| patterns message method=brain mode=aggregation show_numbered_token=true variable_count_threshold=2
| fields patterns_field, pattern_count, tokens

쿼리는 다음과 같은 결과를 반환해요:

patterns_field pattern_count tokens
<token1> - <token2> [<token3>/Sep/<token4>:<token5>:<token6>:<token7> <token8>] <token9> <token10> HTTP/<token11>” <token12> <token13> 4 {‘’: [‘19927’, ‘28722’, ‘27439’, ‘9481’], ‘’: [‘10’, ‘10’, ‘10’, ‘10’], ‘’: [‘2022’, ‘2022’, ‘2022’, ‘2022’], ‘’: [‘57’, ‘57’, ‘57’, ‘57’], ‘’: [‘15’, ‘15’, ‘15’, ‘15’], ‘’: [‘“HEAD’, ‘“GET’, ‘“PATCH’, ‘“POST’], ‘’: [‘-0700’, ‘-0700’, ‘-0700’, ‘-0700’], ‘’: [‘/e-business/mindshare’, ‘/architectures/convergence/niches/mindshare’, ‘/strategize/out-of-the-box’, ‘/users’], ‘’: [‘177.95.8.74’, ‘127.45.152.6’, ‘118.223.210.105’, ‘210.204.15.104’]}

더 알아보기 (Learn more)