Time Series 구성 파라미터
Time Series 구성 파라미터 (Configuration Parameters)
Redis Time Series는 여러 개의 구성 파라미터를 지원해요. 이 파라미터들이 어디서 어떻게 설정되는지, 그리고 버전 8.0을 기준으로 이름이 어떻게 바뀌었는지를 함께 살펴볼게요.
Redis 오픈소스 - 구성 파라미터 설정 (Redis Open Source - set configuration parameters)
Redis 8.0 이전 버전(Redis 오픈소스)에서는 모든 Time Series 구성 파라미터가 로드 타임(load-time) 파라미터였어요. 로드 타임 구성 파라미터의 값을 설정하는 방법은 다음과 같아요.
redis-server를 시작할 때loadmodule인자 다음에 인자로 전달하기:
redis-server --loadmodule ./{modulename}.so [OPT VAL]...
- 설정 파일(예:
redis.conf)의loadmodule지시문에 인자로 추가하기:
loadmodule ./{modulename}.so [OPT VAL]...
MODULE LOAD path [arg [arg ...]]명령 사용하기MODULE LOADEX path [CONFIG name value [CONFIG name value ...]] [ARGS args [args ....]]명령 사용하기
Redis 8.0부터는 대부분의 Time Series 구성 파라미터가 런타임 파라미터가 됐어요. 런타임 파라미터는 로드 타임에도 설정할 수 있지만, Redis CONFIG 명령을 사용하는 게 더 쉽고 Redis 런타임 구성 파라미터와 동일한 방식으로 동작해요. 즉:
CONFIG SET parameter value [parameter value ...]— 하나 이상의 구성 파라미터를 설정해요.CONFIG GET parameter [parameter ...]— 하나 이상의 파라미터의 현재 값을 읽어요.CONFIG REWRITE— Redis 구성 파일(예:redis.conf)을 구성 변경 사항을 반영하도록 다시 작성해요.
Redis 8.0부터는 Redis 구성 파라미터와 같은 방식으로 Time Series 구성 파라미터를 Redis 구성 파일에 직접 지정할 수도 있어요.
CONFIG SET로 값이 설정되거나 구성 파일에 수동으로 추가되면, --loadmodule, loadmodule, MODULE LOAD, 또는 MODULE LOADEX로 설정된 값을 덮어써요.
클러스터에서는 각 노드에서 CONFIG SET과 CONFIG REWRITE를 별도로 실행해야 해요.
Redis 8.0에서는 Time Series 구성 파라미터의 새 이름이 도입되어 Redis 구성 파라미터와 이름을 맞췄어요. CONFIG 명령을 사용할 때는 반드시 새 이름을 사용해야 해요.
Time Series 구성 파라미터 목록 (Time series configuration parameters)
| 파라미터 이름 (버전 < 8.0) | 파라미터 이름 (버전 ≥ 8.0) | 런타임 | Redis Software | Redis Cloud |
|---|---|---|---|---|
| CHUNK_SIZE_BYTES | ts-chunk-size-bytes | ✅ | ✅ 지원 | ✅ Flexible & Annual ❌ Free & Fixed |
| COMPACTION_POLICY | ts-compaction-policy | ✅ | ✅ 지원 | ✅ Flexible & Annual ❌ Free & Fixed |
| DUPLICATE_POLICY | ts-duplicate-policy | ✅ | ✅ 지원 | ✅ Flexible & Annual ❌ Free & Fixed |
| RETENTION_POLICY | ts-retention-policy | ✅ | ✅ 지원 | ✅ Flexible & Annual ❌ Free & Fixed |
| ENCODING | ts-encoding | ✅ | ✅ 지원 | ✅ Flexible & Annual ❌ Free & Fixed |
| IGNORE_MAX_TIME_DIFF | ts-ignore-max-time-diff | ✅ | ||
| IGNORE_MAX_VAL_DIFF | ts-ignore-max-val-diff | ✅ | ||
| NUM_THREADS | ts-num-threads | ⬜ | ✅ 지원 | ❌ Flexible & Annual ❌ Free & Fixed |
| OSS_GLOBAL_PASSWORD | v8.0에서 폐기됨 | ✅ |
CHUNK_SIZE_BYTES / ts-chunk-size-bytes
각 새 청크(chunk)의 데이터 부분에 대한 초기 할당 크기(바이트)를 지정해요. 실제 청크는 더 많은 메모리를 소비할 수 있어요. 이 값을 변경해도 기존 청크에는 영향을 주지 않아요.
- 타입: 정수(integer)
- 유효 범위:
[48 .. 1048576]; 반드시 8의 배수여야 해요
우선순위 순서 (Precedence order)
청크 크기는 서로 다른 레벨에서 제공될 수 있기 때문에, 실제 청크 크기의 우선순위는 다음과 같아요.
예시 (Example)
기본 청크 크기를 1024바이트로 설정한다면:
버전 < 8.0:
$ redis-server --loadmodule ./redistimeseries.so CHUNK_SIZE_BYTES 1024
버전 >= 8.0:
redis> CONFIG SET ts-chunk-size-bytes 1024
COMPACTION_POLICY / ts-compaction-policy
TS.ADD, TS.INCRBY, TS.DECRBY로 새로 생성되는 키에 대한 기본 컴팩션 규칙을 지정해요.
- 타입: 문자열(string)
이 구성 파라미터는 TS.CREATE로 생성하는 키에는 영향을 주지 않는다는 점을 주의하세요. 그 이유를 이해하려면 다음 시나리오를 생각해보죠. 기본 컴팩션 정책을 정의했는데, 추가 컴팩션 규칙을 수동으로 만들고 싶다고 가정해요. 이때 TS.CREATERULE을 쓰려면 먼저 빈 대상 키를 만들어야 해요. 그런데 이렇게 하면 기본 컴팩션 정책 때문에 Redis가 대상 키에 원치 않는 컴팩션을 자동으로 만들어버리는 문제가 생겨요.
각 규칙은 세미콜론(;)으로 구분되며, 규칙은 콜론(:)으로 구분되는 여러 필드로 구성돼요.
- 집계 유형(Aggregation type) — 다음 중 하나:
| 집계기 | 설명 |
|---|---|
avg |
모든 값의 산술 평균 |
sum |
모든 값의 합 |
min |
최솟값 |
max |
최댓값 |
range |
최고값과 최저값의 차이 |
count |
값의 개수 |
first |
버킷에서 타임스탬프가 가장 낮은 값 |
last |
버킷에서 타임스탬프가 가장 높은 값 |
std.p |
값의 모집단 표준편차 |
std.s |
값의 표본 표준편차 |
var.p |
값의 모집단 분산 |
var.s |
값의 표본 분산 |
twa |
모든 값의 시간 가중 평균 (v1.8부터) |
- 각 시간 버킷의 지속 시간 — 숫자와 시간 표현 (1분 예시:
1M,60s, 또는60000m)- m - 밀리초
- s - 초
- M - 분
- h - 시간
- d - 일
- 보존 시간(Retention time) — 숫자와 시간 표현 (1분 예시:
1M,60s, 또는60000m)
0m, 0s, 0M, 0h, 또는 0d는 만료가 없음을 의미해요.
- m - 밀리초
- s - 초
- M - 분
- h - 시간
- d - 일
- (v1.8부터):
선택 사항: 시간 버킷 정렬(alignment) — 숫자와 시간 표현 (1분 예시: 1M, 60s, 또는 60000m)
Epoch 이후 정확히 alignTimestamp에 시작하는 버킷이 존재하고, 다른 모든 버킷이 그에 따라 정렬되도록 해요. 기본값: 0 (Epoch에 정렬). 예시: bucketDuration이 24시간이라면, alignTimestamp를 6h(Epoch 이후 6시간)로 설정하면 각 버킷의 시간 범위가 [06:00 .. 06:00)이 되도록 보장해요.
- m - 밀리초
- s - 초
- M - 분
- h - 시간
- d - 일
⚠️ 경고:
클러스터 환경에서는 이 구성 파라미터를 설정하면 모든 Time Series 키 이름에 hash tags를 사용해야 해요. 그래야 Redis가 각 컴팩션을 소스 키와 같은 해시 슬롯에 생성할 수 있어요. 그렇게 하지 않으면 오류 메시지 없이 데이터 컴팩션이 실패할 수 있어요.
컴팩션 정책이 정의되면 새로 생성되는 Time Series에 대해 컴팩션 규칙이 자동으로 만들어지며, 컴팩션 키 이름은 다음과 같아요.
- 시간 버킷 정렬이 0인 경우:
key_agg_dur — 여기서 key는 소스 Time Series의 키, agg는 집계기(대문자), dur는 밀리초 단위 버킷 지속 시간. 예시: key_SUM_60000.
- 시간 버킷 정렬이 0이 아닌 경우:
key_agg_dur_aln — key는 소스 Time Series의 키, agg는 집계기(대문자), dur는 밀리초 단위 버킷 지속 시간, aln은 밀리초 단위 시간 버킷 정렬. 예시: key_SUM_60000_1000.
우선순위 순서 (Precedence order)
ts-compaction-policy구성 파라미터- 컴팩션 규칙 없음
규칙 예시 (Example rules)
max:1M:1h- 1분 윈도우에 대해max로 집계하고 마지막 1시간만 보존twa:1d:0m:360M- 매일 [06:00 .. 06:00)을twa로 집계; 만료 없음
예시 (Example)
5개의 컴팩션 규칙으로 구성된 컴팩션 정책을 설정한다면:
버전 < 8.0:
$ redis-server --loadmodule ./redistimeseries.so COMPACTION_POLICY max:1m:1h;min:10s:5d:10d;last:5M:10m;avg:2h:10d;avg:3d:100d
버전 >= 8.0:
redis> CONFIG SET ts-compaction-policy max:1m:1h;min:10s:5d:10d;last:5M:10m;avg:2h:10d;avg:3d:100d
DUPLICATE_POLICY / ts-duplicate-policy
동일한 타임스탬프를 가진 여러 샘플의 삽입(TS.ADD와 TS.MADD)을 처리하는 기본 정책으로, 다음 값 중 하나를 가져요.
| 정책 | 설명 |
|---|---|
BLOCK |
새로 보고된 값을 무시하고 오류로 응답 |
FIRST |
새로 보고된 값 무시 |
LAST |
새로 보고된 값으로 덮어쓰기 |
MIN |
새 값이 기존 값보다 낮을 때만 덮어쓰기 |
MAX |
새 값이 기존 값보다 높을 때만 덮어쓰기 |
SUM |
이전 샘플이 있으면 새 샘플을 더해 (이전 + 새)로 갱신. 이전 샘플이 없으면 새 값과 같게 설정 |
기본값은 각 새 Time Series가 생성될 때 적용돼요.
- 타입: 문자열(string)
우선순위 순서 (Precedence order)
중복 정책은 서로 다른 레벨에서 제공될 수 있기 때문에, 실제 중복 정책의 우선순위는 다음과 같아요.
TS.ADD의ON_DUPLICATE_POLICY선택적 인자TS.CREATE와TS.ALTER의DUPLICATE_POLICY선택적 인자로 설정된 키 레벨 정책ts-duplicate-policy구성 파라미터- 하드코딩된 기본값:
BLOCK
RETENTION_POLICY / ts-retention-policy
새로 생성되는 키의 기본 보존 기간(밀리초)을 지정해요.
보존 기간은 키별로 가장 높게 보고된 타임스탬프 대비 샘플의 최대 수명이에요. 샘플은 이후 TS.ADD, TS.MADD, TS.INCRBY, TS.DECRBY 호출에 전달된 타임스탬프와의 차이에만 기반해서 만료돼요.
- 타입: 정수(integer)
- 유효 범위:
[0 .. 9,223,372,036,854,775,807]
값 0은 만료가 없음을 의미해요.
COMPACTION_POLICY / ts-compaction-policy와 RETENTION_POLICY / ts-retention-policy가 모두 지정되면, 새로 생성되는 컴팩션의 보존은 COMPACTION_POLICY / ts-compaction-policy에 지정된 보존 시간에 따르게 돼요.
우선순위 순서 (Precedence order)
보존은 서로 다른 레벨에서 제공될 수 있기 때문에, 실제 보존의 우선순위는 다음과 같아요.
예시 (Example)
기본 보존을 300일로 설정한다면:
버전 < 8.0:
$ redis-server --loadmodule ./redistimeseries.so RETENTION_POLICY 25920000000
버전 >= 8.0:
redis> CONFIG SET ts-retention-policy 25920000000
ENCODING / ts-encoding
참고: v1.6 이전에는 이 구성 파라미터의 이름이 CHUNK_TYPE이었어요.
ts-compaction-policy가 구성되었을 때 자동으로 생성되는 컴팩션의 기본 청크 인코딩을 지정해요.
- 타입: 문자열(string)
- 유효 값:
COMPRESSED,UNCOMPRESSED
우선순위 순서 (Precedence order)
ts-encoding구성 파라미터- 하드코딩된 기본값:
COMPRESSED
예시 (Example)
기본 인코딩을 UNCOMPRESSED로 설정한다면:
버전 < 8.0:
$ redis-server --loadmodule ./redistimeseries.so ENCODING UNCOMPRESSED
버전 >= 8.0:
redis> CONFIG SET ts-encoding UNCOMPRESSED
IGNORE_MAX_TIME_DIFF / ts-ignore-max-time-diff 및 IGNORE_MAX_VAL_DIFF / ts-ignore-max-val-diff
새로 생성되는 키의 기본값을 지정해요.
- 타입:
ts-ignore-max-time-diff: 정수(integer)ts-ignore-max-val-diff: 실수(double)
- 유효 범위:
ts-ignore-max-time-diff:[0 .. 9,223,372,036,854,775,807]ts-ignore-max-val-diff:[0 .. 1.7976931348623157e+308]
많은 센서가 데이터를 주기적으로 보고해요. 흔히 측정값과 이전 측정값의 차이는 무시할 만한 정도이고, 무작위 노이즈나 측정 정확도 제한과 관련된 경우가 많아요. 이런 상황에서는 새 측정값을 Time Series에 추가하지 않는 게 더 나을 수 있어요.
다음 조건이 모두 충족되면 새 샘플은 중복으로 간주되어 무시돼요.
- Time Series가 컴팩션이 아니다.
- Time Series의
ts-duplicate-policy가LAST이다. - 샘플이 순서대로 추가된다 (
timestamp ≥ max_timestamp). - 현재 타임스탬프와 이전 타임스탬프의 차이(
timestamp - max_timestamp)가ts-ignore-max-time-diff보다 작거나 같다. - 현재 값과 이전 최대 타임스탬프 시점 값의 절댓값 차이(
abs(value - value_at_max_timestamp)가ts-ignore-max-val-diff보다 작거나 같다.
여기서 max_timestamp는 Time Series에서 가장 큰 타임스탬프를 가진 샘플의 타임스탬프이고, value_at_max_timestamp는 max_timestamp 시점의 값이에요.
우선순위 순서 (Precedence order)
ts-ignore-max-time-diff및ts-ignore-max-val-diff구성 파라미터- 하드코딩된 기본값:
0및0.0
예시 (Example)
버전 < 8.0:
$ redis-server --loadmodule ./redistimeseries.so IGNORE_MAX_TIME_DIFF 10 IGNORE_MAX_VAL_DIFF 0.1
버전 >= 8.0:
redis> CONFIG SET ts-ignore-max-time-diff 10 ts-ignore-max-val-diff 0.1
NUM_THREADS / ts-num-threads
클러스터 모드에서 크로스 키 쿼리(TS.MRANGE, TS.MREVRANGE, TS.MGET, TS.QUERYINDEX)에 사용되는 샤드당 스레드의 최대 수를 지정해요. 값은 1보다 같거나 커야 해요. 이 값을 늘리면 성능이 향상될 수도, 오히려 저하될 수도 있다는 점에 주의하세요!
- 타입: 정수(integer)
- 유효 범위:
[1..16] - Redis 오픈소스 기본값:
3 - Redis Software 기본값: 플랜에 의해 설정되며, 플랜을 변경하면 자동으로 갱신돼요.
- Redis Cloud 기본값:
- Flexible & Annual: 플랜에 의해 설정
- Free & Fixed:
1
예시 (Example)
버전 < 8.0:
$ redis-server --loadmodule ./redistimeseries.so NUM_THREADS 3
버전 >= 8.0:
redis> redis-server --loadmodule ./redistimeseries.so ts-num-threads 3
OSS_GLOBAL_PASSWORD
버전 8.0 이전에는 클러스터에서 Time Series를 사용할 때 모든 클러스터 노드에 OSS_GLOBAL_PASSWORD 구성 파라미터를 설정해야 했어요. 버전 8.0부터는 Redis가 더 이상 이 파라미터를 사용하지 않으며, 있어도 무시해요. 이제 Redis는 클러스터 노드 간 내부 명령을 보내기 위해 새로운 공유 시크릿 메커니즘을 사용해요.