TIMECHART 명령어
TIMECHART 명령어
timechart 명령어는 데이터의 시간 기반 집계를 만들어요. 데이터를 시간 간격으로, 선택적으로는 필드별로 그룹화한 뒤 각 그룹에 집계 함수를 적용해요. 결과는 비피벗(non-pivoted) 형식으로 반환되며, 각 시간-필드 조합마다 별도의 행이 생성돼요.
출처: 문서
본문
timechart 명령어는 데이터의 시간 기반 집계를 만들어요. 데이터를 시간 간격으로, 그리고 선택적으로 필드로 그룹화한 뒤 각 그룹에 집계 함수를 적용해요. 결과는 비피벗 형식으로 반환되며, 각 시간-필드 조합마다 별도의 행이 생성돼요.
구문 (Syntax)
timechart 명령어의 구문은 다음과 같아요:
timechart [timefield=<field_name>] [span=<time_interval>] [limit=<number>] [useother=<boolean>] [usenull=<boolean>] [nullstr=<string>] <aggregation_function> [by <field>]
매개변수 (Parameters)
timechart 명령어는 다음 매개변수를 지원해요.
| 매개변수 | 필수/선택 | 설명 |
|---|---|---|
timefield |
선택 | 시간 기반 그룹핑에 사용할 필드예요. 반드시 타임스탬프 필드여야 해요. 기본값은 @timestamp예요. |
span |
선택 | 데이터를 그룹화할 시간 간격을 지정해요. 기본값은 1m(1분)이에요. 지원되는 시간 단위의 전체 목록은 시간 단위 (Time units)를 참고해요. |
limit |
선택 | by 절을 사용할 때 표시할 최대 고유 값 개수를 지정해요. 기본값은 10이에요. 고유 값이 limit보다 많으면, useother가 false가 아닌 한 추가 값은 OTHER 범주로 그룹화돼요. "가장 고유한" 값은 모든 시간 간격에 걸친 집계 값의 합을 계산해 결정돼요. 0으로 설정하면 어떤 제한도 없이 모든 고유 값을 표시해요 (limit=0이면 useother가 자동으로 false가 돼요). by 절을 사용할 때만 적용돼요. |
useother |
선택 | limit을 초과하는 값에 대해 OTHER 범주를 만들지 여부를 제어해요. false로 설정하면 OTHER 범주 없이 상위 N개 값(limit 기준)만 표시돼요. true로 설정하면 limit을 초과하는 값이 OTHER 범주로 그룹화돼요. 이 매개변수는 by 절을 사용하고 값이 limit보다 많을 때만 적용돼요. 기본값은 true예요. |
usenull |
선택 | by 필드에 null 값이 있는 문서를 별도 NULL 범주로 그룹화할지 여부를 제어해요. usenull=false면 by 필드에 null 값이 있는 문서가 결과에서 제외돼요. usenull=true면 by 필드에 null 값이 있는 문서가 별도 NULL 범주로 그룹화돼요. 기본값은 true예요. |
nullstr |
선택 | by 필드에 null 값이 있는 문서의 범주 이름을 지정해요. usenull이 true일 때만 적용돼요. 기본값은 "NULL"이에요. |
<aggregation_function> |
필수 | 각 시간 버킷에 적용할 집계 함수예요. 단일 집계 함수만 지원돼요. 사용 가능한 함수: stats 명령어가 지원하는 모든 집계 함수와 timechart 전용 집계. |
by |
선택 | 시간 간격에 더해 지정한 필드로 결과를 그룹화해요. 지정하지 않으면 각 시간 간격의 모든 문서에 대해 집계가 수행돼요. |
참고 사항 (Notes)
timechart 명령어를 사용할 때 다음 사항을 고려해요:
timechart명령어는 데이터에 타임스탬프 필드가 필요해요. 기본적으로@timestamp필드를 사용하지만,timefield매개변수로 다른 필드를 지정할 수 있어요.- 결과는 데이터가 있는 각 시간-필드 조합마다 별도의 행이 있는 비피벗 형식으로 반환돼요.
- 데이터가 있는 조합만 결과에 포함돼요. 빈 조합은 null이나 0 값을 표시하는 대신 생략돼요.
limit매개변수의 상위 N개 값은 각 고유 필드 값의 모든 시간 간격에 대한 값의 합을 기준으로 선택돼요.limit매개변수를 사용할 때 limit을 초과하는 값은OTHER범주로 그룹화돼요 (useother=false가 아닌 한).- by 필드에 null 값이 있는 문서는 별도 범주로 취급되어 결과에 null로 나타나요.
시간 단위 (Time units)
span 매개변수에 사용할 수 있는 시간 단위는 다음과 같아요:
- 밀리초 (
ms) - 초 (
s) - 분 (
m, 대소문자 구분) - 시간 (
h) - 일 (
d) - 주 (
w) - 월 (
M, 대소문자 구분) - 분기 (
q) - 년 (
y)
Timechart 전용 집계 함수
timechart 명령어는 단위 시간당 값을 계산하는 특수한 비율 기반 집계 함수를 제공해요.
per_second
사용법: per_second(field)는 각 시간 버킷 내의 숫자 필드에 대한 초당 비율을 계산해요.
계산 공식: per_second(field) = sum(field) / span_in_seconds, 여기서 span_in_seconds는 초 단위의 span 간격이에요.
반환 타입: DOUBLE
per_minute
사용법: per_minute(field)는 각 시간 버킷 내의 숫자 필드에 대한 분당 비율을 계산해요.
계산 공식: per_minute(field) = sum(field) * 60 / span_in_seconds, 여기서 span_in_seconds는 초 단위의 span 간격이에요.
반환 타입: DOUBLE
per_hour
사용법: per_hour(field)는 각 시간 버킷 내의 숫자 필드에 대한 시간당 비율을 계산해요.
계산 공식: per_hour(field) = sum(field) * 3600 / span_in_seconds, 여기서 span_in_seconds는 초 단위의 span 간격이에요.
반환 타입: DOUBLE
per_day
사용법: per_day(field)는 각 시간 버킷 내의 숫자 필드에 대한 일당 비율을 계산해요.
계산 공식: per_day(field) = sum(field) * 86400 / span_in_seconds, 여기서 span_in_seconds는 초 단위의 span 간격이에요.
반환 타입: DOUBLE
예제 1: 5분 단위 로그 볼륨
다음 쿼리는 전체 시스템 활동을 모니터링하기 위해 5분 윈도우로 모든 로그 이벤트를 세어요:
source=otellogs
| timechart timefield=@timestamp span=5m count()
쿼리는 다음과 같은 결과를 반환해요:
@timestamp | count()
2024-02-01 09:10:00 | 5
2024-02-01 09:15:00 | 5
2024-02-01 09:20:00 | 5
2024-02-01 09:25:00 | 5
예제 2: 서비스별 시간 경과 오류율
다음 쿼리는 서비스 상태를 추적하기 위해 10분 윈도우에서 서비스별 오류 로그만 세어요:
source=otellogs
| where severityText = 'ERROR'
| timechart timefield=@timestamp span=10m count() by `resource.attributes.service.name`
쿼리는 다음과 같은 결과를 반환해요:
@timestamp | resource.attributes.service.name | count()
2024-02-01 09:10:00 | checkout | 1
2024-02-01 09:10:00 | payment | 2
2024-02-01 09:20:00 | checkout | 1
2024-02-01 09:20:00 | frontend-proxy | 1
2024-02-01 09:20:00 | product-catalog | 1
2024-02-01 09:20:00 | recommendation | 1
예제 3: 상위 3개 서비스, 나머지는 OTHER로 그룹화
다음 쿼리는 로그 볼륨 기준 상위 3개 서비스로 분류를 제한하고, 나머지 서비스는 OTHER 범주로 그룹화해요:
source=otellogs
| timechart timefield=@timestamp span=15m limit=3 count() by `resource.attributes.service.name`
쿼리는 다음과 같은 결과를 반환해요:
@timestamp | resource.attributes.service.name | count()
2024-02-01 09:00:00 | OTHER | 1
2024-02-01 09:00:00 | cart | 2
2024-02-01 09:00:00 | frontend | 1
2024-02-01 09:00:00 | product-catalog | 1
2024-02-01 09:15:00 | OTHER | 8
2024-02-01 09:15:00 | cart | 1
2024-02-01 09:15:00 | frontend | 3
2024-02-01 09:15:00 | product-catalog | 3
예제 4: OTHER 범주 제외하기
다음 쿼리는 useother=false로 설정해 OTHER 버킷 없이 상위 2개 서비스만 표시해요:
source=otellogs
| timechart timefield=@timestamp span=30m limit=2 useother=false count() by `resource.attributes.service.name`
쿼리는 다음과 같은 결과를 반환해요:
@timestamp | resource.attributes.service.name | count()
2024-02-01 09:00:00 | frontend | 4
2024-02-01 09:00:00 | product-catalog | 4
예제 5: 심각도별 초당 오류율
다음 쿼리는 per_second 비율 함수를 사용해 서로 다른 시간 윈도우 간의 오류 개수를 심각도 수준별로 그룹화해 정규화해요:
source=otellogs
| where severityNumber >= 13
| timechart timefield=@timestamp span=2m per_second(severityNumber) by severityText
쿼리는 다음과 같은 결과를 반환해요:
@timestamp | severityText | per_second(severityNumber)
2024-02-01 09:12:00 | ERROR | 0.14166666666666666
2024-02-01 09:12:00 | WARN | 0.10833333333333334
2024-02-01 09:14:00 | ERROR | 0.14166666666666666
2024-02-01 09:16:00 | ERROR | 0.14166666666666666
2024-02-01 09:18:00 | WARN | 0.10833333333333334
2024-02-01 09:20:00 | ERROR | 0.14166666666666666
2024-02-01 09:22:00 | WARN | 0.10833333333333334
2024-02-01 09:24:00 | ERROR | 0.2833333333333333
2024-02-01 09:26:00 | WARN | 0.10833333333333334
2024-02-01 09:28:00 | ERROR | 0.14166666666666666
예제 6: 시간 경과 고유 서비스 개수
다음 쿼리는 시간당 활발히 로그를 기록하는 고유 서비스 수를 추적해, 서비스 장애를 감지하는 데 유용해요:
source=otellogs
| timechart timefield=@timestamp span=1h distinct_count(`resource.attributes.service.name`)
쿼리는 다음과 같은 결과를 반환해요:
@timestamp | distinct_count( resource.attributes.service.name )
2024-02-01 09:00:00 | 7
예제 7: limit=0을 count()와 함께 사용해 모든 값 표시하기
이 예제는 11개의 고유 호스트가 있는 events_many_hosts 데이터셋을 사용해요.
어떤 제한도 적용하지 않고 모든 고유 값을 표시하려면 limit=0으로 설정해요:
source=events_many_hosts
| timechart span=1h limit=0 count() by host
전체 11개 호스트가 OTHER 범주 없이 별도 행으로 반환돼요:
@timestamp | host | count()
2024-07-01 00:00:00 | web-01 | 1
2024-07-01 00:00:00 | web-02 | 1
2024-07-01 00:00:00 | web-03 | 1
2024-07-01 00:00:00 | web-04 | 1
2024-07-01 00:00:00 | web-05 | 1
2024-07-01 00:00:00 | web-06 | 1
2024-07-01 00:00:00 | web-07 | 1
2024-07-01 00:00:00 | web-08 | 1
2024-07-01 00:00:00 | web-09 | 1
2024-07-01 00:00:00 | web-10 | 1
2024-07-01 00:00:00 | web-11 | 1
예제 8: count() 함수와 함께 useother=false 사용하기
다음 쿼리는 useother=false로 설정해 OTHER 범주를 만들지 않고 상위 10개 호스트로 결과를 제한해요:
source=events_many_hosts
| timechart span=1h useother=false count() by host
쿼리는 다음과 같은 결과를 반환해요:
@timestamp | host | count()
2024-07-01 00:00:00 | web-01 | 1
2024-07-01 00:00:00 | web-02 | 1
2024-07-01 00:00:00 | web-03 | 1
2024-07-01 00:00:00 | web-04 | 1
2024-07-01 00:00:00 | web-05 | 1
2024-07-01 00:00:00 | web-06 | 1
2024-07-01 00:00:00 | web-07 | 1
2024-07-01 00:00:00 | web-08 | 1
2024-07-01 00:00:00 | web-09 | 1
2024-07-01 00:00:00 | web-10 | 1
예제 9: limit 매개변수와 useother 매개변수, avg() 함수 사용하기
다음 쿼리는 시간당 평균 cpu_usage 기준 상위 3개 호스트를 표시해요. 나머지 모든 호스트는 OTHER 범주로 그룹화돼요 (기본적으로 useother=true):
source=events_many_hosts
| timechart span=1h limit=3 avg(cpu_usage) by host
쿼리는 다음과 같은 결과를 반환해요:
@timestamp | host | avg(cpu_usage)
2024-07-01 00:00:00 | OTHER | 41.3
2024-07-01 00:00:00 | web-03 | 55.3
2024-07-01 00:00:00 | web-07 | 48.6
2024-07-01 00:00:00 | web-09 | 67.8
다음 쿼리는 useother=false로 설정해 OTHER 범주를 만들지 않고 시간당 평균 cpu_usage 기준 상위 3개 호스트를 표시해요:
source=events_many_hosts
| timechart span=1h limit=3 useother=false avg(cpu_usage) by host
쿼리는 다음과 같은 결과를 반환해요:
@timestamp | host | avg(cpu_usage)
2024-07-01 00:00:00 | web-03 | 55.3
2024-07-01 00:00:00 | web-07 | 48.6
2024-07-01 00:00:00 | web-09 | 67.8
예제 10: by 필드의 null 값 처리
다음 쿼리는 by 필드의 null 값이 별도 범주로 취급되는 방법을 보여줘요:
source=events_null
| timechart span=1h count() by host
events_null 데이터셋에는 host 값이 없는 항목이 하나 있어요. 기본 설정이 usenull=true, nullstr="NULL"이므로 이 항목은 별도 NULL 범주로 그룹화돼요:
@timestamp | host | count()
2024-07-01 00:00:00 | NULL | 1
2024-07-01 00:00:00 | db-01 | 1
2024-07-01 00:00:00 | web-01 | 2
2024-07-01 00:00:00 | web-02 | 2
예제 11: 초당 패킷 비율 계산하기
다음 쿼리는 per_second() 함수를 사용해 네트워크 트래픽 데이터의 초당 패킷 비율을 계산해요:
source=events
| timechart span=30m per_second(packets) by host
쿼리는 다음과 같은 결과를 반환해요:
@timestamp | host | per_second(packets)
2023-01-01 10:00:00 | server1 | 0.1
2023-01-01 10:00:00 | server2 | 0.05
2023-01-01 10:30:00 | server1 | 0.1
2023-01-01 10:30:00 | server2 | 0.05
제한 사항 (Limitations)
timechart 명령어에는 다음 제한 사항이 있어요:
- timechart 명령어당 단일 집계 함수만 지원돼요.
bins매개변수 및 기타 bin 옵션은 지원되지 않아요. 시간 간격을 제어하려면span매개변수를 사용해요.