구성 파라미터

구성 파라미터 (Configuration Parameters — Time series)

Redis time series는 여러 구성 파라미터를 지원해요. 이 페이지에서는 time series 구성 파라미터를 어떻게 설정하는지, 그리고 각 파라미터의 의미와 우선순위를 정리해 드릴게요.

출처: Redis 공식 문서 — configuration (time series)

Redis Open Source - 구성 파라미터 설정 (Redis Open Source - set configuration parameters)

Redis Open Source의 Redis 8(버전 8.0) 이전에는 모든 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 구성 파라미터는 런타임(runtime) 파라미터예요. 런타임 파라미터를 로드 시점에도 설정할 수 있지만, Redis CONFIG 명령을 쓰는 게 더 쉽고 Redis 런타임 구성 파라미터와 같은 방식으로 동작해요.

즉:

CONFIG SET parameter value [parameter value ...] — 하나 이상의 구성 파라미터를 설정
CONFIG GET parameter [parameter ...] — 하나 이상의 파라미터의 현재 값을 읽기
CONFIG REWRITE — Redis 구성 파일(예: redis.conf)을 구성 변경 사항을 반영하도록 다시 작성

Redis 8.0부터는 Redis 구성 파라미터를 쓰는 것과 같은 방식으로 Redis 구성 파일에 time series 구성 파라미터를 직접 지정할 수 있어요.

CONFIG SET으로 설정하거나 구성 파일에 수동으로 추가한 값은 --loadmodule, loadmodule, MODULE LOAD, MODULE LOADEX로 설정된 값을 덮어써요. 클러스터에서는 CONFIG SET과 CONFIG REWRITE를 각 노드에서 별도로 실행해야 해요.

Redis 8.0에서는 time series 구성 파라미터 이름을 Redis 구성 파라미터와 명명을 맞추기 위해 새 이름이 도입됐어요. CONFIG 명령을 쓸 때는 새 이름을 사용해야 해요. 자세한 내용은 Redis 구성 문서도 참고하세요.

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에서 deprecated	✅

CHUNK_SIZE_BYTES / ts-chunk-size-bytes

각 새 청크(chunk)의 데이터 부분에 대한 초기 할당 크기(바이트 단위). 실제 청크는 더 많은 메모리를 소비할 수 있어요. 이 값을 바꿔도 기존 청크에는 영향이 없어요.

타입: integer
유효 범위: [48 .. 1048576]; 8의 배수여야 함

우선순위 (Precedence order)

청크 크기는 여러 수준에서 제공될 수 있기 때문에 실제 청크 크기의 우선순위는:

TS.CREATE와 TS.ALTER의 CHUNK_SIZE 선택적 인자로 설정된 키-레벨 정책
ts-chunk-size-bytes 구성 파라미터
하드코딩된 기본값: 4096

