diff --git a/docs/reference/cat.asciidoc b/docs/reference/cat.asciidoc index b5e73a1dd06..d857006d2b1 100644 --- a/docs/reference/cat.asciidoc +++ b/docs/reference/cat.asciidoc @@ -120,3 +120,4 @@ include::cat/thread_pool.asciidoc[] include::cat/shards.asciidoc[] +include::cat/segments.asciidoc[] \ No newline at end of file diff --git a/docs/reference/cat/segments.asciidoc b/docs/reference/cat/segments.asciidoc new file mode 100644 index 00000000000..9cc5215f6b6 --- /dev/null +++ b/docs/reference/cat/segments.asciidoc @@ -0,0 +1,71 @@ +[[cat-segments]] +== cat segments + +The `segments` command provides low level information about the segments +in the shards of an index. It provides information similar to the +link:indices-segments.html[_segments] endpoint. + +[source,shell] +-------------------------------------------------- +% curl 'http://localhost:9200/_cat/segments?v' +index shard prirep ip segment generation docs.count [...] +test 4 p 192.168.2.105 _0 0 1 +test1 2 p 192.168.2.105 _0 0 1 +test1 3 p 192.168.2.105 _2 2 1 +-------------------------------------------------- + +[source,shell] +-------------------------------------------------- +[...] docs.deleted size size.memory committed searchable version compound + 0 2.9kb 7818 false true 4.10.2 true + 0 2.9kb 7818 false true 4.10.2 true + 0 2.9kb 7818 false true 4.10.2 true +-------------------------------------------------- + +The output shows information about index names and shard numbers in the first +two columns. + +If you only want to get information about segments in one particular index, +you can add the index name in the URL, for example `/_cat/segments/test`. Also, +several indexes can be queried like `/_cat/segments/test,test1` + + +The following columns provide additional monitoring information: + +prirep:: Whether this segment belongs to a primary or replica shard. + +ip:: The ip address of the segments shard. + +segment:: A segment name, derived from the segment generation. The name + is internally used to generate the file names in the directory + of the shard this segment belongs to. + +generation:: The generation number is incremented with each segment that is written. + The name of the segment is derived from this generation number. + +docs.count:: The number of non-deleted documents that are stored in this segment. + +docs.deleted:: The number of deleted documents that are stored in this segment. + It is perfectly fine if this number is greater than 0, space is + going to be reclaimed when this segment gets merged. + +size:: The amount of disk space that this segment uses. + +size.memory:: Segments store some data into memory in order to be searchable efficiently. + This column shows the number of bytes in memory that are used. + +committed:: Whether the segment has been sync'ed on disk. Segments that are + committed would survive a hard reboot. No need to worry in case + of false, the data from uncommitted segments is also stored in + the transaction log so that Elasticsearch is able to replay + changes on the next start. + +searchable:: True if the segment is searchable. A value of false would most + likely mean that the segment has been written to disk but no + refresh occurred since then to make it searchable. + +version:: The version of Lucene that has been used to write this segment. + +compound:: Whether the segment is stored in a compound file. When true, this + means that Lucene merged all files from the segment in a single + one in order to save file descriptors. diff --git a/rest-api-spec/api/cat.segments.json b/rest-api-spec/api/cat.segments.json new file mode 100644 index 00000000000..25dce003df4 --- /dev/null +++ b/rest-api-spec/api/cat.segments.json @@ -0,0 +1,33 @@ +{ + "cat.segments": { + "documentation": "http://www.elasticsearch.org/guide/en/elasticsearch/reference/master/cat-segments.html", + "methods": ["GET"], + "url": { + "path": "/_cat/segments", + "paths": ["/_cat/segments", "/_cat/segments/{index}"], + "parts": { + "index": { + "type" : "list", + "description": "A comma-separated list of index names to limit the returned information" + } + }, + "params": { + "h": { + "type": "list", + "description" : "Comma-separated list of column names to display" + }, + "help": { + "type": "boolean", + "description": "Return help information", + "default": false + }, + "v": { + "type": "boolean", + "description": "Verbose mode. Display column headers", + "default": true + } + } + }, + "body": null + } +} diff --git a/rest-api-spec/test/cat.segments/10_basic.yaml b/rest-api-spec/test/cat.segments/10_basic.yaml new file mode 100755 index 00000000000..5147057953a --- /dev/null +++ b/rest-api-spec/test/cat.segments/10_basic.yaml @@ -0,0 +1,87 @@ +--- +"Help": + - do: + cat.segments: + help: true + + - match: + $body: | + /^ index .+ \n + shard .+ \n + prirep .+ \n + ip .+ \n + segment .+ \n + generation .+ \n + docs.count .+ \n + docs.deleted .+ \n + size .+ \n + size.memory .+ \n + committed .+ \n + searchable .+ \n + version .+ \n + compound .+ \n + $/ +--- +"Test cat segments output": + + - do: + indices.create: + index: index1 + body: + settings: + number_of_shards: "3" + number_of_replicas: "0" + - do: + index: + index: index1 + type: type + body: { foo: bar } + refresh: true + - do: + cluster.health: + wait_for_status: yellow + - do: + cat.segments: + v: false + - match: + $body: | + /^(index1 \s+ \d \s+ (p|r) \s+ \d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3} \s+ _\d (\s\d){3} \s+ + (\d+|\d+[.]\d+)(kb|b) \s+ \d+ (\s+ (false|true)){2} \s+ \d+\.\d+\.\d+ \s+ (false|true) \s? \n?)$/ + + - do: + indices.create: + index: index2 + body: + settings: + number_of_shards: "3" + number_of_replicas: "0" + - do: + cluster.health: + wait_for_status: yellow + wait_for_relocating_shards: 0 + + - do: + index: + index: index2 + type: type + body: { foo: bar } + refresh: true + - do: + cluster.health: + wait_for_status: yellow + + + - do: + cat.segments: + v: false + - match: + $body: | + /^(index(1|2) .+ \n?){2}$/ + + - do: + cat.segments: + index: index2 + v: false + - match: + $body: | + /^(index2 .+ \n?)$/