diff --git a/documentation/README.md b/documentation/README.md new file mode 120000 index 000000000..1d0707530 --- /dev/null +++ b/documentation/README.md @@ -0,0 +1 @@ +ch01-arcus-basic-concept.md \ No newline at end of file diff --git a/documentation/SUMMARY.md b/documentation/SUMMARY.md new file mode 100644 index 000000000..d3032240d --- /dev/null +++ b/documentation/SUMMARY.md @@ -0,0 +1,23 @@ +# Table of contents + +* [Basic concept](ch01-arcus-basic-concept.md) +* [Collection items](ch02-collection-items.md) +* [Item attributes](ch03-item-attributes.md) + +## Manuals +* [Commandline arguments](manuals/commandline_arguments.md) +* [Compilation faq](manuals/compilation_faq.md) + +## Reference +* [ascii protocol](ascii-protocol/ch00-arcus-ascii-protocol.md) + * [Telnet interface](ascii-protocol/ap01-arcus-telnet-interface.md) + * [Key-Value](ascii-protocol/ch04-command-key-value.md) + * [List](ascii-protocol/ch05-command-list-collection.md) + * [Set](ascii-protocol/ch06-command-set-collection.md) + * [Map](ascii-protocol/ch07-command-map-collection.md) + * [B+Tree](ascii-protocol/ch08-command-btree-collection.md) + * [Pipelining](ascii-protocol/ch09-command-pipelining.md) + * [Item attribute](ascii-protocol/ch10-command-item-attribute.md) + * [Scan](ascii-protocol/ch11-command-scan.md) + * [Administraion](ascii-protocol/ch12-command-administration.md) +​ \ No newline at end of file diff --git a/documentation/ascii-protocol/ap01-arcus-telnet-interface.md b/documentation/ascii-protocol/ap01-arcus-telnet-interface.md new file mode 100644 index 000000000..8ec07a6fe --- /dev/null +++ b/documentation/ascii-protocol/ap01-arcus-telnet-interface.md @@ -0,0 +1,116 @@ +# ARCUS Telnet Interface + +ARCUS cache server의 동작을 간단히 확인하는 방법으로, telnet interface를 이용할 수 있다. + +## Telnet 사용법 + +OS prompt 상에서 아래와 같이 telnet 명령을 실행시킨다. +telnet 명령의 인자로는 연결하고자 하는 ARCUS cache server인 memcached의 IP와 port number를 준다. + +``` +$ telnet {memcached-ip} {memcached-port} +``` + +## Telnet 연결 + +Localhost에 11211 포트 번호로 memcached가 구동되어 있다고 가정한다. +telnet 명령으로 해당 memcached에 연결하기 위해, +OS prompt 상에서 아래의 명령을 수행한다. + +``` +$ telnet localhost 11211 +Trying 127.0.0.1... +Connected to localhost.localdomain (127.0.0.1). +Escape character is '^]'. +``` + +telnet 명령으로 memcached에 연결한 이후에는 ARCUS ASCII 명령을 직접 수행해 볼 수 있다. +아래에서 그 예들을 든다. ARCUS ASCII 명령의 자세한 설명은 [ARCUS cache server ascii protocol](ch00-arcus-ascii-protocol.md)을 참고하기 바란다. + + +### 예제 1. get/set + +하나의 key-value item으로 <"foo", "fooval">을 저장하기 위해, set 명령을 입력한다. + +``` +set foo 0 0 6 +fooval +``` + +set 명령의 수행 결과로 정상적으로 key-value item이 저장되었다는 string이 리턴된다. + +``` +STORED +``` + +저장된 foo item을 조회하기 위해, get 명령을 입력한다. + + +``` +get foo +``` + +get 명령으로 조회한 foo item 결과는 아래와 같다. + + +``` +VALUE foo 0 6 +fooval +END +``` + +### 예제 2. b+tree + +하나의 b+tree item을 생성하면서 5개의 elements를 추가하기 위해, +아래의 5개 bop insert 명령을 차례로 수행한다. + +``` +bop insert bkey1 90 6 create 11 0 0 +datum9 +bop insert bkey1 70 6 +datum7 +bop insert bkey1 50 6 +datum5 +bop insert bkey1 30 6 +datum3 +bop insert bkey1 10 6 +datum1 +``` + +5개 bop insert 명령의 수행 결과는 아래와 같다. + + +``` +CREATED_STORED +STORED +STORED +STORED +STORED +``` + +b+tree에서 30부터 80까지의 bkey(b+tree key) range에 속하는 elements를 조회하기 위하여, +bop get 명령을 입력한다. + + +``` +bop get bkey1 30..80 +``` + +bop get 명령으로 조회한 결과는 아래와 같다. + + +``` +VALUE 11 3 +30 6 datum3 +50 6 datum5 +70 6 datum7 +END +``` + +## Telnet 종료 + +현재의 telnet 연결을 종료하려면, quit 명령을 입력한다. + +``` +quit +``` diff --git a/documentation/ascii-protocol/ch00-arcus-ascii-protocol.md b/documentation/ascii-protocol/ch00-arcus-ascii-protocol.md new file mode 100644 index 000000000..8fb8c6f4d --- /dev/null +++ b/documentation/ascii-protocol/ch00-arcus-ascii-protocol.md @@ -0,0 +1,66 @@ +# ARCUS Cache Server ASCII Protocol + +ARCUS Cache Server가 제공하는 명령들의 ASCII Protocol을 기술한다. +Binary protocol은 현재 지원하지 않으므로, 논의에서 제외한다. + +본 문서는 ARCUS cache client 개발자를 주 대상으로 하며, +ARCUS Cache Server에 관심있는 독자의 경우도 참고할 수 있다. + +Collection Support +------------------ + +ASCII Protocol 관점에서 ARCUS Cache Server는 기존 memcached 기능 외에 collection 기능을 제공한다. +하나의 data만을 가지는 simple key-value 외에도 여러 data를 구조화된 형태로 저장/조회할 수 있으며, +제공하는 collection 유형은 아래와 같다. + +- list : 데이터들의 linked list 구조 +- set : 유일한 데이터들의 집합으로 membership 검사에 적합 +- map : \쌍으로 구성된 데이터들의 집합으로 field 기준의 hash 구조 +- b+tree : b+tree 키 기준으로 정렬된 데이터들의 집합으로 range scan 처리에 적합 + +Basic Concepts +-------------- + +ARCUS Cache Server를 사용함에 있어 필요한 cache key, item, slab 등의 기본 용어와 개념은 +[ARCUS 기본 개념](../ch01-arcus-basic-concept.md)에서 설명하므로, 이를 먼저 읽어보길 권한다. + +ARCUS Cache Server가 제공하는 collection과 element 구조, b+tree key, element flag 등의 +중요 요소들은 [Collection 기본 개념](../ch02-collection-items.md)에서 소개한다. + +Collection 기능을 제공함에 따라 item 속성들이 확장되었으며, +이들은 [Item 속성 설명](../ch03-item-attributes.md)에서 자세히 다룬다. + +Simple Key-Value 기능 +--------------------- + +ARCUS Cache Server는 memcached 1.4 기준의 key-value 명령을 그대로 제공하며, 일부에 대해 확장된 명령을 제공한다. +따라서, 기존 memcached 1.4에서 사용한 명령들은 ARCUS Cache Server에서도 그대로 사용 가능하다. +[Key-Value 명령](ch04-command-key-value.md)에서 key-value 유형의 item에 대해 수행가능한 명령들을 소개한다. + +Collection 기능 +--------------- + +Collection 명령의 자세한 설명은 아래를 참고 바랍니다. + +- [List collection 명령](ch05-command-list-collection.md) +- [Set collection 명령](ch06-command-set-collection.md) +- [Map collection 명령](ch07-command-map-collection.md) +- [B+tree collection 명령](ch08-command-btree-collection.md) + +Collection 일부 명령들은 command pipelining 처리가 가능하며, +[Command Pipelining 기능](ch09-command-pipelining.md)에서 설명한다. + +Item Attributes 기능 +-------------------- + +Collection 지원으로 인해 item 유형이 다양해 졌으며, 다양한 item 유형에 따라 item attributes도 확장되었다. +Item attributes를 조회하거나 변경하기 위하여 [Item Attribute 명령](ch10-command-item-attribute.md)을 제공한다. + +Scan 기능 +-------------------- +조건에 맞는 item 혹은 prefix 목록을 가져오는 기능으로 [Scan 명령](ch11-command-scan.md)을 제공한다. + +Admin & Monitoring 기능 +----------------------- + +ARCUS Cache Server의 운영 상에 필요한 기능들은 [Admin & Monitoring 명령](ch12-command-administration.md)으로 제공한다. diff --git a/documentation/ascii-protocol/ch04-command-key-value.md b/documentation/ascii-protocol/ch04-command-key-value.md new file mode 100644 index 000000000..e8b66ee16 --- /dev/null +++ b/documentation/ascii-protocol/ch04-command-key-value.md @@ -0,0 +1,112 @@ +# Chapter 4. Simple Key-Value 명령 + +ARCUS Cache Server는 memcached 1.4의 key-value 명령을 그대로 지원하며, +이에 추가하여 incr/decr 명령은 그 기능을 확장 지원한다. + +Simple key-value 명령들의 요약은 아래와 같다. +이들 명령들의 자세한 정보는 [memcached 1.4의 기존 ASCII protocol](https://github.com/naver/arcus-memcached/blob/master/doc/protocol.txt)를 참고하기 바란다. + +## storage 명령 + +set, add, replace, append, prepend, cas 명령이 있으며 syntax는 다음과 같다. + +``` + [noreply]\r\n\r\n +cas [noreply]\r\n\r\n +``` + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|----------------------|------------------------ | +| "STORED" | 성공 +| "NOT_STORED" | 연산 조건에 부합하지 않아 저장에 실패 함. ex) 이미 존재하는 key에 대해 add 연산, 존재하지 않는 key에 대해 replace, append, prepend 연산. +| "NOT_FOUND" | cas 연산의 key miss. +| "EXISTS" | cas 연산의 응답으로, 해당 아이템이 클라이언트의 마지막 fetch 이후 수정된 적이 있음을 뜻함. +| "TYPE_MISMATCH" | 해당 아이템이 key-value 타입이 아님. +| "CLIENT_ERROR" | 클라이언트에서 잘못된 질의를 했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) bad command line format +| "SERVER ERROR" | 서버 측의 오류로 저장하지 못했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) out of memory + +## retrieval 명령 + +하나의 cache item을 조회하는 get, gets 명령이 있으며, syntax는 다음과 같다. +get 명령은 value만 조회하는 반면 gets 명령은 value와 함께 cas value도 조회한다. + +``` +get \r\n +gets \r\n +``` + +한번에 여러 cache item들을 조회하기 위한 mget, mgets 명령이 있으며, syntax는 다음과 같다. +mget, mgets 명령은 get, gets 처럼 mget 명령은 value만 조회하고 mgets 명령은 value와 함께 cas value도 조회한다. +mget 명령은 1.11 버전부터 mgets 명령은 1.13 버전부터 제공한다. + +``` +mget \r\n +<"space separated keys">\r\n +mgets \r\n +<"space separated keys">\r\n +``` +- \<”space separated keys”\> - key list로, 스페이스(' ')로 구분한다. +- \과 \ - key list 문자열의 길이와 key 개수를 나타낸다. + +retrieval 명령이 정상 수행되었을 경우, Response string은 아래와 같이 구성된다. + +- key hit된 아이템 정보를 모두 출력 +- key miss된 아이템은 별도 response 없이 생략 +- 응답의 끝에 "END\r\n" 출력 + +``` +VALUE []\r\n +\r\n\ +... +END\r\n +``` + +실패시 string은 아래와 같다. + + +| Response String | 설명 | +|----------------------|------------------------ | +| "CLIENT_ERROR" | 클라이언트에서 잘못된 질의를 했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) bad command line format +| "SERVER ERROR" | 서버 측의 오류로 조회하지 못했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) out of memory writing get response + +mget 명령에서 메모리 부족으로 일부 key에 대해서만 정상 조회한 후 실패한 경우, 전체 연산을 서버 에러 처리한다. + +## deletion 명령 + +delete 명령이 있으며 syntax는 다음과 같다. + +``` +delete [noreply]\r\n +``` + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|----------------------|------------------------ | +| "DELETED" | 성공 +| "NOT_FOUND" | key miss +| "CLIENT_ERROR" | 클라이언트에서 잘못된 질의를 했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) bad command line format + +## Increment/Decrement 명령 + +incr, decr 명령이 있으며, syntax는 아래와 같다. +ARCUS Cache Server는 이 명령을 확장하여, +해당 key가 존재하지 않는 경우에 initial 값을 가지는 새로운 key-value item을 생성한다. + +``` +incr [ ] [noreply]\r\n +decr [ ] [noreply]\r\n +``` + +성공시 Response string으로 incr, decr 연산을 적용한 값이 출력 된다. + +실패시 Response string과 의미는 아래와 같다. + +| Response String | 설명 | +|----------------------|------------------------ | +| "NOT_FOUND" | key miss +| "TYPE_MISMATCH" | 해당 아이템이 key-value 타입이 아님 +| "CLIENT_ERROR" | 클라이언트에서 잘못된 질의를 했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) invalid numeric delta argument, cannot increment or decrement non-numeric value +| "SERVER ERROR" | 서버 측의 오류로 연산하지 못했음을 의미. 이어 나오는 문자열을 통해 오류의 원인을 파악 가능. 예) out of memory diff --git a/documentation/ascii-protocol/ch05-command-list-collection.md b/documentation/ascii-protocol/ch05-command-list-collection.md new file mode 100644 index 000000000..832cd9a13 --- /dev/null +++ b/documentation/ascii-protocol/ch05-command-list-collection.md @@ -0,0 +1,152 @@ +# Chapter 5. LIST 명령 + +List collection에 관한 명령은 아래와 같다. + +- [List collection 생성: lop create](#lop-create-list-collection-생성) +- List collection 삭제: delete (기존 key-value item의 삭제 명령을 그대로 사용) + +List element에 관한 명령은 아래와 같다. + +- [List element 삽입: lop insert](#lop-insert-list-element-삽입) +- [List element 삭제: lop delete](#lop-delete-list-element-삭제) +- [List element 조회: lop get](#lop-get-list-element-조회) + +## lop create (List Collection 생성) + +List collection을 empty 상태로 생성한다. + +``` +lop create [noreply]\r\n +* attributes: [] [unreadable] +``` + +- \ - 대상 item의 key string +- \ - 설정할 item attributes. [Item Attribute 설명](../ch03-item-attributes.md)을 참조 바란다. + - unreadable - 명시하면, readable 속성은 off로 설정됩니다. +- noreply - 명시하면, response string을 전달받지 않는다. + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|----------------------------------------|------------------------ | +| "CREATED" | 성공 +| "EXISTS" | 동일 key string을 가진 item이 이미 존재 +| "NOT_SUPPORTED" | 지원하지 않음 +| “CLIENT_ERROR bad command line format” | protocol syntax 틀림 +| “SERVER_ERROR out of memory” | 메모리 부족 + +## lop insert (List Element 삽입) + +List collection에 하나의 element를 삽입한다. +List collection을 생성하면서 하나의 element를 삽입할 수도 있다. + +``` +lop insert [create ] [noreply|pipe]\r\n\r\n +* attributes: [] [unreadable] +``` + +- \ - 대상 item의 key string +- \ - 삽입 위치를 0-based index로 지정. + - 0, 1, 2, ... : list의 앞에서 시작하여 각 element 위치를 나타냄 + - -1, -2, -3, ... : list의 뒤에서 시작하여 각 element 위치를 나타냄 +- \ - 삽입할 데이터 길이 (trailing 문자인 "\r\n"을 제외한 길이) +- create \ - list collection 없을 시에 list 생성 요청. +[Item Attribute 설명](../ch03-item-attributes.md)을 참조 바란다. + - unreadable - 명시하면, readable 속성은 off로 설정됩니다. +- noreply or pipe - 명시하면, response string을 전달받지 않는다. +pipe 사용은 [Command Pipelining](ch09-command-pipelining.md)을 참조 바란다. +- \ - 삽입할 데이터 (최대 크기는 [기본제약사항](../ch01-arcus-basic-concept.md#기본-제약-사항)을 참고) + + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|------------------------------------------|------------------------ | +| "STORED" | 성공 (element만 삽입) +| “CREATED_STORED” | 성공 (collection 생성하고 element 삽입) +| “NOT_FOUND” | key miss +| “TYPE_MISMATCH” | 해당 item이 list collection이 아님 +| “OVERFLOWED” | overflow 발생 +| “OUT_OF_RANGE” | 삽입 위치가 list의 현재 element index 범위를 넘어섬. 예를 들어, 10개 element가 있는 상태에서 삽입 위치가 20인 경우임 +| "NOT_SUPPORTED" | 지원하지 않음 +| “CLIENT_ERROR bad command line format” | protocol syntax 틀림 +| “CLIENT_ERROR too large value” | 삽입할 데이터가 element value의 최대 크기보다 큼 +| “CLIENT_ERROR bad data chunk” | 삽입할 데이터 길이가 \와 다르거나 "\r\n"으로 끝나지 않음 +| “SERVER_ERROR out of memory” | 메모리 부족 + +## lop delete (List Element 삭제) + +List collection에 하나의 index 또는 index range에 해당하는 elements를 삭제한다. + +``` +lop delete [drop] [noreply|pipe]\r\n +lop delete 명령에서 각 인자의 설명은 아래와 같다. +``` +- \ - 대상 item의 key string +- \ - 삭제할 element의 index or index range. + Element index는 "lop insert" 명령에서 소개한 바와 같이 0-based index 형태로 지정하며, + index range는 index1..index2 형태로 표현하여, 그 예는 다음과 같다. + - 0..-1: 첫째 element부터 마지막 element까지 (forward 순서) + - 2..-2: 앞의 3번째 element부터 뒤의 2번째 element까지 (forward 순서) + - -3..-1: 뒤의 3번째 element부터 뒤의 1번째 element까지 (forward 순서) + - 4..2 : 앞의 5번째 element 부터 앞의 3번째 element까지 (backward 순서) + - -1..0: 마지막 element 부터 첫째 element 까지 (backward 순서) +- drop - element 삭제로 인해 empty list가 될 경우, 그 list를 drop할 것인지를 지정한다. +- noreply or pipe - 명시하면, response string을 전달받지 않는다. +pipe 사용은 [Command Pipelining](ch09-command-pipelining.md)을 참조 바란다. + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|------------------------------------------|------------------------ | +| "DELETED" | 성공 (element만 삭제) +| “DELETED_DROPPED” | 성공 (element 삭제하고 list를 drop한 상태) +| “NOT_FOUND” | key miss +| “NOT_FOUND_ELEMENT” | element miss (single index or index range에 해당하는 element가 없음) +| “TYPE_MISMATCH” | 해당 item이 list collection이 아님 +| "NOT_SUPPORTED" | 지원하지 않음 +| “CLIENT_ERROR bad command line format” | protocol syntax 틀림 + +## lop get (List Element 조회) + +List collection에 하나의 index 또는 index range에 해당하는 elements를 조회한다. + +``` +lop get [delete|drop]\r\n +``` + +- \ - 대상 item의 key string +- \ - 조회할 element의 index or index range. "lop delete" 명령의 인자 참조 +- delete or drop - element 조회하면서 그 element를 delete할 것인지, +그리고 delete로 인해 empty list가 될 경우 그 list를 drop할 것인지를 지정한다. + +성공 시의 response string은 아래와 같다. +VALUE 라인의 \는 조회된 element 개수를 의미한다. +마지막 라인은 END, DELETED, DELETED_DROPPED 중의 하나를 가지며, +각각 element 조회만 수행한 상태, element 조회하고 삭제한 상태, +element 조회 및 삭제하고 list를 drop한 상태를 의미한다. + +``` +VALUE \r\n + \r\n + \r\n + \r\n +... +END|DELETED|DELETED_DROPPED\r\n +``` + +실패 시의 response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|--------------------------------------------------------|------------------------ | +| “NOT_FOUND” | key miss +| “NOT_FOUND_ELEMENT” | element miss (index or index range에 해당하는 element가 없음) +| “TYPE_MISMATCH” | 해당 item이 list collection이 아님 +| “UNREADABLE” | 해당 item이 unreadable item임 +| "NOT_SUPPORTED" | 지원하지 않음 +| “CLIENT_ERROR bad command line format” | protocol syntax 틀림 +| "SERVER_ERROR out of memory [writing get response]” | 메모리 부족 + + +[item-attribute]: ch03-item-attributes.md "Chapter 3. Item Attribute 설명" +[command-pipelining]: ch09-command-pipelining.md "Chapter 9. Command Pipelining" diff --git a/documentation/ascii-protocol/ch06-command-set-collection.md b/documentation/ascii-protocol/ch06-command-set-collection.md new file mode 100644 index 000000000..29f7aa6c9 --- /dev/null +++ b/documentation/ascii-protocol/ch06-command-set-collection.md @@ -0,0 +1,168 @@ +# Chapter 6. SET 명령 + +Set collection에 관한 명령은 아래와 같다. + +- [Set collection 생성: sop create](#sop-create-set-collection-생성) +- Set collection 삭제: delete (기존 key-value item의 삭제 명령을 그대로 사용) + +Set element에 관한 명령은 아래와 같다. + +- [Set element 삽입: sop insert](#sop-insert-set-element-삽입) +- [Set element 삭제: sop delete](#sop-delete-set-element-삭제) +- [Set element 조회: sop get](#sop-get-set-element-조회) +- [Set element 존재유무 검사: sop exist](#sop-exist-set-element-존재유무-검사) + +## sop create (Set Collection 생성) + +Set collection을 empty 상태로 생성한다. + +``` +sop create [noreply]\r\n +* : [] [unreadable] +``` + +- \ - 대상 item의 key string +- \ - 설정할 item attributes. [Item Attribute 설명](../ch03-item-attributes.md)을 참조 바란다. + - unreadable - 명시하면, readable 속성은 off로 설정됩니다. +- noreply - 명시하면, response string을 전달받지 않는다. + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|------------------------------------------|------------------------ | +| "CREATED" | 성공 +| "EXISTS" | 동일 key string을 가진 item이 이미 존재 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "SERVER_ERROR out of memory" | 메모리 부족 + +## sop insert (Set Element 삽입) + +Set collection에 하나의 element를 삽입한다. +Set collection을 생성하면서 하나의 element를 삽입할 수도 있다. + +``` +sop insert [create ] [noreply|pipe]\r\n\r\n +* : [] [unreadable] +``` + +- \ - 대상 item의 key string +- \ - 삽입할 데이터 길이 (trailing 문자인 "\r\n"을 제외한 길이) +- create \ - set collection 없을 시에 set 생성 요청. +[Item Attribute 설명](../ch03-item-attributes.md)을 참조 바란다. + - unreadable - 명시하면, readable 속성은 off로 설정됩니다. +- noreply or pipe - 명시하면, response string을 전달받지 않는다. +pipe 사용은 [Command Pipelining](ch09-command-pipelining.md)을 참조 바란다. +- \ - 삽입할 데이터 (최대 크기는 [기본제약사항](ch01-arcus-basic-concept.md#기본-제약-사항)을 참고) + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|------------------------------------------|------------------------ | +| "STORED" | 성공 (element만 삽입) +| "CREATED_STORED" | 성공 (collection 생성하고 element 삽입) +| "NOT_FOUND" | key miss +| "TYPE_MISMATCH" | 해당 item이 set collection이 아님 +| "OVERFLOWED" | overflow 발생 +| "ELEMENT_EXISTS" | 동일 데이터를 가진 element가 존재. set uniqueness 위배 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "CLIENT_ERROR too large value" | 삽입할 데이터가 element value의 최대 크기보다 큼 +| "CLIENT_ERROR bad data chunk" | 삽입할 데이터 길이가 \와 다르거나 "\r\n"으로 끝나지 않음 +| "SERVER_ERROR out of memory" | 메모리 부족 + +## sop delete (Set Element 삭제) + +Set collection에서 하나의 element를 삭제한다. + +``` +sop delete [drop] [noreply|pipe]\r\n\r\n +``` + +- \ - 대상 item의 key string +- \ - 삭제할 데이터 길이 (trailing 문자인 "\r\n"을 제외한 길이) +- drop - element 삭제로 인해 empty set이 될 경우, 그 set을 drop할 것인지를 지정한다. +- noreply or pipe - 명시하면, response string을 전달받지 않는다. +pipe 사용은 [Command Pipelining](ch09-command-pipelining.md)을 참조 바란다. +- \ - 삭제할 데이터 + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------|------------------------ | +| "DELETED" | 성공 (element만 삭제) +| "DELETED_DROPPED" | 성공 (element 삭제하고 collection을 drop한 상태) +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | element miss (삭제할 element가 없음) +| "TYPE_MISMATCH" | 해당 item이 set collection이 아님 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "CLIENT_ERROR too large value" | 삭제할 데이터가 element value의 최대 크기보다 큼 +| "CLIENT_ERROR bad data chunk" | 삭제할 데이터의 길이가 \와 다르거나 “\r\n”으로 끝나지 않음 + +## sop get (Set Element 조회) + +Set collection에서 N 개의 elements를 조회한다. + +``` +sop get [delete|drop]\r\n +``` + +- \ - 대상 item의 key string +- \ - 조회할 elements 개수를 지정. 0이면 전체 elements를 의미한다. +- delete or drop - element 조회하면서 그 element를 delete할 것인지, +그리고 delete로 인해 empty set이 될 경우 그 set을 drop할 것인지를 지정한다. + +성공 시의 response string은 아래와 같다. +VALUE 라인의 \는 조회된 element 개수를 의미한다. +마지막 라인은 END, DELETED, DELETED_DROPPED 중의 하나를 가지며 +각각 element 조회만 수행한 상태, element 조회하고 삭제한 상태, +element 조회 및 삭제하고 set을 drop한 상태를 의미한다. + +``` +VALUE \r\n + \r\n + \r\n + \r\n +... +END|DELETED|DELETED_DROPPED\r\n +``` + +실패 시의 response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|------------------------------------------------------|------------------------ | +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | element miss (element가 존재하지 않는 상태임) +| "TYPE_MISMATCH" | 해당 item이 set collection이 아님 +| "UNREADABLE" | 해당 item이 unreadable item임 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "SERVER_ERROR out of memory [writing get response]" | 메모리 부족 + +## sop exist (Set Element 존재유무 검사) + +Set collection에 특정 element의 존재 유무를 검사한다. + +``` +sop exist [pipe]\r\n\r\n +``` + +- \ - 대상 item의 key string +- \와 \ - 존재 유무를 검사할 데이터의 길이와 데이터 그 자체 +- pipe - 명시하면, response string을 전달받지 않는다. +[Command Pipelining](ch09-command-pipelining.md)을 참조 바란다. + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|------------------------------------------|------------------------ | +| "EXIST" | 성공 (주어진 데이터가 set에 존재) +| "NOT_EXIST" | 성공 (주어진 데이터가 set에 존재하지 않음) +| "NOT_FOUND" | key miss +| "TYPE_MISMATCH" | 해당 item이 set collection이 아님 +| "UNREADABLE" | 해당 item이 unreadable item임 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "CLIENT_ERROR too large value" | 주어진 데이터가 element value의 최대 크기보다 큼 +| "CLIENT_ERROR bad data chunk" | 주어진 데이터의 길이가 \와 다르거나 “\r\n”으로 끝나지 않음 diff --git a/documentation/ascii-protocol/ch07-command-map-collection.md b/documentation/ascii-protocol/ch07-command-map-collection.md new file mode 100644 index 000000000..63c8e2c59 --- /dev/null +++ b/documentation/ascii-protocol/ch07-command-map-collection.md @@ -0,0 +1,177 @@ +# Chapter 7. MAP 명령 + +Map collection에 관한 명령은 아래와 같다. + +- [Map collection 생성: mop create](#mop-create-map-collection-생성) +- Map collection 삭제: delete (기존 key-value item의 삭제 명령을 그대로 사용) + +Map element에 관한 명령은 아래와 같다. + +- [Map element 삽입: mop insert](#mop-insert-map-element-삽입) +- [Map element 변경: mop update](#mop-update-map-element-변경) +- [Map element 삭제: mop delete](#mop-delete-map-element-삭제) +- [Map element 조회: mop get](#mop-get-map-field-element-조회) + +## mop create (Map Collection 생성) + +Map collection을 empty 상태로 생성한다. + +``` +mop create [noreply]\r\n +* : [] [unreadable] +``` + +- \ - 대상 item의 key string +- \ - 설정할 item attributes. [Item Attribute 설명](../ch03-item-attributes.md)을 참조 바란다. + - unreadable - 명시하면, readable 속성은 off로 설정됩니다. +- noreply - 명시하면, response string을 전달받지 않는다. + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|----------------------------------------|------------------------ | +| "CREATED" | 성공 +| "EXISTS" | 동일 key string을 가진 item이 이미 존재 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "SERVER_ERROR out of memory" | 메모리 부족 + +## mop insert (Map Element 삽입) + +Map collection에 하나의 field, element를 삽입한다. +Map collection을 생성하면서 \로 구성된 하나의 element를 삽입할 수도 있다. + +``` +mop insert [create ] [noreply|pipe]\r\n\r\n +* : [] [unreadable] +``` + +- \ - 대상 item의 key string +- \ - 삽입할 element의 field string +- \ - 삽입할 element의 데이터 길이 (trailing 문자인 "\r\n"을 제외한 길이) +- create \ - 해당 map collection 없을 시에 map 생성 요청. +[Item Attribute 설명](../ch03-item-attributes.md)을 참조 바란다. + - unreadable - 명시하면, readable 속성은 off로 설정됩니다. +- noreply or pipe - 명시하면, response string을 전달받지 않는다. +pipe 사용은 [Command Pipelining](ch09-command-pipelining.md)을 참조 바란다. +- \ - 삽입할 데이터 (최대 크기는 [기본제약사항](../ch01-arcus-basic-concept.md#기본-제약-사항)을 참고) + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------|------------------------ | +| "STORED" | 성공 (field, element 삽입) +| "CREATED_STORED" | 성공 (collection 생성하고 field, element 삽입) +| "NOT_FOUND" | key miss +| "TYPE_MISMATCH" | 해당 item이 map collection이 아님 +| "OVERFLOWED" | overflow 발생 +| "ELEMENT_EXISTS" | 동일 이름의 field가 이미 존재. map field uniqueness 위배 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "CLIENT_ERROR too large value" | 삽입할 데이터가 element value의 최대 크기보다 큼 +| "CLIENT_ERROR bad data chunk" | 삽입할 데이터 길이가 \와 다르거나 "\r\n"으로 끝나지 않음 +| "CLIENT_ERROR invalid prefix name" | 유효하지(존재하지) 않는 prefix 명 +| "SERVER_ERROR out of memory" | 메모리 부족 + +## mop update (Map Element 변경) + +Map collection에서 하나의 field에 대해 element 변경을 수행한다. +현재 다수 field에 대한 변경연산은 제공하지 않는다. + +``` +mop update [noreply|pipe]\r\n\r\n +``` + +- \ - 대상 item의 key string +- \ - 대상 element의 field string +- \ - 변경할 데이터 길이 (trailing 문자인 "\r\n"을 제외한 길이) +- noreply or pipe - 명시하면, response string을 전달받지 않는다. +pipe 사용은 [Command Pipelining](ch09-command-pipelining.md)을 참조 바란다. +- \ - 변경할 데이터 자체 + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|------------------------------------------|------------------------ | +| "UPDATED" | 성공 (element 변경) +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | field miss +| "TYPE_MISMATCH" | 해당 item이 map collection이 아님 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "CLIENT_ERROR too large value" | 삽입할 데이터가 element value의 최대 크기보다 큼 +| "CLIENT_ERROR bad data chunk" | 삽입할 데이터 길이가 \와 다르거나 "\r\n"으로 끝나지 않음 +| "SERVER_ERROR out of memory" | 메모리 부족 + +## mop delete (Map Element 삭제) + +Map collection에서 하나 이상의 field 이름을 주어, 그에 해당하는 element를 삭제한다. + +``` +mop delete [drop] [noreply|pipe]\r\n +[<"space separated fields">]\r\n +``` + +- "space separated fields" - 대상 map의 field list로, 스페이스(' ')로 구분한다. + - 하위 호환성(1.10.X 이하 버전)을 위해 콤마(,)도 지원하지만 권장하지 않는다. +- \ - 대상 item의 key string +- \과 \ - field list 문자열의 길이와 field 개수를 나타낸다. 0이면 전체 field, element를 의미한다. +- drop - field, element 삭제로 인해 empty map이 될 경우, 그 map을 drop할 것인지를 지정한다. +- noreply or pipe - 명시하면, response string을 전달받지 않는다. +pipe 사용은 [Command Pipelining](ch09-command-pipelining.md)을 참조 바란다. + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------|------------------------ | +| "DELETED" | 성공 (전체 또는 일부 field, element 삭제) +| "DELETED_DROPPED" | 성공 (전체 또는 일부 field, element 삭제하고 collection을 drop한 상태) +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | field miss (삭제할 field, element가 없음. 모든 field가 없을 시에만 리턴) +| "TYPE_MISMATCH" | 해당 item이 map collection이 아님 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 + +## mop get (Map Field, Element 조회) + +Map collection에서 하나 이상의 field 이름을 주어, 그에 해당하는 element를 조회한다. + +``` +mop get [delete|drop]\r\n +[<"space separated fields">]\r\n +``` + +- "space separated fields" - 대상 map의 field list로, 스페이스(' ')로 구분한다. + - 하위 호환성(1.10.X 이하 버전)을 위해 콤마(,)도 지원하지만 권장하지 않는다. +- \ - 대상 item의 key string +- \ 과 \ - field list 문자열의 길이와 field 개수를 나타낸다. 0이면 전체 field, element를 의미한다. +- delete or drop - field, element 조회하면서 그 field, element를 delete할 것인지, +그리고 delete로 인해 empty map이 될 경우 그 map을 drop할 것인지를 지정한다. + +성공 시의 response string은 아래와 같다. +VALUE 라인의 \는 조회된 field 개수를 의미한다. +마지막 라인은 END, DELETED, DELETED_DROPPED 중의 하나를 가지며 +각각 field 조회만 수행한 상태, field 조회하고 삭제한 상태, +field 조회 및 삭제하고 map을 drop한 상태를 의미한다. + +``` +VALUE \r\n + \r\n + \r\n + \r\n +... +END|DELETED|DELETED_DROPPED\r\n +``` + +실패 시의 response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|------------------------------------------------------|------------------------ | +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | field miss (주어진 field 이름들 중 하나라도 가진 element가 전혀 없는 상태임) +| "TYPE_MISMATCH" | 해당 item이 map collection이 아님 +| "UNREADABLE" | 해당 item이 unreadable item임 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "SERVER_ERROR out of memory [writing get response]" | 메모리 부족 + diff --git a/documentation/ascii-protocol/ch08-command-btree-collection.md b/documentation/ascii-protocol/ch08-command-btree-collection.md new file mode 100644 index 000000000..ae4cc90be --- /dev/null +++ b/documentation/ascii-protocol/ch08-command-btree-collection.md @@ -0,0 +1,666 @@ +# Chapter 8. B+Tree 명령 + +B+tree collection에 관한 명령은 아래와 같다. + +- [B+tree collection 생성: bop create](#bop-create-btree-collection-%EC%83%9D%EC%84%B1) +- B+tree collection 삭제: delete (기존 key-value item의 삭제 명령을 그대로 사용) + +B+tree element에 관한 기본 명령은 아래와 같다. + +- [B+tree element 삽입/대체: bop insert/upsert](#bop-insertupsert-btree-element-삽입대체) +- [B+tree element 변경: bop update](#bop-update-btree-element-%EB%B3%80%EA%B2%BD) +- [B+tree element 삭제: bop delete](#bop-delete-btree-element-삭제) +- [B+tree element 조회: bop get](#bop-get-btree-element-조회) +- [B+tree element 개수 계산: bop count](#bop-count-btree-element-개수-계산) +- [B+tree element 값의 증감: bop incr/decr](#bop-incrdecr-btree-element-값의-증감) + +ARCUS cache server는 다수의 b+tree들에 대한 조회 기능을 특별히 제공하며, 이들은 아래와 같다. + +- [하나의 명령으로 여러 b+tree들에 대한 조회를 한번에 수행하는 기능: bop mget](#bop-mget-btree-multiple-get) +- [여러 b+tree들에서 조회 조건을 만족하는 elements를 sort merge하여 최종 결과를 얻는 기능: bop smget](#bop-smget-btree-sort-merge-get) + +ARCUS cache server는 bkey 기반의 element 조회 기능 외에도 b+tree position 기반의 element 조회 기능을 제공한다. +B+tree에서 특정 element의 position이란 b+teee에서의 그 element의 위치 정보로서, +bkey들의 정렬(ASC or DESC) 기준으로 봐서 몇 번째 위치한 element인지를 나타낸다. +B+tree position은 0-based index로 표현한다. +예를 들어, b+tree에 N개의 elements가 있다면 0부터 N-1까지의 index로 나타낸다. + +ARCUS cache server에서 제공하는 b+tree position 관련 명령은 다음과 같다. + +- [B+tree에서 특정 bkey의 position을 조회하는 기능 : bop position](#bop-position-btree-position-조회) +- [B+tree에서 하나의 position 또는 position range에 해당하는 element를 조회하는 기능 : bop gbp(get by position)](#bop-gbp-btree-get-by-position) +- [B+tree에서 특정 bkey의 position과 element 그리고 그 위치 앞뒤의 element를 함께 조회하는 기능: bop pwg(position with get)](#bop-pwg-btree-find-position-with-get-version-180) + +B+tree position 기반의 조회가 필요한 예를 하나 들면, ranking 시스템이 있다. +Ranking 시스템에서는 특정 score를 bkey로 하여 해당 elements를 저장하고, +조회는 최고/최저 score 기준으로 몇번째 위치 또는 위치의 범위에 해당하는 element를 찾는 경우가 많다. + + +## bop create (B+tree Collection 생성) + +B+tree collection을 empty 상태로 생성한다. + +``` +bop create [noreply]\r\n +* attributes: [] [unreadable] +``` + +- \ - 대상 item의 key string +- \ - 설정할 item attributes. +[Item Attribute 설명](../ch03-item-attributes.md)을 참조 바란다. + - unreadable - 명시하면, readable 속성은 off로 설정됩니다. +- noreply - 명시하면, response string을 전달받지 않는다. + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------|------------------------ | +| "CREATED" | 성공 +| "EXISTS" | 동일 key string을 가진 item이 이미 존재 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "SERVER_ERROR out of memory" | 메모리 부족 + +## bop insert/upsert (B+Tree Element 삽입/대체) + +B+tree collection에 하나의 element를 추가하는 명령으로 +(1) 하나의 element를 삽입하는 bop insert 명령과 +(2) 현재 삽입하는 bkey를 가진 element가 없으면 현재의 element를 삽입하고 +그 bkey를 가진 element가 있으면 현재의 element로 대체시키는 bop upsert 명령이 있다. +이들 명령 수행에서 b+tree collection을 생성하면서 하나의 element를 추가할 수도 있다. + +``` +bop insert [] [create ] [noreply|pipe|getrim]\r\n\r\n +bop upsert [] [create ] [noreply|pipe|getrim]\r\n\r\n +* attributes: [] [unreadable] +``` + +- \ - 대상 item의 key string +- \ - 삽입할 element의 bkey +- \ - 삽입할 element의 optional flag +- \와 \ - 삽입할 element의 데이터의 길이와 데이터 그 자체 (최대 크기는 [기본제약사항](../ch01-arcus-basic-concept.md#기본-제약-사항)을 참고) +- create \ - b+tree collection 없을 시에 b+tree 생성 요청. +[Item Attribute 설명](../ch03-item-attributes.md)을 참조 바란다. + - unreadable - 명시하면, readable 속성은 off로 설정됩니다. +- noreply or pipe - 명시하면, response string을 전달받지 않는다. +pipe 사용은 [Command Pipelining](ch09-command-pipelining.md)을 참조 바란다. +- getrim - 새로운 element 추가로 maxcount 제약에 의한 overflow trim이 발생할 경우, +trim된 element 정보를 가져온다. + +Trimmed element 정보가 리턴되는 경우, 그 response string은 아래와 같다. + +``` +VALUE \r\n + [] \r\n +END\r\n +``` + +그 외의 response string과 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------|------------------------ | +| "STORED" | 성공 (element만 삽입) +| "CREATED_STORED" | 성공 (collection 생성하고 element 삽입) +| "REPLACED" | 성공 (element를 대체) +| "NOT_FOUND" | key miss +| "TYPE_MISMATCH" | 해당 item이 b+tree colleciton이 아님 +| "BKEY_MISMATCH" | 삽입할 bkey 유형과 대상 b+tree의 bkey 유형이 다름 +| "OVERFLOWED" | overflow 발생 +| "OUT_OF_RANGE" | 새로운 element 삽입이 maxcount 또는 maxbkeyrange 제약을 위배하면서 그 element의 bkey 값이 overflowaction에 의해 자동 삭제되는 경우이어서 삽입이 실패하는 경우이다. 예를 들어, smallest_trim 상황에서 새로 삽입할 element의 bkey 값이 b+tree의 smallest bkey 보다 작으면서 maxcount 개의 elements가 이미 존재하거나 maxbkeyrange를 벗어나는 경우가 이에 해당된다. +| "ELEMENT_EXISTS" | 동일 bkey를 가진 element가 존재 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "CLIENT_ERROR too large value" | 삽입할 데이터가 element value의 최대 크기보다 큼 +| "CLIENT_ERROR bad data chunk" | 삽입할 데이터의 길이가 \와 다르거나 "\r\n"으로 끝나지 않음 +| "SERVER_ERROR out of memory" | 메모리 부족 + +## bop update (B+Tree Element 변경) + +B+tree collection에서 하나의 element에 대해 eflag 변경 그리고/또는 data 변경을 수행한다. +현재 다수 elements에 대한 변경 연산은 제공하지 않고 있다. + +``` +bop update [] [noreply|pipe]\r\n[\r\n] +* eflag_update : [ ] +``` + +- \ - 대상 item의 key string +- \ - 대상 element의 bkey +- \ - eflag update 명시. +[Collection 기본 개념](../ch02-collection-items.md)에서 eflag update를 참조 바란다. +- \와 \ - 새로 변경할 데이터의 길이와 데이터 그 자체. 데이터 변경을 원치 않으면 \를 -1로 하고 \를 생략하면 된다. +- noreply or pipe - 명시하면, response string을 전달받지 않는다. +pipe 사용은 [Command Pipelining](ch09-command-pipelining.md)을 참조 바란다. + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------|------------------------ | +| "UPDATED" | 성공 +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | element miss (변경할 element가 없음) +| "TYPE_MISMATCH" | 해당 item이 b+tree colleciton이 아님 +| "BKEY_MISMATCH" | 명령 인자로 주어진 bkey 유형과 대상 b+tree의 bkey 유형이 다름 +| "EFLAG_MISMATCH" | 해당 element의 eflag 값에 대해 \를 적용할 수 없음. 예를 들어, 변경하고자 하는 eflag가 존재하지 않거나, 존재하더라도 \ 조건으로 명시된 부분의 데이터를 가지지 않은 상태이다. +| "NOTHING_TO_UPDATE" | eflag 변경과 data 변경 중 어느 하나도 명시되지 않은 상태 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "CLIENT_ERROR too large value" | 변경할 데이터가 element value의 최대 크기보다 큼 +| "CLIENT_ERROR bad data chunk" | 변경할 데이터의 길이가 \와 다르거나 "\r\n"으로 끝나지 않음 +| "SERVER_ERROR out of memory" | 메모리 부족 + +## bop delete (B+Tree Element 삭제) + +b+tree collection에서 하나의 bkey 또는 bkey range 조건과 eflag filter 조건을 만족하는 +N 개의 elements를 삭제한다. + +``` +bop delete [] [] [drop] [noreply|pipe]\r\n +* : [ ] +``` + +- \ - 대상 item의 key string +- \ - 하나의 bkey 또는 bkey range 조회 조건. +Bkey range는 "bkey1..bkey2" 형식으로 표현한다. +- \ - eflag filter 조건. +[Collection 기본 개념](../ch02-collection-items.md)에서 eflag filter 참조 바란다. +- \ - 삭제할 elements 개수 지정 +- drop - element 삭제로 인해 empty b+tree가 될 경우, 그 b+tree를 drop할 것인지를 지정한다. +- noreply or pipe - 명시하면, response string을 전달받지 않는다. +pipe 사용은 [Command Pipelining](ch09-command-pipelining.md)을 참조 바란다. + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------|------------------------ | +| "DELETED" | 성공 (element만 삭제) +| "DELETED_DROPPED" | 성공 (element 삭제하고 collection을 drop한 상태) +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | element miss (삭제할 element가 없음) +| "TYPE_MISMATCH" | 해당 item이 b+tree colleciton이 아님 +| "BKEY_MISMATCH" | 명령 인자의 bkey 유형과 대상 b+tree의 bkey 유형이 다름 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 + +## bop get (B+Tree Element 조회) + +B+tree collection에서 하나의 bkey 또는 bkey range 조건과 eflag filter 조건을 만족하는 +elements에서 offset 개를 skip한 후 count 개의 elements를 조회한다. + +``` +bop get [] [[] ] [delete|drop]\r\n +* : [ ] +``` + +- \ - 대상 item의 key string +- \ - 하나의 bkey 또는 bkey range 조회 조건. Bkey range는 "bkey1..bkey2" 형식으로 표현한다. +- \ - eflag filter 조건. [Collection 기본 개념](../ch02-collection-items.md)에서 eflag filter 참조 바란다. +- [\] \ - 조회 조건을 만족하는 elements에서 skip 개수와 실제 조회할 개수 +- delete or drop - element 조회하면서 그 element를 delete할 것인지 +그리고 delete로 인해 empty b+tree가 될 경우 그 b+tree를 drop할 것인지를 지정한다. + +성공 시의 response string은 아래와 같다. + +``` +VALUE \r\n + [] \r\n + [] \r\n + [] \r\n +… +END|TRIMMED|DELETED|DELETED_DROPPED\r\n +``` + +위 response string에 대한 설명은 다음과 같다. + +VALUE 라인의 \는 조회된 element 개수를 나타내며, +그 다음 라인 부터 조회된 각 element의 bkey, flag, data가 나타낸다. +마지막 라인은 조회 상태로서 END, TRIMMED, DELETED, DELETED_DROPPED 중 하나를 가진다. +END, DELEETED, DELEETD_DROPPED은 각각 +element 조회만 수행한 상태, element 조회하고 삭제한 상태, +element 조회 및 삭제한 후 empty b+tree collection도 drop한 상태를 의미한다. +TRIMMED는 특별한 의미로서, element 조회만 수행한 상태이면서 +element 조회 조건이 b+tree의 overflowaction으로 trim된 bkey 영역과 overlap 되었음을 나타낸다. +이를 통해, 조회 조건을 만족하지만 overflow trim으로 조회되지 않은 elements가 있을 수 있음을 +해당 응용이 알 수 있게 한다. 그러면, 해당 응용은 필요시, +back-end storage에서 조회되지 않은 나머지 elements를 다시 조회할 수 있다. +참고로, overflow action으로 smallest_silent_trim 또는 largest_silent_trim을 사용한다면, +b+tree collection 내부에 trim 발생 여부를 유지하지 않아 TRIMMED와 같은 trim 발생 상태를 +알려주지 않게 된다. 이 경우, trim 발생 여부에 대한 검사는 응용에서 자체적으로 수행해야 한다. + +실패 시의 response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-------------------------------------------------------|------------------------ | +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | element miss (조회 조건을 만족하는 element가 없음) +| "OUT_OF_RANGE" | 조회 조건을 만족하는 element가 없으며, 또한 주어진 bkey range가 b+tree의 overflowaction에 의해 trim된 bkey 영역과 overlap 되었음을 나타낸다. +| "TYPE_MISMATCH" | 해당 item이 b+tree collection이 아님 +| "BKEY_MISMATCH" | 명령 인자로 주어진 bkey 유형과 대상 b+tree의 bkey 유형이 다름 +| "UNREADABLE" | 해당 item이 unreadable item임 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "SERVER_ERROR out of memory [writing get response]" | 메모리 부족 + +## bop count (B+Tree Element 개수 계산) + +b+tree collection에서 하나의 bkey 또는 bkey range 조건과 eflag filter 조건을 만족하는 +elements 개수를 구한다. + +``` +bop count []\r\n +* : [ ] +``` + +- \ - 대상 item의 key string +- \ - 하나의 bkey 또는 bkey range 조회 조건. +Bkey range는 "bkey1..bkey2" 형식으로 표현한다. +- \ - eflag filter 조건. +[Collection 기본 개념](../ch02-collection-items.md)에서 eflag filter 참조 바란다. + +성공 시의 response string은 아래와 같다. + +``` +COUNT= +``` + +실패 시의 return string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|------------------------------------------|------------------------ | +| "NOT_FOUND" | key miss +| "TYPE_MISMATCH" | 해당 item이 b+tree collection이 아님 +| "BKEY_MISMATCH" | 명령 인자로 주어진 bkey 유형과 대상 b+tree의 bkey 유형이 다름 +| "UNREADABLE" | 해당 item이 unreadable item임 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 + +## bop incr/decr (B+Tree Element 값의 증감) + +B+tree collection 특정 하나의 element에 있는 데이터를 increment 또는 decrement하고, +증감된 데이터를 반환한다. +이 명령은 key-value item에 대한 incr/decr 명령과 유사한 명령으로 +이 명령을 수행할 b+tree element의 데이터는 증감이 가능한 숫자형 데이터이어야 한다. + +``` +bop incr [ []] [noreply|pipe]\r\n +bop decr [ []] [noreply|pipe]\r\n +``` + +- \ - 대상 item의 key string +- \ - 대상 element의 bkey +- \ - increment/decrement할 delta 값으로서, 0 보다 큰 숫자 값을 가져야 한다. + - increment 연산으로 64bit unsigned integer가 overflow되면, wrap around되어 잔여 값으로 설정된다. + - decrement 연산으로 64bit unsigned integer가 underflow되면, 새로운 값은 무조건 0으로 설정된다. +- \ - 대상 element가 없을 경우, 새로운 element를 생성하고 initial 값으로 설정한다. + - \는 새로은 element에 eflag 값을 줄 경우에 명시할 수 있다. + +성공 시의 response string은 아래와 같다. +Increment/decrement 수행 후의 데이터 값이다. + +``` +\r\n +``` + +실패 시의 response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------------------------------|------------------------ | +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | element miss +| "TYPE_MISMATCH" | 해당 item이 b+tree collection이 아님 +| "BKEY_MISMATCH" | 명령 인자로 주언진 bkey 유형과 대상 b+tree의 bkey 유형이 다름 +| "OUT_OF_RANGE" | 새로운 element 삽입이 maxcount 또는 maxbkeyrange 제약을 위배하면서 그 element의 bkey 값이 overflowaction에 의해 자동 삭제되는 경우이어서 삽입이 실패하는 경우이다. 예를 들어, smallest_trim 상황에서 새로 삽입할 element의 bkey 값이 b+tree의 smallest bkey 보다 작으면서 maxcount 개의 elements가 이미 존재하거나 maxbkeyrange를 벗어나는 경우가 이에 해당된다. +| "OVERFLOWED" | overflow 발생 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR cannot increment or decrement non-numeric value" | 해당 element의 데이터가 숫자형이 아님. +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "SERVER_ERROR out of memory [writing get response]" | 메모리 부족 + +## bop mget (B+Tree Multiple Get) + +여러 b+tree들에 대해 동일 조회 조건(bkey range와 eflag filter)으로 element들을 한꺼번에 조회한다. +여러 b+tree들에 대한 동일 조회 조건을 사용하므로, 대상 b+tree들은 동일 bkey 유형을 가져야 한다. +그리고, eflag에 대해서도 동일 성격의 데이터를 사용하기를 권고한다. + +``` +bop mget [] [] \r\n +<”space separated keys”>\r\n +* : [ ] +``` + +- \<”space separated keys”\> - 대상 b+tree들의 key list로, 스페이스(' ')로 구분한다. + - 하위 호환성(1.10.X 이하 버전)을 위해 콤마(,)도 지원하지만 권장하지 않는다. +- \과 \ - key list 문자열의 길이와 key 개수를 나타낸다. +- \ - 하나의 bkey 또는 bkey range 조회 조건. Bkey range는 "bkey1..bkey2" 형식으로 표현한다. +- \ - eflag filter 조건. [Collection 기본 개념](../ch02-collection-items.md)에서 eflag filter 참조 바란다. +- [\] \ - 조회 조건을 만족하는 elements에서 skip 개수와 실제 조회할 개수 + +bop mget 명령은 O(small N) 수행 원칙을 위하여 다음의 제약 사항을 가진다. +- key list에 지정 가능한 최대 key 수는 200이다. +- count의 최대 값은 50이다. + + +성공 시의 response string은 다음과 같다. + +``` +VALUE [ ]\r\n +[ELEMENT [] \r\n + ... + ELEMENT [] \r\n] +VALUE [ ]\r\n +[ELEMENT [] \r\n + ... + ELEMENT [] \r\n] + +... + +VALUE [ ]\r\n +[ELEMENT [] \r\n + ... + ELEMENT [] \r\n] +END\r\n +``` + +조회한 대상 key마다 VALUE 라인이 있으며, 대상 key string과 조회 상태가 나타난다. +조회 상태는 아래 중의 하나가 되며, 각 의미는 bop get 명령의 response string을 참조 바란다. + +- OK : 정상 조회 +- TRIMMED : 정상 조회 But, trimmed element 존재 +- NOT_FOUND +- NOT_FOUND_ELEMENT +- OUT_OF_RANGE +- TYPE_MISMATCH +- BKEY_MISMATCH +- UNREADABLE + +조회 상태가 정상 조회된 상태인 "OK"와 "TRIMMED"이면, +그 key에 설정된 flags 값과 조회한 element 개수가 나오며, +다음 라인부터 조회한 각 element의 bkey optional eflag, data 길이와 data 그 자체가 나온다. +그 외의 조회 상태는 해당 key에서 element 조회를 실패한 경우이므로, +flags와 ecount를 포함하여 조회된 element 정보가 생략된다. + +실패 시의 response string과 그 의미는 다음과 같다. + +| Response String | 설명 | +|-------------------------------------------------------|------------------------ | +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "CLIENT_ERROR bad data chunk" | space separated key list의 길이가 \와 다르거나 “\r\n”으로 끝나지 않음 +| "CLIENT_ERROR bad value" | bop mget 명령의 제약 조건을 위배함. +| "SERVER_ERROR out of memory [writing get response]" | 메모리 부족 + +## bop smget (B+Tree Sort Merge Get) + +여러 b+tree들에서 bkey range 조건과 eflag filter 조건을 모두 만족하는 +elements를 sort merge 형태로 조회하면서 count 개의 elements를 가져온다. +즉, 여러 b+tree들을 하나의 large b+tree로 구성되어 있다고 보고, +이에 대한 element 조회 기능과 동일하다. + +smget 동작은 조회 범위와 어떤 b+tree의 trim 영역과의 겹침에 대한 처리로, +아래 두 가지 동작 모드가 있다. + +1) 기존 smget 동작 (1.8.X 이하 버전에서 동작하던 방식) + - smget 조회 조건을 만족하는 첫번째 element가 trim된 b+tree가 하나라도 존재하면 OUT_OF_RANGE 응답을 보낸다. + 이 경우, 응용은 모든 key에 대해 백엔드 저장소인 DB에서 elements 조회한 후에 + 응용에서 sort-merge 작업을 수행하여야 한다. + - OUT_OF_RANGE가 없는 상황에서 smget을 수행하면서 + 조회 조건을 만족하는 두번째 이후의 element가 trim된 b+tree를 만나게 되면, + 그 지점까지 조회한 elements를 최종 elements 결과로 하고 + smget 수행 상태는 TRIMMED로 하여 응답을 보낸다. + 이 경우, 응용은 모든 key에 대해 백엔드 저장소인 DB에서 trim 영역의 elements를 조회하여 + smget 결과에 반영하여야 한다. + +2) 신규 smget 동작 (1.9.0 이후 버전에서 추가된 방식) + - 기존의 OUT_OF_RANGE에 해당하는 b+tree를 missed keys로 분류하고 + 나머지 b+tree들에 대해 smget을 계속 수행한다. + 따라서, 응용에서는 missed keys에 한해서만 + 백엔드 저장소인 DB에서 elements를 조회하여 최종 smget 결과에 반영할 수 있다. + - smget 조회 조건을 만족하는 두번째 이후의 element가 trim된 b+tree가 존재하더라도, + 그 지점에서 smget을 중지하는 것이 아니라, 그러한 b+tree를 trimmed keys로 분류하고 + 원하는 개수의 elements를 찾을 때까지 smget을 계속 진행한다. + 따라서, 응용에서는 trimmed keys에 한하여 + 백엔드 저장소인 DB에서 trim된 elements를 조회하여 최종 smget 결과에 반영할 수 있다. + - bkey에 대한 unique 조회 기능을 지원한다. + 중복 bkey를 허용하여 조회하는 duplcate 조회 외에 + 중복 bkey를 제거하고 unique bkey만을 조회하는 unique 조회를 지원한다. + - 조회 조건에 offset 기능을 제거한다. + +기존 smget 연산을 사용하더라도, offset 값은 항상 0으로 사용하길 권고한다. +양수의 offset을 사용하는 smget에서 missed keys가 존재하고 +missed keys에 대한 DB 조회가 offset으로 skip된 element를 가지는 경우, +응용에서 정확한 offset 처리가 불가능해지기 때문이다. +이전의 조회 결과에 이어서 추가로 조회하고자 하는 경우, +이전에 조회된 bkey 값을 바탕으로 bkey range를 재조정하여 사용할 수 있다. + +``` +bop smget [] [duplicate|unique]\r\n +<"space separated keys">\r\n +* : [ ] +``` + +- \<”space separated keys”\> - 대상 b+tree들의 key list로, 스페이스(' ')로 구분한다. + - 하위 호환성(1.10.X 이하 버전)을 위해 콤마(,)도 지원하지만 권장하지 않는다. +- \과 \ - key list 문자열의 길이와 key 개수를 나타낸다. +- \ - 하나의 bkey 또는 bkey range 조회 조건. +Bkey range는 "bkey1..bkey2" 형식으로 표현한다. +- \ - eflag filter 조건. +[Collection 기본 개념](../ch02-collection-items.md)에서 eflag filter 참조 바란다. +- \ - 조회할 element 개수 +- [duplicate|unique] - smget 동작 방식을 지정한다. + - 생략되면, 예전 smget 동작을 수행한다. + - 지정되면, 신규 smget 동작을 수행한다. duplicate는 중복 bkey를 허용하고, unique는 중복 bkey를 제거한다. + +bop smget 명령은 O(small N) 수행 원칙을 위하여 다음의 제약 사항을 가진다. +- key list에 지정 가능한 최대 key 수는 10000이다. +- count의 최대 값은 2000이다. + +기존 smget 동작에서 성공 시의 response string은 다음과 같다. + +``` +VALUE \r\n + [] \r\n + [] \r\n + [] \r\n +... +MISSED_KEYS \r\n +\r\n +\r\n +… +END|DUPLICATED|TRIMMED|DUPLICATRED_TRIMMED\r\n +``` + +위 response string에 대한 설명은 다음과 같다. + +- VALUE 부분: 조회한 elements를 나타낸다. + - Element 정보는 조회한 element가 속한 b+tree의 key string과 flags 정보 + 그리고 그 element의 bkey, optional eflag, data로 구성된다. + - Element 정보는 bkey 기준으로 정렬되며, + 동일 bkey를 가진 elements는 key string 기준으로 정렬된다. +- MISSED_KEYS 부분: smget 조회에 참여하지 못한 key list와 그 원인을 나타낸다. + - \는 smget에 참여하지 못한 key string이다. +- 마지막 라인은 smget response string의 마지막을 나타낸다. + - END: 조회 결과에 중복 bkey가 없음 + - DUPLICATED: 조회 결과에 중복 bkey가 있음. + - TRIMMED: 조회 범위가 trim 영역과 겹치는 b+tree를 발견한 상태이다. + - DUPLICATED_TRIMMED: DUPLICATED와 TRIMMED 의미를 모두 가진다. + +신규 smget 동작에서 성공 시의 response string은 다음과 같다. + +``` +ELEMENTS \r\n + [] \r\n + [] \r\n + [] \r\n +... +MISSED_KEYS \r\n + \r\n + \r\n +… +TRIMMED_KEYS \r\n + \r\n + \r\n +… +END|DUPLICATED\r\n + +* = NOT_FOUND | UNREADABLE | OUT_OF_RANGE +``` + +위 response string에 대한 설명은 다음과 같다. + +- ELEMENTS 부분: 조회한 elements를 나타낸다. + - Element 정보는 조회한 element가 속한 b+tree의 key string과 flags 정보 + 그리고 그 element의 bkey, optional eflag, data로 구성된다. + - Element 정보는 bkey 기준으로 정렬되며, + 동일 bkey를 가진 elements는 key string 기준으로 정렬된다. +- MISSED_KEYS 부분: smget 조회에 참여하지 못한 key list와 그 원인을 나타낸다. + - \는 smget에 참여하지 못한 key string이다. + - \는 smget에 참여하지 못한 원인을 나타낸다. + - NOT_FOUND: 그 key가 cache에 존재하지 않음 + - UNREADABLE: 그 key가 unreadable 상태에 있음 + - OUT_OF_RANGE: bkey range의 시작 부분이 그 key의 trim 영역과 겹쳐 있음 +- TRIMMED_KEYS 부분: smget 조회 범위의 뒷 부분에서 trim이 발생한 key list이다. + - \는 trim이 발생한 key string이다. + - \는 trim 직전에 있던 마지막 bkey 이다. + - Timmed keys 정보는 bkey 기준으로 정렬된다. +- 마지막 라인은 smget response string의 마지막을 나타낸다. + - END: 조회 결과에 중복 bkey가 없음 + - DUPLICATED: 조회 결과에 중복 bkey가 있음. + + +smget 수행의 실패 시의 response string은 다음과 같다. + +| Response String | 설명 | +|------------------------------------------------------|------------------------ | +| "TYPE_MISMATCH" | 어떤 key가 b+tree type이 아님 +| "BKEY_MISMATCH" | smget에 참여된 b+tree들의 bkey 유형이 서로 다름. +| "OUT_OF_RANGE" | 기존 smget 동작에서만 발생할 수 있는 실패 response string이다. +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "CLIENT_ERROR bad data chunk" | 주어진 key 리스트에 중복 key가 존재하거나 주어진 key 리스트의 길이가 \ 길이와 다르거나 "\r\n"으로 끝나지 않음. +| "CLIENT_ERROR bad value" | 앞서 기술한 smget 연산의 제약 조건을 위배 +| "SERVER_ERROR out of memory [writing get response" | 메모리 부족 + + +## bop position (B+Tree Position 조회) + +b+tree collection에서 특정 element의 position을 조회한다. +Element의 position이란 b+tree에서의 위치 정보로서, +bkey들의 정렬(ASC or DESC) 기준으로 몇 번째 위치한 element인지를 나타내는 +0부터 N-1까지의 index를 의미한다. + +``` +bop position \r\n +* = asc | desc +``` + +- \ - 대상 item의 key string +- \ - 대상 element의 bkey +- \ - 어떤 bkey 정렬 기준으로 position을 얻을 것인지 명시 + +성공 시의 response string은 아래와 같다. + +``` +POSITION=\r\n +``` + +실패 시의 response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|------------------------------------------|------------------------ | +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | element miss +| "TYPE_MISMATCH" | b+tree collection 아님 +| "BKEY_MISMATCH" | 명령 인자로 주어진 bkey 유형과 대상 b+tree의 bkey 유형이 다름 +| "UNREADABLE" | 해당 item이 unreadable item임 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 + +## bop gbp (B+Tree Get By Position) + +B+tree collection에서 position 기반으로 elements를 조회한다. + +``` +bop gbp \r\n +* = asc | desc +``` + +- \ - 대상 item의 key string +- \ - 어떤 bkey 정렬 기준으로 position을 적용할 지를 명시 +- \ - 조회할 elements의 하나의 position 또는 position range. +Position range는 "position1..position2" 형식으로 표현. + +성공 시의 response string은 아래와 같다. +bop get 성공 시의 response string을 참조 바란다. + +``` +VALUE \r\n + [] \r\n + [] \r\n + [] \r\n +… +END\r\n +``` + +실패 시의 response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|------------------------------------------------------|------------------------ | +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | element miss +| "TYPE_MISMATCH" | b+tree collection 아님 +| "UNREADABLE" | 해당 item이 unreadable item임 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "SERVER_ERROR out of memory [writing get response]" | 메모리 부족 + +## bop pwg (B+Tree Find Position with Get [version 1.8.0]) + +B+tree collection에서 특정 bkey의 position을 조회하면서, +그 bkey를 가진 element를 포함하여 앞뒤에(양방향) 위치한 element N개 씩을 한번에 조회한다. + +``` +bop pwg []\r\n +* = asc | desc +``` + +- \ - 대상 item의 key string +- \ - 대상 element의 bkey +- \ - 어떤 bkey 정렬 기준으로 position을 얻을 것인지 명시 +- \ - 조회한 position의 앞뒤에서 각각 몇 개의 element를 조회할 것인지를 명시 (**최대 값은 100으로 제한**) + - 0이면, 조회한 position의 element만 조회 + - 양수이면, 조회한 position의 element 외에 그 position의 앞뒤에서 각각 그 수만큼 element 조회 + +성공 시의 response string은 아래와 같다. + +``` +VALUE \r\n + [] \r\n +... + [] \r\n +END\r\n +``` + +위의 VALUE 라인에서 각 값의 의미는 다음과 같다. +그 아래 라인들에서 element 값의 표현은 bop get 경우와 동일하다. + +- \ : 주어진 bkey의 position +- \ : b+tree item의 flags 속성값 +- \ : 조회한 전체 element 개수 +- \ : 전체 element list에서 주어진 bkey를 가진 element 위치 (0-based index) + - 주어진 bkey의 position과 element만 조회하면, count는 1이 되고, index는 0이 된다. + - 주어진 bkey의 position과 element 외에 양방향 10개 element 조회에서, + 그 position 앞에 5개 element가 존재하고 뒤에 10개 element가 존재한다면 + count는 (5 + 1 + 10) = 16이 되고, index는 5가 된다. + +실패 시의 response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------------------|-------------------------| +| "NOT_FOUND" | key miss +| "NOT_FOUND_ELEMENT" | element miss +| "TYPE_MISMATCH" | b+tree collection 아님 +| "BKEY_MISMATCH" | 명령 인자로 주어진 bkey 유형과 대상 b+tree의 bkey 유형이 다름 +| "UNREADABLE" | 해당 item이 unreadable item임 +| "NOT_SUPPORTED" | 지원하지 않음 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 +| "SERVER_ERROR out of memory [writing get response]" | 메모리 부족 diff --git a/documentation/ascii-protocol/ch09-command-pipelining.md b/documentation/ascii-protocol/ch09-command-pipelining.md new file mode 100644 index 000000000..3523b8e41 --- /dev/null +++ b/documentation/ascii-protocol/ch09-command-pipelining.md @@ -0,0 +1,70 @@ +# Chapter 9. Command Pipelining + +Command pipelining은 +“pipe” 키워드를 통해 여러 collection 명령들을 pipelining하여 cache server에 전달하고, +cache server는 각 명령을 처리한 즉시 그 response를 client로 전달하는 것이 아니라 +그 response를 reply queue에 보관해 두었다가, 마지막 명령 처리 후에 reply queue에 보관해 둔 전체 response를 +한번에 client로 전달하는 기능이다. +기존에 N 번의 request – response를 전달하던 것에 비해 +command pipelining은 한 번의 request stream과 한 번의 response stream을 전달할 수 있게 함으로써 +network 비용을 상당히 줄일 수 있으며, 전체 latency를 줄일 수 있는 장점을 가진다. + +Command pipelining은 현재 collection 명령들 중 일부에 한해서만 가능하다. +Command pipelining 가능한 명령은 아래와 같으며, 단순 response string을 가지는 명령만 이에 해당된다. +한번에 pipelining이 가능한 최대 명령의 수는 `500`개로 제한을 두고 있음을 주의하여야 한다. + +* lop 명령들 - lop insert/delete +* sop 명령들 - sop insert/delete/exist +* mop 명령들 - mop insert/delete/update +* bop 명령들 - bop insert/upsert/delete/update/incr/decr + +Command pipelining 수행 예로, +특정 list의 tail 쪽으로 10개 elements를 추가하고자 한다면, +아래와 같이 lop insert 명령을 연속하여 cache server로 보내면 된다. +첫 번째 명령부터 마지막 바로 이전 명령까지는 모두 “pipe” 인자를 사용하여 연결하여야 하고, +마지막 명령에서는 “pipe” 인자를 생략함으로써 pipelining의 끝임을 표현하여야 한다. + +``` + lop insert lkey -1 6 pipe\r\ndatum0\r\n + lop insert lkey -1 6 pipe\r\ndatum1\r\n + lop insert lkey -1 6 pipe\r\ndatum2\r\n + lop insert lkey -1 6 pipe\r\ndatum3\r\n + lop insert lkey -1 6 pipe\r\ndatum4\r\n + lop insert lkey -1 6 pipe\r\ndatum5\r\n + lop insert lkey -1 6 pipe\r\ndatum6\r\n + lop insert lkey -1 6 pipe\r\ndatum7\r\n + lop insert lkey -1 6 pipe\r\ndatum8\r\n + lop insert lkey -1 6\r\ndatum9\r\n +``` + +Command pipelining의 response string은 아래와 같다. + +``` +RESPONSE \r\n +\r\n +\r\n +... +\r\n +END|PIPE_ERROR \r\n +``` + +RESPONSE 라인에서 \는 전체 결과 수를 나타내고, +그 다음 라인들은 각 명령의 수행 결과를 차례로 나타낸다. +각 명령의 결과는 각 명령마다 다르므로 각 명령에 대한 설명을 참조하여야 한다. +마지막 라인은 pipelining 수행 상태를 나타내며, 아래 중의 하나를 가진다. + +- "END" - pipelining 연산이 정상 수행됨 +- “PIPE_ERROR command overflow” - pipelining 가능한 최대 commands 수인 500개를 초과하였다. + 이 경우, 500개까지의 command들만 하나의 command pipelining으로 처리되고 하나의 response stream으로 리턴된다. + 그 이후의 commands들은 처리되지 않는다. +- “PIPE_ERROR memory overflow” - ARCUS cache server 내부에서 pipelining 처리를 위한 + 메모리 공간이 부족한 상태를 의미한다. ARCUS cache server는 500개 commands의 result를 담아둘 공간을 + 미리 확보하여 수행하므로 이 오류가 발생할 가능성은 거의 없다. + 단, 의도하지 않은 이유에 의한 경우를 대비하여 이 오류를 추가해 둔 것이다. + 이 오류가 발생하면, 그 시점에 command pipelining을 중지하고 그 즉시 response stream을 client에 전달한다. + 이 경우의 response stream에는 가장 마지막에 수행된 command의 response string이 생략된다. + 그리고, 그 이후의 commands들은 처리되지 않는다. +- “PIPE_ERROR bad error” - pipelining 으로 어떤 command를 수행 중 + “CLIENT_ERROR”와 “SERVER_ERROR”로 시작하는 중요 오류가 발생한 경우이다. + 이 경우에도, 그 즉시 command pipelining을 중지하고 현재까지의 response stream을 client에 전달한다. + 그리고, 그 이후의 commands들은 처리되지 않는다. diff --git a/documentation/ascii-protocol/ch10-command-item-attribute.md b/documentation/ascii-protocol/ch10-command-item-attribute.md new file mode 100644 index 000000000..91da04e34 --- /dev/null +++ b/documentation/ascii-protocol/ch10-command-item-attribute.md @@ -0,0 +1,63 @@ +# Chapter 10. Item Attribute 명령 + +Item attributes를 조회하는 getattr 명령과 변경하는 setattr 명령을 소개한다. + +ARCUS에서 어떤 item attributes를 제공하는 지를 알고자 한다면, +[Item Attibute 설명](../ch03-item-attributes.md)을 참고 바란다. + + +## getattr (Item Attribute 조회) + +Item attributes를 조회하는 getattr 명령은 아래와 같다. + +``` +getattr [ ...]\r\n +``` + +- \ - 대상 item의 key string +- [\ ...] - 조회할 attribute name을 순차적으로 지정하는 것이며, + 이를 생략하면, item 유형에 따라 조회가능한 모든 attributes 값을 조회한다. + +성공 시의 response string은 아래와 같다. +getattr 명령의 인자로 지정한 attribute name 순서대로 name과 value의 쌍을 리턴한다. + +``` +ATTR =\r\n +ATTR =\r\n +... +END\r\n +``` + +실패 시의 response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------|------------------------ | +| "NOT_FOUND" | key miss +| "ATTR_ERROR not found" | 인자로 지정한 attribute가 존재하지 않거나 해당 item 유형에서 지원되지 않는 attribute임. +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 + + +## setattr (Item Attribute 변경) + +Item attributes를 변경하는 setattr 명령은 아래와 같다. +모든 attributes에 대해 조회가 가능하지만, 변경은 일부 attributes에 대해서만 가능하다. +변경가능한 attributes로는 expiretime, maxcount, overflowaction, readable, maxbkeyrange가 있다. + +``` +setattr = [= ...]\r\n +``` + +- \ - 대상 item의 key string +- \=\ - 변경할 attribute의 name과 value 쌍을 하나 이상 명시하여야 한다. + +이 명령의 response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------|------------------------ | +| "OK" | 성공 +| "NOT_FOUND" | key miss +| "ATTR_ERROR not found" | 인자로 지정한 attribute가 존재하지 않거나 해당 item 유형에서 지원되지 않는 attribute임. +| "ATTR_ERROR bad value" | 해당 attribute에 대해 새로 변경하고자 하는 value가 allowed value가 아님. +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 + + diff --git a/documentation/ascii-protocol/ch11-command-scan.md b/documentation/ascii-protocol/ch11-command-scan.md new file mode 100644 index 000000000..adb5867f7 --- /dev/null +++ b/documentation/ascii-protocol/ch11-command-scan.md @@ -0,0 +1,151 @@ +# Chapter 11. Scan 명령 + +- [SCAN KEY 명령](#scan-key-명령) +- [SCAN PREFIX 명령](#scan-prefix-명령) + +## Scan key 명령 + +특정 조건을 만족하는 아이템들의 키 목록을 얻어올 수 있는 scan key 기능을 제공한다. +scan key 기능은 제한된 시간(5ms) 내에서 아이템들을 스캔하고 응용에게 찾은 키 스트링 목록과 +다음 스캔할 위치를 응답해준다. 응용은 응답 받은 위치를 다시 주어 scan key 를 반복 호출하는 +iteration 방식으로 전체 아이템을 스캔한다. +scan key 명령 요청 syntax는 아래와 같다. + +``` +scan key [count ] [match ] [type ]\r\n +``` + +- \ - 스캔 시작 위치. +처음부터 스캔한다면 0을, 이전 스캔이 끝난 다음 지점부터 이어서 한다면 이전 스캔에서 응답 받은 cursor 값을 그대로 지정한다. +- \ - 스캔할 아이템 개수. 1~2000 범위에서 지정할 수 있고, 지정하지 않을 시 20 으로 설정된다. +지정한 수만큼의 아이템들을 스캔하여 그 중 조건(type, pattern)과 일치하는 아이템들의 키 목록을 응답한다. +응답한 키 목록의 개수는 scan key 내부 구현 로직 상 count 보다 적거나 많을 수 있다. +count 보다 적은 경우는 조건과 불일치한 아이템이 존재하거나 long query 방지를 위해 scan key 수행시간이 제한시간을 초과하여 수행을 종료한 경우이다. +count 보다 많은 경우는 스캔 동작이 해시테이블의 버켓 단위로 수행하기 때문에 하나의 버켓에 대해 스캔을 시작하면 마지막 지점까지 스캔을 완료하므로 count 보다 많은 수의 아이템을 스캔할 수 있다. +이렇게 설계한 이유는 버켓 중간에서 스캔을 중지할 경우 다음 스캔 요청이 들어올 때까지 그 버켓의 상태가 변경되지 않게 유지해야 하는 +복잡성을 제거하여 stateless한 scan key api를 제공하기 위함이다. +- \ - 키 문자열 패턴. 최대 문자열 길이: 64, 최대 '\*' 입력 개수: 4 . 지정하지 않을 시 모든 키 문자열을 조회한다. +glob style 패턴 문자열을 지정하여 해당 패턴과 일치하는 키 문자열을 갖는 아이템들을 찾는다. glob 문자는 '\*', '\?', '\\' 을 지원한다. +문자열 비교 알고리즘의 worst case 수행 시간이 오래 걸리는 것을 방지하기 위해 패턴 문자열에 길이와 '\*' 입력 개수에 제약을 두었다. +- \ - 아이템 타입. 각 타입별 지정 값은 다음과 같다. 지정하지 않을 시 'A' 로 설정된다. +All type : 'A', KV : 'K', List : 'L', Set : 'S', Map : 'M', Btree : 'B' + +scan key 명령 응답 syntax는 아래와 같다. + +``` +KEYS \r\n +key1 \r\n +key2 \r\n +key3 \r\n +... +``` + +첫 번째 줄에는 KEYS 로 시작하는 응답 문자열이 나온다. +\는 조건과 일치한 아이템 개수로 두 번째 줄부터 키 문자열이 \ 개 만큼 나온다. +\는 스캔할 다음 지점으로 이어서 스캔할 경우 이 값을 그대로 주어 scan key 호출하면 된다. +이 값이 0 이 나오면 전체 아이템을 스캔 완료했음을 나타낸다. 따라서 응용은 0이 나올때까지 반복 호출하면 된다. + +두 번째 줄부터 scan된 key 목록이 나온다. +\ - 아이템 타입. 각 타입별 지정 값은 다음과 같다. +KV : 'K', List : 'L', Set : 'S', Map : 'M', Btree : 'B' +\은 아이템 만료 시간을 나타낸다. + +scan key 사용 예시이다. +1000개의 아이템을 스캔하여 그 중 KV 타입이고, \*key1\* 패턴과 일치하는 키 목록을 조회한다. +``` +scan key 0 count 1000 match *key1* type K +``` + +5개의 키가 조회되었고, 다음 스캔 지점 cursor 값은 8000이다. +0이 아니므로 전체 아이템을 스캔하지 못했음을 의미한다. 0이 나올때까지 응답받은 cursor 를 주어 scan key 를 반복 호출하면 된다. +``` +KEYS 5 8000\r\n +akey12 K 0\r\n +bkey13 K 10\r\n +ccckey14 K 0\r\n +cckey16 K 0\r\n +keykey13 K 3600\r\n +``` + +scan key 명령 실패 시에 response string 은 다음과 같다. + +| Response String | 설명 | +|----------------------------------------|------------------------ | +| CLIENT_ERROR bad cursor value | cursor 문자열 길이가 32 이상인 경우 +| CLIENT_ERROR bad count value | count 가 0 이거나 2000 보다 큰 경우 +| CLIENT_ERROR bad pattern string | 패턴 문자열 길이가 65 이상이거나 패턴 문자열에 * 을 5개 이상 주었거나 '\\' 다음에 패턴 문자('\\', '\*', '\?')가 없는 경우 +| CLIENT_ERROR bad item type | type 값을 잘못 준 경우 +| CLIENT_ERROR invalid cursor | cursor 에 숫자가 아닌 값을 준 경우 +| CLIENT_ERROR bad command line format | protocol syntax 틀림 + +## Scan prefix 명령 + +특정 조건을 만족하는 Prefix 목록을 얻어올 수 있는 scan prefix 기능을 제공한다. +scan prefix 기능은 제한된 시간(5ms) 내에서 Prefix들을 스캔하고 응용에게 찾은 Prefix 목록과 +다음 스캔할 위치를 응답해준다. 응용은 응답 받은 위치를 다시 주어 scan prefix 를 반복 호출하는 +iteration 방식으로 전체 Prefix를 스캔한다. +scan prefix 명령 요청 syntax는 아래와 같다. + +``` +scan prefix [count ] [match ]\r\n +``` + +- \ - 스캔 시작 위치. +처음부터 스캔한다면 0을, 이전 스캔이 끝난 다음 지점부터 이어서 한다면 이전 스캔에서 응답 받은 cursor 값을 그대로 지정한다. +- \ - 스캔할 Prefix 개수. 1~2000 범위에서 지정할 수 있고, 지정하지 않을 시 20 으로 설정된다. +지정한 수만큼의 Prefix들을 스캔하여 그 중 조건(pattern)과 일치하는 Prefix 목록을 응답한다. +응답한 Prefix 목록의 개수는 scan prefix 내부 구현 로직 상 count 보다 적거나 많을 수 있다. +count 보다 적은 경우는 조건과 불일치한 Prefix가 존재하거나 long query 방지를 위해 scan prefix 수행시간이 제한시간을 초과하여 수행을 종료한 경우이다. +count 보다 많은 경우는 스캔 동작이 해시테이블의 버켓 단위로 수행하기 때문에 하나의 버켓에 대해 스캔을 시작하면 마지막 지점까지 스캔을 완료하므로 count 보다 많은 수의 Prefix를 스캔할 수 있다. +이렇게 설계한 이유는 버켓 중간에서 스캔을 중지할 경우 다음 스캔 요청이 들어올 때까지 그 버켓의 상태가 변경되지 않게 유지해야 하는 +복잡성을 제거하여 stateless한 scan prefix api를 제공하기 위함이다. +- \ - 키 문자열 패턴. 최대 문자열 길이: 64, 최대 '\*' 입력 개수: 4 . 지정하지 않을 시 모든 키 문자열을 조회한다. +glob style 패턴 문자열을 지정하여 해당 패턴과 일치하는 키 문자열을 갖는 Prefix들을 찾는다. glob 문자는 '\*', '\?', '\\' 을 지원한다. +문자열 비교 알고리즘의 worst case 수행 시간이 오래 걸리는 것을 방지하기 위해 패턴 문자열에 길이와 '\*' 입력 개수에 제약을 두었다. + +scan prefix 명령 응답 syntax는 아래와 같다. + +``` +PREFIXES \r\n +prefix1 \r\n +prefix2 \r\n +prefix3 \r\n +... +``` + +첫 번째 줄에는 PREFIXES 로 시작하는 응답 문자열이 나온다. +\는 조건과 일치한 Prefix 개수로 두 번째 줄부터 Prefix 문자열이 \ 개 만큼 나온다. +\는 스캔할 다음 지점으로 이어서 스캔할 경우 이 값을 그대로 주어 scan prefix 호출하면 된다. +이 값이 0 이 나오면 전체 Prefix를 스캔 완료했음을 나타낸다. 따라서 응용은 0이 나올때까지 반복 호출하면 된다. + +두 번째 줄부터 scan된 prefix 목록이 나온다. +\는 해당 prefix의 아이템 개수를 나타낸다. +\는 해당 prefix의 아이템들이 차지하는 메모리 용량을 byte 단위로 나타낸다. +\은 해당 prefix가 생성된 시간을 나타낸다. + +scan prefix 사용 예시이다. +1000개의 Prefix를 스캔하여 그 중 \*prefix1\* 패턴과 일치하는 Prefix 목록을 조회한다. +``` +scan prefix 0 count 1000 match *prefix1* +``` + +5개의 키가 조회되었고, 다음 스캔 지점 cursor 값은 8이다. +0이 아니므로 전체 Prefix를 스캔하지 못했음을 의미한다. 0이 나올때까지 응답받은 cursor 를 주어 scan prefix 를 반복 호출하면 된다. +``` +PREFIXES 5 8\r\n +aprefix12 1 96 20220621095219\r\n +bprefix13 12 2016 20220621095219\r\n +cccprefix14 25 2704 20220621095219\r\n +ccprefix16 2 256 20220621095219\r\n +prefixprefix13 3 288 20220621095219\r\n +``` + +scan prefix 명령 실패 시에 response string 은 다음과 같다. + +| Response String | 설명 | +|----------------------------------------|------------------------ | +| CLIENT_ERROR bad cursor value | cursor 문자열 길이가 32 이상인 경우 +| CLIENT_ERROR bad count value | count 가 0 이거나 2000 보다 큰 경우 +| CLIENT_ERROR bad pattern string | 패턴 문자열 길이가 65 이상이거나 패턴 문자열에 * 을 5개 이상 주었거나 '\\' 다음에 패턴 문자('\\', '\*', '\?')가 없는 경우 +| CLIENT_ERROR invalid cursor | cursor 에 숫자가 아닌 값을 준 경우 +| CLIENT_ERROR bad command line format | protocol syntax 틀림 diff --git a/documentation/ascii-protocol/ch12-command-administration.md b/documentation/ascii-protocol/ch12-command-administration.md new file mode 100644 index 000000000..aa460cc3d --- /dev/null +++ b/documentation/ascii-protocol/ch12-command-administration.md @@ -0,0 +1,1023 @@ +# Chapter 12. Admin & Monitoring 명령 + +- [FLUSH 명령](#flush-명령) +- [SCRUB 명령](#scrub-명령) +- [STATS 명령](#stats-명령) +- [CONFIG 명령](#config-명령) +- [CMDLOG 명령](#command-logging-명령) +- [LQDETECT 명령](#long-query-detect-명령) +- [KEY DUMP 명령](#key-dump-명령) +- [ZKENSEMBLE 명령](#zkensemble-명령) +- [HELP 명령](#help-명령) + +## Flush 명령 + +ARCUS Cache Server는 items을 invalidate 시키기 위한 두 가지 flush 명령을 제공한다. + +- flush_all : 모든 items을 flush +- flush_prefix: 특정 prefix의 items들만 flush + +Flush 작업은 items을 invalidate시키더라도 그 items이 차지한 메모리 공간을 즉각 반환하지 않는다. +대신, ARCUS Cache Server의 global 정보로 flush 수행 시점 정보를 기록해 둠으로써, +그 시점 이전에 존재했던 items은 invalidated items이라는 것을 알 수 있게 한다. +따라서, item 접근할 때마다 invalidated item인지를 확인하여야 하는 부담이 있지만, +flush 작업 자체는 O(1) 시간에 그 수행이 완료된다. + +flush_all 명령은 flush 수행 시점 정보만 기록해 두고, 전체 prefix들의 통계 정보는 그대로 남겨 둔다. +따라서, flush_all을 수행하더라도 prefix 관련한 통계 정보를 조회할 수 있다. +해당 prefix에 속한 items이 모두 제거되는 시점에, 그 prefix의 통계 정보는 함께 제거된다. +반면, flush_prefix 명령은 해당 prefix에 대한 flush 수행 시점 정보를 기록해 두면서, +그 prefix의 통계 정보를 모두 reset시켜 제거한다는 것이 차이가 있다. +따라서, flush_prefix 수행 이후에는 해당 prefix에 대한 통계 정보를 조회할 수 없게 된다. + +두 flush 명령의 syntax는 아래와 같다. + +``` +flush_all [] [noreply]\r\n +flush_prefix [] [noreply]\r\n +``` + +- \ - prefix string. "\"을 사용하면, prefix string이 없는 item들을 invalidate시킨다. +- \ - 지연된 invalidation 요청 시에 명시하며, 그 지연 기간을 초(second) 단위로 지정한다. +- noreply - 명시하면, response string이 생략된다. + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------|------------------------ | +| "OK" | 성공 +| "NOT_FOUND" | prefix miss (flush_prefix 명령인 경우만 해당) +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 + +## Scrub 명령 + +ARCUS Cache Server에는 유효하지 않으면서 메모리를 차지하고 있는 items이 존재할 수 있다. +이 items은 아래 두 유형으로 구분된다. + +- ARCUS Cache Server에서 어떤 items이 expired되더라도 그 items은 즉각 제거되지 않으며, + flush 명령으로 어떤 items을 invalidate시키더라도 그 items은 즉각 제거되지 않는다. + 이들 items은 ARCUS Cache Server 내부에 메모리를 차지하면서 계속 존재하고 있다. + 어떤 이유이든 이 items에 대한 접근이 발생할 때 + ARCUS Cache Server는 expired/flushed 상태임을 알게 되며, + 그 items을 제거함으로써 그 items이 차지한 메모리를 반환한다. +- Cache cloud를 형성하고 consistent hashing의 key-to-node mapping을 사용하는 환경에서, + 그 cache cloud에 특정 node의 추가나 삭제에 의해 key-to-node remapping이 발생하게 된다. + 이러한 key-to-node remapping이 발생하면, 어떤 node에 있던 기존 items은 더 이상 사용되지 않게 된다. + 이러한 items을 stale items이라 한다. 이러한 stale items은 자연스럽게 expired 되기도 하지만, + old data를 가지고 남아 있다가 그 이후의 key-to-node remapping에 의해 + 유효한 items으로 다시 전환될 여지가 있다. + 따라서, 이러한 stale items은 cache cloud의 node list가 변경될 때마다 제거하여야 한다. + +Scrub 기능이란 (1) expired item, flushed item과 같은 invalidated item들을 명시적으로 제거하는 기능과 +(2) cache cloud에서 key-to-node remapping으로 발생한 stale items들을 명시적으로 제거하는 기능을 의미한다. + +이러한 scrub 기능은 daemon thread에 의해 background 작업으로 수행되며, +한 순간에 하나의 scrub 작업만 수행될 수 있다. +즉, scrub 작업이 진행 중인 상태에서 새로운 scrub 작업을 요청할 수 없다. + +``` +scrub [stale]\r\n +``` + +- stale - 명시하지 않으면 invalidated item을 제거하고, 명시하면 stale item을 제거한다. + +Response string과 그 의미는 아래와 같다. + +| Response String | 설명 | +|-----------------------------------------|------------------------ | +| "OK" | 성공 +| "BUSY" | 현재 scrub 작업이 수행 중이어서 새로운 scrub 작업을 요청할 수 없음 +| "NOT_SUPPORTED" | 지원되지 않는 scrub 명령 +| "CLIENT_ERROR bad command line format" | protocol syntax 틀림 + +참고 사항으로, scrub 명령은 ASCII 명령의 extension 기능으로 구현되었기에, +ARCUS Cache Server 구동 시에 ascii_scrub.so 파일을 dynamic linking 하는 +구동 옵션을 주어야 scrub 명령을 사용할 수 있다. + + +## Stats 명령 + +ARCUS Cache Server의 각종 통계 정보를 조회하거나 그 통계 정보를 reset한다. + +``` +stats []\r\n +``` + +\를 생략하거나, 어떤 값을 주느냐에 따라 stats 명령의 동작은 아래와 같이 달라진다. + +``` + | stats 명령의 동작 + ------------------ | ------------------------------------------- + | General purpose 통계 정보 조회 + settings | Configuration 정보 조회 + items | Item 통계 정보 조회 + slabs | Slab 통계 정보 조회 + prefixes | Prefix 별 item 통계 정보 조회 + detail on|off|dump | Prefix 별 수행 명령 통계 정보 조회 및 제어 + zookeeper | Zookeeper 정보 조회 + scrub | scrub 수행 상태 조회 + cachedump | slab class 별 cache key dump + reset | 모든 통계 정보를 reset + persistence | Persistence 정보 조회 +``` + +stats 명령은 직접 한번씩 수행해 보기를 권하며, 아래에서는 추가 설명이 필요한 부분들만 기술한다. + +### General purpose 정보 + +특정 분류에 국한되지 않은 일반적인 통계를 알기 위한 명령이다. 다음은 stats 명령 결과의 예이다. + +``` +STAT pid 3553 +STAT uptime 6910 +STAT time 1584942539 +STAT version 1.11.7 +STAT libevent 2.1.11-stable +STAT pointer_size 64 +STAT rusage_user 1.241010 +STAT rusage_system 2.843840 +STAT daemon_connections 2 +STAT curr_connections 1 +STAT quit_connections 0 +STAT reject_connections 0 +STAT total_connections 3 +STAT connection_structures 3 +STAT cmd_get 0 +STAT cmd_set 0 +STAT cmd_incr 0 +STAT cmd_decr 0 +STAT cmd_delete 0 +STAT cmd_flush 0 +STAT cmd_flush_prefix 0 +STAT cmd_cas 0 +STAT cmd_lop_create 0 +STAT cmd_lop_insert 0 +STAT cmd_lop_delete 0 +STAT cmd_lop_get 0 +STAT cmd_sop_create 0 +STAT cmd_sop_insert 0 +STAT cmd_sop_delete 0 +STAT cmd_sop_get 0 +STAT cmd_sop_exist 0 +STAT cmd_mop_create 0 +STAT cmd_mop_insert 0 +STAT cmd_mop_update 0 +STAT cmd_mop_delete 0 +STAT cmd_mop_get 0 +STAT cmd_bop_create 0 +STAT cmd_bop_insert 0 +STAT cmd_bop_update 0 +STAT cmd_bop_delete 0 +STAT cmd_bop_get 0 +STAT cmd_bop_count 0 +STAT cmd_bop_position 0 +STAT cmd_bop_pwg 0 +STAT cmd_bop_gbp 0 +STAT cmd_bop_mget 0 +STAT cmd_bop_smget 0 +STAT cmd_bop_incr 0 +STAT cmd_bop_decr 0 +STAT cmd_getattr 0 +STAT cmd_setattr 0 +STAT auth_cmds 0 +STAT auth_errors 0 +STAT get_hits 0 +STAT get_misses 0 +STAT delete_misses 0 +STAT delete_hits 0 +STAT incr_misses 0 +STAT incr_hits 0 +STAT decr_misses 0 +STAT decr_hits 0 +STAT cas_misses 0 +STAT cas_hits 0 +STAT cas_badval 0 +STAT lop_create_oks 0 +STAT lop_insert_misses 0 +STAT lop_insert_hits 0 +STAT lop_delete_misses 0 +STAT lop_delete_elem_hits 0 +STAT lop_delete_none_hits 0 +STAT lop_get_misses 0 +STAT lop_get_elem_hits 0 +STAT lop_get_none_hits 0 +STAT sop_create_oks 0 +STAT sop_insert_misses 0 +STAT sop_insert_hits 0 +STAT sop_delete_misses 0 +STAT sop_delete_elem_hits 0 +STAT sop_delete_none_hits 0 +STAT sop_get_misses 0 +STAT sop_get_elem_hits 0 +STAT sop_get_none_hits 0 +STAT sop_exist_misses 0 +STAT sop_exist_hits 0 +STAT mop_create_oks 0 +STAT mop_insert_misses 0 +STAT mop_insert_hits 0 +STAT mop_update_misses 0 +STAT mop_update_elem_hits 0 +STAT mop_update_none_hits 0 +STAT mop_delete_misses 0 +STAT mop_delete_elem_hits 0 +STAT mop_delete_none_hits 0 +STAT mop_get_misses 0 +STAT mop_get_elem_hits 0 +STAT mop_get_none_hits 0 +STAT bop_create_oks 0 +STAT bop_insert_misses 0 +STAT bop_insert_hits 0 +STAT bop_update_misses 0 +STAT bop_update_elem_hits 0 +STAT bop_update_none_hits 0 +STAT bop_delete_misses 0 +STAT bop_delete_elem_hits 0 +STAT bop_delete_none_hits 0 +STAT bop_get_misses 0 +STAT bop_get_elem_hits 0 +STAT bop_get_none_hits 0 +STAT bop_count_misses 0 +STAT bop_count_hits 0 +STAT bop_position_misses 0 +STAT bop_position_elem_hits 0 +STAT bop_position_none_hits 0 +STAT bop_pwg_misses 0 +STAT bop_pwg_elem_hits 0 +STAT bop_pwg_none_hits 0 +STAT bop_gbp_misses 0 +STAT bop_gbp_elem_hits 0 +STAT bop_gbp_none_hits 0 +STAT bop_mget_oks 0 +STAT bop_smget_oks 0 +STAT bop_incr_elem_hits 0 +STAT bop_incr_none_hits 0 +STAT bop_incr_misses 0 +STAT bop_decr_elem_hits 0 +STAT bop_decr_none_hits 0 +STAT bop_decr_misses 0 +STAT getattr_misses 0 +STAT getattr_hits 0 +STAT setattr_misses 0 +STAT setattr_hits 0 +STAT stat_prefixes 0 +STAT bytes_read 23 +STAT bytes_written 771 +STAT limit_maxbytes 8589934592 +STAT threads 6 +STAT conn_yields 0 +STAT curr_prefixes 0 +STAT reclaimed 0 +STAT evictions 0 +STAT outofmemorys 0 +STAT sticky_items 0 +STAT curr_items 0 +STAT total_items 0 +STAT sticky_bytes 0 +STAT bytes 0 +STAT sticky_limit 0 +STAT engine_maxbytes 8589934592 +END +``` + +명령 별 주요 통계를 정리하면 다음과 같다. + +- cmd_\: 해당 명령의 수행 횟수 +- \_hits: 해당 명령의 key hit 횟수 +- \_misses: 해당 명령의 key miss 횟수 +- 콜렉션 명령의 key hit 횟수는 따로 제공하지 않으며, 아래 횟수의 합으로 계산할 수 있다. + - \_\_elem_hits: 콜렉션 명령의 key hit 그리고 element hit 횟수 + - \_\_none_hits: 콜렉션 명령의 key hit 그러나 element miss 횟수 + +다음은 그 외의 개별 통계이다. + +| stats | 설명 | +| --------------------- | ------------------------------------------------------------ | +| pid | 캐시 노드의 프로세스 id | +| uptime | 캐시 서버를 구동한 시간(초) | +| time | 현재 시간 (unix time) | +| version | 현재 arcus-memcached 버전 | +| libevent | 사용중인 libevent 버전 | +| pointer_size | 포인터의 크기(bit 단위) | +| rusage_user | 프로세스의 누적 user time. | +| rusage_system | 프로세스의 누적 system time. | +| daemon_connections | 서버가 사용하는 daemon connection 개수 | +| curr_connections | 현재 열려있는 connection 개수 | +| quit_connections | 클라이언트가 quit 명령을 이용해 연결을 끊은 횟수 | +| reject_connections | 클라이언트와의 연결을 거절한 횟수 | +| total_connections | 서버 구동 이후 누적 connection 총합 | +| connection_structures | 서버가 할당한 connection 구조체 개수 | +| auth_cmds | sasl 인증 횟수 | +| auth_errors | sasl 인증 실패 횟수 | +| cas_badval | 키는 찾았으나 cas 값이 맞지 않은 요청의 횟수 | +| bytes_read | 서버가 네트워크에서 읽은 데이터 용량 총합(bytes) | +| bytes_written | 서버가 네트워크에 쓴 데이터 용량 총합(bytes) | +| limit_maxbytes | 서버에 허용된 최대 메모리 용량(bytes) | +| threads | worker thread 개수 | +| conn_yields | 이벤트당 최대 요청 수의 제한 | +| curr_prefixes | 현재 저장된 prefix 개수 | +| reclaimed | expired된 아이템의 공간을 사용해 새로운 아이템을 저장한 횟수 | +| evictions | eviction 횟수 | +| outofmemorys | outofmemory (메모리가 부족한 상황에서 eviction이 허용되지 않거나 실패) 발생 횟수 | +| sticky_items | 현재 sticky 아이템의 개수 | +| curr_items | 현재 서버에 저장된 아이템의 개수 | +| total_items | 서버 구동 후 저장한 아이템의 누적 개수 | +| sticky_bytes | sticky 아이템이 차지하는 메모리 용량(bytes) | +| bytes | 현재 사용중인 메모리 용량(bytes) | +| sticky_limit | sticky item을 저장할 수 있는 최대 메모리 용량(bytes) | +| engine_maxbytes | 엔진에 허용된 최대 저장 용량 | + +### Settings 통계 정보 + +각종 설정값에 대한 통계 정보를 보는 명령이다. 다음은 stats settings 실행 결과의 예이다. + +``` +STAT maxbytes 8589934592 +STAT maxconns 3000 +STAT tcpport 11911 +STAT udpport 0 +STAT sticky_limit 0 +STAT inter NULL +STAT verbosity 1 +STAT oldest 0 +STAT evictions on +STAT domain_socket NULL +STAT umask 700 +STAT growth_factor 1.25 +STAT chunk_size 48 +STAT num_threads 6 +STAT stat_key_prefix : +STAT detail_enabled yes +STAT allow_detailed yes +STAT reqs_per_event 5 +STAT cas_enabled yes +STAT tcp_backlog 8192 +STAT binding_protocol auto-negotiate +STAT auth_enabled_sasl no +STAT auth_sasl_engine none +STAT auth_required_sasl no +STAT item_size_max 1048576 +STAT max_list_size 50000 +STAT max_set_size 50000 +STAT max_map_size 50000 +STAT max_btree_size 50000 +STAT max_element_bytes 16384 +STAT scrub_count 96 +STAT topkeys 0 +STAT logger syslog +STAT ascii_extension scrub +END +``` + +| stats | 설명 | +| ------------------ | ------------------------------------------------------------ | +| maxbytes | 캐시 서버의 최대 저장 용량(byte) | +| maxconns | 접속할 수 있는 클라이언트의 최대 개수 | +| tcpport | listen하고 있는 TCP port | +| udpport | listen하고 있는 UDP port | +| sticky_limit | sticky 아이템을 저장할 수 있는 최대 공간의 크기(bytes) | +| inter | listen interface | +| verbosity | 현재 verbosity 레벨(0~3) | +| oldest | 가장 오래된 아이템이 저장되고 지난 시간 | +| evictions | eviction의 허용 여부 | +| domain_socket | domain socket의 경로 | +| umask | domain socket의 umask | +| growth_factor | slab class의 chunk 크기 증가 팩터 | +| chunk_size | 아이템을 저장하기 위해 할당하는 최소의 공간(key + value + flags)의 크기(bytes) | +| stat_key_prefix | prefix와 key를 구분하는 문자 | +| detail_enabled | detailed stat(prefix별 통계) 수집 여부 | +| allow_detailed | stat detail 명령 허용 여부 | +| reqs_per_event | io 이벤트에서 처리할 수 있는 최대 io 연산 수 | +| cas_enabled | cas 연산 허용 여부 | +| tcp_backlog | tcp의 backlog 큐 크기 | +| binding_protocol | 사용중인 프로토콜. ASCII, binary, auto(negotiating) 세 가지임 | +| auth_enabled_sasl | sasl 인증 사용 여부 | +| auth_sasl_engine | sasl 인증에 사용할 엔진 | +| auth_required_sasl | sasl 인증 필수 여부 | +| item_size_max | 아이템의 최대 사이즈 | +| max_list_size | list collection의 최대 element 갯수 | +| max_set_size | set collection의 최대 element 갯수 | +| max_map_size | map collection의 최대 element 갯수 | +| max_btree_size | btree collection의 최대 element 갯수 | +| max_element_bytes | collection element 데이터의 최대 크기 | +| topkeys | 추적하고 있는 topkey 개수 | +| logger | 사용 중인 logger extension | +| ascii_extension | 사용 중인 ASCII protocol extension | + +### Items 통계 정보 + +item에 대한 slab class 별 통계 정보를 조회하는 명령이다. 다음은 stats items 실행 결과의 예이다. + +``` +STAT items:0:number 2000002 +STAT items:0:sticky 0 +STAT items:0:age 5401 +STAT items:0:evicted 0 +STAT items:0:evicted_nonzero 0 +STAT items:0:evicted_time 0 +STAT items:0:outofmemory 0 +STAT items:0:tailrepairs 0 +STAT items:0:reclaimed 0 +END +``` + +'items:' 옆에 표기된 숫자가 slab class id이다. 통계 정보의 의미는 다음과 같다. + +| stats | 설명 | +| --------------- | ------------------------------------------------------------ | +| number | 해당 클래스에 저장된 아이템의 개수 | +| sticky | sticky로 설정된 아이템의 개수. [basic concept 문서](../ch01-arcus-basic-concept.md#expiration-eviction-and-sticky) 참조 | +| age | LRU 체인에서 가장 오래된 아이템이 생성되고 나서 지난 시간(초) | +| evicted | evict된 아이템의 개수 | +| evicted_nonzero | evict된 아이템 중, expired time이 명시적인 양수 값으로 설정되어 있던 아이템의 개수 | +| evicted_time | 가장 최근에 evict된 아이템에 마지막으로 접근하고 나서 지난 시간(초) | +| out_of_memory | 메모리 부족으로 아이템을 저장하는데 실패한 횟수 | +| tailrepairs | slab allocator를 refcount leak에서 복구한 횟수 | +| reclaimed | expired된 아이템의 공간을 사용해 새로운 아이템을 저장한 횟수 | + +### Slabs 통계 정보 + +각 slab 클래스의 통계 정보와 전체 클래스에 대한 메타 정보를 조회하는 명령이다. 다음은 stats slabs 실행 결과의 예이다. + +``` +STAT SM:free_min_classid 709 +STAT SM:free_max_classid -1 +STAT SM:used_total_space 472 +STAT SM:used_01pct_space 288 +STAT SM:free_small_space 0 +STAT SM:free_bslot_space 261640 +STAT SM:free_avail_space 261640 +STAT SM:free_chunk_space 0 +STAT SM:free_limit_space 0 +STAT SM:space_shortage_level 0 +STAT 0:chunk_size 262144 +STAT 0:chunks_per_page 4 +STAT 0:reserved_pages 0 +STAT 0:total_pages 1 +STAT 0:total_chunks 4 +STAT 0:used_chunks 1 +STAT 0:free_chunks 0 +STAT 0:free_chunks_end 3 +STAT 0:mem_requested 262144 +STAT active_slabs 1 +STAT memory_limit 8589934592 +STAT total_malloced 1048576 +END +``` + +콜론(:)앞의 문자는 slab 클래스 번호를 의미한다. 'SM'이라고 표기된 클래스는 작은 크기의 데이터를 관리하는 small manager 클래스이다. + +일반 클래스의 통계 정보가 뜻하는 의미는 다음과 같다. + +| stats | 설명 | +| --------------- | ------------------------------------------------------------ | +| chunk_size | 각 chunk가 사용하는 메모리 공간들의 크기 합(bytes) | +| chunks_per_page | 페이지 당 chunk의 개수 | +| reserved_pages | 해당 클래스에 할당하기 위해 예약된 페이지 수 | +| total_pages | 해당 클래스에 할당된 페이지의 개수 | +| total_chunks | 해당 클래스에 할당된 청크의 개수 | +| used_chunks | 이미 아이템에게 할당된 chunk의 개수 | +| free_chunks | 아직 할당되지 않았거나 삭제 연산으로 인해 free된 chunk의 개수 | +| free_chunks_end | 마지막으로 할당된 페이지 끝에 남아있는 chunk 개수 | +| mem_requested | 해당 클래스에 요청된 메모리 공간의 크기 합(bytes) | + + small manager 클래스의 통계 정보가 뜻하는 의미는 다음과 같다. + +| stats | 설명 | +| -------------------- | ------------------------------------------------------------ | +| free_min_classid | free slot의 id 중 최소값 | +| free_max_classid | free slot의 id 중 최대값(마지막 슬롯인 big free slot의 id는 제외) | +| used_total_space | 사용중인 공간의 크기 합(bytes) | +| used_01pct_space | 크기가 상위 1퍼센트에 속하는 슬롯들이 사용하는 공간의 크기 합(bytes) | +| free_small_space | 할당되지 않았고, 할당될 가능성이 낮은 작은 메모리 공간의 크기 합(bytes) | +| free_bslot_space | big free slot의 남은 공간의 크기 합(bytes) | +| free_avail_space | 할당되지 않았고, 할당될 가능성이 높은 큰 메모리 공간의 크기 합(bytes) | +| free_chunk_space | 메모리 블락(chunk)를 할당할 수 있는 공간의 크기 합(bytes) | +| free_limit_space | 항상 비운 채로 유지되어야 하는 최소한의 여유 공간의 크기 합(bytes) | +| space_shortage_level | 공간이 부족한 정도를 0~100 으로 수치화한 레벨. | + +space_shortage_level이 10 이상으로 올라가면, background에서 아이템을 evict 하는 별도의 쓰레드를 실행해 메모리 공간을 확보한다. LRU 체인의 끝부터 space_shortage_level 만큼 아이템을 삭제하게 된다. (ssl이 10이라면 10개의 아이템 삭제) + +기타 메타 통계를 정리하면 다음과 같다. + +| stats | 설명 | +| -------------- | ----------------------------------------------- | +| active_slabs | 할당된 slab class의 총 개수 | +| memory_limit | 캐시 서버의 최대 용량(bytes) | +| total_malloced | slab page에 할당된 메모리 공간의 크기 합(bytes) | + +### Prefix 통계 정보 + +모든 prefix들의 item 통계 정보는 "stats prefixes" 명령으로 조회하고, +모든 prefix들의 연산 통계 정보는 "stats detail dump" 명령으로 조회한다. +그리고, Prefix들의 연산 통계 정보에 한해, +통계 정보의 수집 여부를 on 또는 off 할 수 있다. + +모든 prefix들의 item 통계 정보의 결과 예는 아래와 같다. +\ prefix 통계는 prefix를 가지지 않는 items 통계이다. + +``` +PREFIX itm 2 kitm 1 litm 1 sitm 0 mitm 0 bitm 0 tsz 144 ktsz 64 ltsz 80 stsz 0 mtsz 0 btsz 0 time 20121105152422 +PREFIX a itm 5 kitm 5 litm 0 sitm 0 mitm 0 bitm 0 tsz 376 ktsz 376 ltsz 0 stsz 0 mtsz 0 btsz 0 time 20121105152422 +PREFIX b itm 2 kitm 2 litm 0 sitm 0 mitm 0 bitm 0 tsz 144 ktsz 144 ltsz 0 stsz 0 mtsz 0 btsz 0 time 20121105152422 +END +``` + +각 prefix의 item 통계 정보에 +itm은 전체 item 수이고, kitm, litm, sitm, mitm, bitm은 각각 kv, list, set, map, b+tree item 수이며, +tsz(total size)는 전체 items이 차지하는 공간의 크기이고, +ktsz, ltsz, stsz, mtsz, btsz는 각각 kv, list, set, map, b+tree items이 차지하는 공간의 크기이다. +time은 prefix 생성 시간이다. + +모든 prefix들의 연산 통계 정보의 결과 예는 아래와 같다. +각 PREFIX 라인은 실제로 하나의 line으로 표시되지만, 본 문서는 이해를 돕기 위해 여러 line으로 표시한다. + + +``` +PREFIX get 2 hit 2 set 2 del 0 + lcs 0 lis 0 lih 0 lds 0 ldh 0 lgs 0 lgh 0 + scs 0 sis 0 sih 0 sds 0 sdh 0 sgs 0 sgh 0 ses 0 seh 0 + mcs 0 mis 0 mih 0 mus 0 muh 0 mds 0 mdh 0 mgs 0 mgh 0 + bcs 0 bis 0 bih 0 bus 0 buh 0 bds 0 bdh 0 bps 0 bph 0 bms 0 bmh 0 bgs 0 bgh 0 bns 0 bnh 0 + pfs 0 pfh 0 pgs 0 pgh 0 + gas 0 sas 0 +PREFIX a get 5 hit 5 set 5 del 0 + lcs 0 lis 0 lih 0 lds 0 ldh 0 lgs 0 lgh 0 + scs 0 sis 0 sih 0 sds 0 sdh 0 sgs 0 sgh 0 ses 0 seh 0 + mcs 0 mis 0 mih 0 mus 0 muh 0 mds 0 mdh 0 mgs 0 mgh 0 + bcs 0 bis 0 bih 0 bus 0 buh 0 bds 0 bdh 0 bps 0 bph 0 bms 0 bmh 0 bgs 0 bgh 0 bns 0 bnh 0 + pfs 0 pfh 0 pgs 0 pgh 0 + gas 0 sas 0 +PREFIX b get 2 hit 2 set 2 del 0 + lcs 0 lis 0 lih 0 lds 0 ldh 0 lgs 0 lgh 0 + scs 0 sis 0 sih 0 sds 0 sdh 0 sgs 0 sgh 0 ses 0 seh 0 + mcs 0 mis 0 mih 0 mus 0 muh 0 mds 0 mdh 0 mgs 0 mgh 0 + bcs 0 bis 0 bih 0 bus 0 buh 0 bds 0 bdh 0 bps 0 bph 0 bms 0 bmh 0 bgs 0 bgh 0 bns 0 bnh 0 + pfs 0 pfh 0 pgs 0 pgh 0 + gas 0 sas 0 +END +``` + +각 prefix의 연산 통계 정보에서 +get, hit, set, del은 kv 유형의 items에 대한 연산 통계이고, +'l', 's', 'm', 'b'로 시작하는 3 character는 각각 list, set, map, b+tree 유형의 items에 대한 연산 통계이며, +'p'로 시작하는 3 character는 특별히 b+tree에 대한 position 연산의 통계이다. +gas와 sas는 item attribute 연산의 통계이다. + +연산 통계에서 각 3 character의 의미는 다음과 같다. + +- list 연산 통계 + - lcs - lop create 수행 횟수 + - lis, lih - lop insert 수행 횟수와 hit 수 + - lds, ldh – lop delete 수행 횟수와 hit 수 + - lgs, lgh – lop get 수행 횟수와 hit 수 +- set 연산 통계 + - scs - sop create 수행 횟수 + - sis, sih - sop insert 수행 횟수와 hit 수 + - sds, sdh – sop delete 수행 횟수와 hit 수 + - sgs, sgh – sop get 수행 횟수와 hit 수 + - ses, seh - sop exist 수행 횟수와 hit 수 +- map 연산 통계 + - mcs - mop create 수행 횟수 + - mis, mih - mop insert 수행 횟수와 hit 수 + - mus, muh – mop update 수행 횟수와 hit 수 + - mds, mdh – mop delete 수행 횟수와 hit 수 + - mgs, mgh – mop get 수행 횟수와 hit 수 +- b+tree 연산 통계 + - bcs – bop create 수행 횟수 + - bis, bih – bop insert/upsert 수행 횟수와 hit 수 + - bus, buh – bop update 수행 횟수와 hit 수 + - bps, bph – bop incr(plus 의미) 수행 횟수와 hit 수 + - bms, bmh - bop decr(minus 의미) 수행 횟수와 hit 수 + - bds, bdh – bop delete 수행 횟수와 hit 수 + - bgs, bgh – bop get 수행 횟수와 hit 수 + - bns, bnh – bop count 수행 횟수와 hit 수 +- b+tree position 연산 통계 + - pfs, pfh - bop position 수행 횟수와 hit 수 + - pgs, pgh - bop gbp 수행 횟수와 hit 수 +- item attribute 연산 통계 + - gas - getattr 수행 횟수 + - sas - setattr 수행 횟수 + +### Zookeeper 상태 정보 + +zookeeper 상태 정보를 보는 명령이다. 다음은 stats zookeeper 실행 결과의 예이다. + +``` +STAT zk_connected true +STAT zk_failstop on +STAT zk_timeout 30000 +STAT zk_reconfig on +STAT zk_reconfig_version 100000000 +END +``` + +| stats | 설명 | +| ------------------ | ------------------------------------------------------------ | +| zk_connected | 주키퍼 연결 상태 | +| zk_failstop | 주키퍼 세션 만료 시 서버 자동 종료 여부 | +| zk_timeout | 주키퍼 세션 타임아웃(msec) | +| zk_reconfig | zookeeper dynamic reconfiguration 기능 사용 여부 | +| zk_reconfig_version| zookeeper dynamic reconfiguration 반영한 버전(16진수) | + +### Scrub 수행 상태 + +Scrub 수행 상태를 조회한 결과 예는 다음과 같다. + +``` +STAT scrubber:status stopped +STAT scrubber:last_run 0 +STAT scrubber:visited 0 +STAT scrubber:cleaned 0 +END +``` + +- status - 현재 scrub 작업이 running 중인지 stopped 상태인지를 나타낸다. +- last_run - 이전에 완료된 scrub 작업의 소요 시간을 초 단위로 나타낸다. +- visited - 현재 수행중인 또는 이전에 수행된 scrub에서 접근한 item들의 수를 나타낸다. +- cleaned - 현재 수행중인 또는 이전에 수행된 scrub에서 삭제한 item들의 수를 나타낸다. + +### slab class 별 cache key dump + +slab class 별 LRU에 달려있는 item들의 cache key들을 dump하기 위하여, +아래의 stats cachedump 명령을 제공한다. + +``` +stats cachedump [ forward | backward [sticky] ]\r\n +``` + +- \ - dump 대상 LRU를 지정하기 위한 slab class id이다. +- \ - dump하고자 하는 item 개수로서 0 ~ 200 범위에서 지정이 가능하다. +0이면 default로 50개로 지정되며, 200 초과이면 200개만 dump한다. +해당 LRU의 head 또는 tail에서 시작하여 limit 개 item들의 cache key들을 dump한다. +- forward or backward - LRU의 head 또는 tail 중에 어디에서 dump를 시작할 것인지를 지정한다. +forward이면 head에서 시작하고, backward이면 tail에서 시작한다. +지정하지 않으면, default는 forward이다. +- sticky - 하나의 slab class에서 non-sticky item들의 LRU 리스트와 sticky item들의 LRU 리스트가 별도로 유지되어 있다. +sticky가 지정되면 sticky LRU에서 dump하고, 지정되지 않으면 non-sticky LRU에서 dump한다. + +Cachedump 결과의 예는 아래와 같다. + +``` +ITEM a:bkey2 +ITEM a:bkey1 +ITEM b:bkey3 +ITEM b:bkey1 +ITEM b:bkey2 +ITEM c:bkey1 +ITEM c:bkey2 +END +``` + +### Persistence 정보 조회 + +Persistence의 설정 정보와 수행 결과를 조회한 결과 예는 다음과 같다. + +``` +STAT use_persistence on +STAT data_path /home/test/arcus/data/ARCUS-DB +STAT logs_path /home/test/arcus/data/ARCUS-DB +STAT async_logging false +STAT chkpt_interval_pct_snapshot 100 +STAT chkpt_interval_min_logsize 256 +STAT recovery_elapsed_time_sec 5 +STAT last_chkpt_in_progress true +STAT last_chkpt_failure_count 0 +STAT last_chkpt_start_time 20201222182102 +STAT last_chkpt_elapsed_time_sec 8 +STAT last_chkpt_snapshot_filesize_bytes 423333 +STAT current_command_log_filesize_bytes 65555 +END +``` + +- use_persistence - 현재 Persistence 모드가 on인지 off인지 나타낸다. +- data_path - 스냅샷 파일이 생성되는 경로를 나타낸다. +- logs_path - 명령 로그 파일이 생성되는 경로를 나타낸다. +- async_logging - 명령 로깅의 동작 모드로 동기 로깅 모드면 false, 비동기 로깅 모드면 true로 나타낸다. +- chkpt_interval_pct_snapshot - 체크포인트 수행 주기 설정으로, 스냅샷 파일 크기에 대비하여 명령 로그 파일의 추가 증가된 크기 비율을 나타낸다. +- chkpt_interval_min_logsize - 체크포인트 수행 주기 설정으로, 체크포인트를 수행할 명령 로그 파일의 최소 크기를 나타낸다. +- recovery_elapsed_time_sec - ARCUS 인스턴스 재구동 후, 데이터를 복구하는데 걸리는 시간을 나타낸다. (unit : seconds) +- last_chkpt_in_progress - 현재 체크포인트의 수행 여부를 나타낸다. +- last_chkpt_failure_count - 이전 체크포인트가 수행되거나 성공될 때까지 몇 번 실패한 것인지를 나타낸다. +- last_chkpt_start_time - 이전 체크포인트가 조건이 충족되어 시작한 시간을 나타낸다. (unit : absolute timestamp) +- last_chkpt_elapsed_time_sec - 이전 체크포인트 수행하는데 걸린 시간을 나타낸다. (unit : seconds) +- last_chkpt_snapshot_filesize_bytes - 이전 체크포인트 스냅샷 파일 크기를 나타낸다. (unit : bytes) +- current_command_log_filesize_bytes - 현재 명령 로그 파일 크기를 나타낸다. (unit : bytes) + +## Config 명령 + +ARCUS Cache Server는 특정 configuration에 대해 동적으로 변경하거나 현재의 값을 조회하는 기능을 제공한다. +동적으로 변경가능한 configuration들은 현재 아래만 지원한다. + +- verbosity +- memlimit +- zkfailstop +- hbtimeout +- hbfailstop +- maxconns +- max_collection_size +- max_element_bytes +- scrub_count + +### Config verbosity + +ARCUS Cache Server의 verbose log level을 동적으로(restart 없이) 변경/조회한다. + +``` +config verbosity []\r\n +``` + +\는 새로 지정할 verbose log level 값으로, 허용가능한 범위는 0 ~ 2이다. +이 인자가 생략되면 현재 설정되어 있는 verbose 값을 조회한다. + +### Config memlimit + +ARCUS Cache Server 구동 시에 -m 옵션으로 설정된 memory limit을 동적으로(restart 없이) 변경/조회한다. + +``` +config memlimit []\r\n +``` + +\는 새로 지정할 memory limit으로 MB 단위로 설정하며, +ARCUS Cache Server가 현재 사용 중인 메모리 크기인 total_malloced 보다 큰 크기로만 설정이 가능하다. +이 인자가 생략되면 현재 설정되어 있는 memory limit 값을 조회한다. + +### Config zkfailstop + +ARCUS Cache Server의 automatic failstop 기능을 on 또는 off 한다. + +``` +config zkfailstop [on|off]\r\n +``` + +Network failure 상태에서 정상적인 서비스를 진행하지 못하는 cache server가 cache cloud에 그대로 존재할 경우, 해당 cache server가 담당하고 있는 data 범위에 대한 요청이 모두 실패하고 DB에 부담을 주게 된다. 또한 이후에 ZooKeeper에 재연결 되더라도 old data를 가지고 있을 가능성이 있으며 이로 인해 응용에 오동작을 발생시킬 수 있다. ARCUS Cache Server는 이를 해결하기 위해 ZooKeeper session timeout이 발생할 경우 failed cache server를 cache cloud에서 자동으로 제거하는 automatic failstop 기능을 기본적으로 제공한다. + +### Config hbtimeout + +hbtimeout 값을 변경/조회한다. + +``` +config hbtimeout []\r\n +``` + +ARCUS Cache Server에는 주기적으로 노드의 정상 작동 여부를 확인하는 heartbeat 연산이 존재한다. hbtimeout은 heartbeat 연산의 timeout 시간을 의미한다. hbtimeout으로 설정한 시간이 지나도 heartbeat 연산이 이루어지지 않으면 해당 heartbeat는 timeout된 것으로 간주한다. 최소 50ms, 최대 10000ms로 설정할 수 있으며 디폴트 값은 10000ms이다. + +### Config hbfailstop + +hbfailstop 값을 변경/조회한다. + +``` +config hbfailstop [hbfailstop]\r\n +``` + +ARCUS Cache Server는 heartbeat 지연이 계속될 경우 서버를 강제 종료할 수 있다. 연속된 timeout이 발생할 때마다 hbtimeout 값을 누적하여 더하고, 누적된 값이 hbfailstop 값을 넘길 경우 failstop을 수행한다. 예를 들어 hbfailstop이 30초, hbtimeout이 10초이면 hbtimeout이 연속으로 3번 발생하였을 경우 failstop이 발생한다. 최소 3000ms, 최대 300000ms로 설정할 수 있으며 디폴트 값은 60000ms이다. + +### Config maxconns + +ARCUS Cache Server 구동 시에 -c 옵션으로 설정된 최대 연결 수를 동적으로(restart 없이) 변경/조회한다. + +``` +config maxconns []\r\n +``` + +\는 새로 지정할 최대 연결 수로서, 현재의 연결 수보다 10% 이상의 큰 값으로만 설정이 가능하다. +이 인자가 생략되면 현재 설정되어 있는 최대 연결 수 값을 조회한다. + +### Config max_collection_size + +콜렉션 아이템의 최대 element 수를 조회/변경한다. + +``` +config max__size []\r\n +* : list|set|btree|map +``` + +기본 설정은 50000개이며 최소 10000개, 최대 1000000개 까지 설정할 수 있다. 기존 값보다 작게 설정할 수 없다. 기본 설정보다 큰 값으로 설정하고 나서, 한 번에 많은 element 들을 조회한다면 조회 응답 속도가 느려질 뿐만 아니라 다른 연산의 응답 속도에도 부정적 영향을 미친다. 따라서, 주의 사항으로, 최대 element 수를 늘리더라도 응용은 한번에 적은 수의 element 만을 조회하는 요청을 반복하는 형태로 구현하여야 한다. + +### Config max_element_bytes + +Collection element가 가지는 value의 최대 크기를 byte 단위로 설정한다. 기본 설정은 16KB이며 1~32KB까지 설정 가능하다. + +``` +config max_element_bytes []\r\n +``` + +### Config scrub_count + +ARCUS Cache Server에는 더 이상 유효하지 않은 아이템을 일괄 삭제하는 scrub 명령이 존재한다. config scrub_count 명령은 daemon thread가 scrub 명령을 수행할 때, 한 번의 연산마다 몇 개의 아이템을 지울지를 설정/조회한다. 기본 값은 96이며 최소 16, 최대 320으로 설정할 수 있다. + +``` +config scrub_count []\r\n +``` + +## Command Logging 명령 + +ARCUS Cache Server에 입력되는 command를 logging 한다. +start 명령을 시작으로 logging이 종료될 때 까지의 모든 command를 기록한다. +단, 성능유지를 위해 skip되는 command가 있을 수 있으며 stats 명령을 통해 그 수를 확인할 수 있다. +10MB log 파일 10개를 사용하며, 초과될 경우 자동 종료한다. + +``` +cmdlog [start [] | stop | stats]\r\n +``` + +\는 logging 정보를 저장할 file의 path이다. +- path는 생략 가능하며, 생략할 경우 default로 지정된다. + - default로 자동 지정할 경우 log file은 memcached 구동 위치 / command_log 디렉터리 안에 생성된다. + - command_log 디렉터리는 자동생성되지 않으며, memcached process가 구동된 위치에 생성해 주어야 한다. + - 생성되는 log file의 파일명은 command_port_bgndate_bgntime_{n}.log 이다. +- path는 직접 지정할 경우 절대 path, 상대 path 지정이 가능하다. 최종 파일이 생성될 디렉터리까지 지정해 주어야 한다. + +start 명령의 결과로 log file에 출력되는 내용은 아래와 같다. + +``` +--------------------------------------- +format :