예시 (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로 새로 생성된 키에 대한 기본 컴팩션(compaction, 정리) 규칙.

타입: string

이 구성 파라미터는 TS.CREATE로 만드는 키에는 영향을 주지 않아요. 이유: 기본 컴팩션 정책을 정의했는데 수동으로 추가 컴팩션 규칙(TS.CREATERULE)을 만들고 싶다고 가정해 봐요. 그러려면 먼저 빈 대상 키를 TS.CREATE로 만들어야 해요. 그러면 기본 컴팩션 정책이 대상 키에 원치 않는 컴팩션을 자동으로 만들어버리는 문제가 생기죠.

각 규칙은 세미콜론(;)으로 구분되고, 규칙은 콜론(:)으로 구분된 여러 필드로 구성돼요:

집계 타입 (Aggregation type), 다음 중 하나:

집계기 (Aggregator)	설명
`avg`	모든 값의 산술 평균
`sum`	모든 값의 합
`min`	최소값
`max`	최대값
`range`	최고값과 최저값의 차이
`count`	값의 개수
`first`	버킷에서 타임스탬프가 가장 낮은 값
`last`	버킷에서 타임스탬프가 가장 높은 값
`std.p`	값의 모집단 표준편차
`std.s`	값의 표본 표준편차
`var.p`	값의 모집단 분산
`var.s`	값의 표본 분산
`twa`	모든 값의 시간 가중 평균(v1.8부터)

각 시간 버킷의 지속 시간(duration) — 숫자와 시간 표기 (1분 예: 1M, 60s, 60000m)
- m - 밀리초(millisecond)
- s - 초(seconds)
- M - 분(minute)
- h - 시간(hour)
- d - 일(day)
보존 시간(retention time) — 숫자와 시간 표기 (1분 예: 1M, 60s, 60000m)
- m - 밀리초 / s - 초 / M - 분 / h - 시간 / d - 일
0m, 0s, 0M, 0h, 0d는 만료가 없음을 의미해요.
(v1.8부터) 선택사항: 시간 버킷 정렬(alignment) — 숫자와 시간 표기 (1분 예: 1M, 60s, 60000m)
- m - 밀리초 / s - 초 / M - 분 / h - 시간 / d - 일
Epoch 이후 정확히 _alignTimestamp_에 시작하는 버킷이 하나 있고 다른 모든 버킷이 그에 맞춰 정렬되도록 보장해요. 기본값: 0(Epoch와 정렬). 예: _bucketDuration_이 24시간일 때 _alignTimestamp_를 6h(Epoch 후 6시간)로 설정하면 각 버킷의 시간 범위가 [06:00 .. 06:00)이 되도록 보장해요.

경고: 클러스터 환경에서 이 구성 파라미터를 설정한다면, 모든 time series 키 이름에 hash tags를 사용해야 해요. 그래야 Redis가 각 컴팩션을 소스 키와 같은 hash slot에 만들기 때문이에요. 그렇게 하지 않으면 오류 메시지 없이 데이터 컴팩션이 실패할 수 있어요.

컴팩션 정책이 정의되면 새로 생성된 time series에 대해 컴팩션 규칙이 자동으로 생성되고, 컴팩션 키 이름은:

시간 버킷 정렬이 0이면: key_agg_dur — 여기서 key는 소스 time series의 키, agg는 집계기(대문자), dur는 버킷 지속 시간(밀리초). 예: key_SUM_60000
시간 버킷 정렬이 0이 아니면: key_agg_dur_aln — key는 소스 키, agg는 집계기(대문자), dur는 버킷 지속 시간(밀리초), aln은 버킷 정렬(밀리초). 예: key_SUM_60000_1000

우선순위 (Precedence order)

ts-compaction-policy 구성 파라미터
컴팩션 규칙 없음

예시 규칙 (Example rules)

max:1M:1h - 1분 창(window)에 대해 max로 집계하고 마지막 한 시간 유지
twa:1d:0m:360M - twa를 사용해 매일 [06:00 .. 06:00) 집계, 만료 없음

예시 (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)

보존은 여러 수준에서 제공될 수 있기 때문에 실제 보존의 우선순위는:

TS.CREATE와 TS.ALTER의 RETENTION 선택적 인자로 설정된 키-레벨 보존
ts-retention-policy 구성 파라미터
보존 없음

예시 (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

클러스터 모드에서 크로스 키(cross-key) 쿼리(TS.MRANGE, TS.MREVRANGE, TS.MGET, TS.QUERYINDEX)를 위한 샤드당 최대 스레드 수. 값은 1보다 크거나 같아야 해요. 이 값을 늘리면 성능이 향상될 수도, 저하될 수도 있다는 점을 주의하세요!

타입: integer
유효 범위: [1..16]
Redis Open Source 기본값: 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

참고: 버전 >= 8.0 예시는 원문에 그대로 표기된 것으로 redis-server로 시작하는 형식이지만 정상적인 예시예요. (원문 그대로 인용 — 확인 필요)

OSS_GLOBAL_PASSWORD

버전 8.0 이전에는 클러스터에서 time series를 사용할 때 모든 클러스터 노드에 OSS_GLOBAL_PASSWORD 구성 파라미터를 설정해야 했어요. 버전 8.0부터 Redis는 더 이상 이 파라미터를 사용하지 않고, 있어도 무시해요. Redis는 이제 클러스터 노드 간 내부 명령을 보내는 새 공유 비밀(shared secret) 메커니즘을 사용해요.

구성 파라미터