escope: A Faster Way to Understand Your Elasticsearch Clusters
Elasticsearch is powerful — but operating it at scale is a different story.
As systems grow, clusters multiply, and search traffic increases, the real challenge is no longer just querying data — it’s understanding the system itself. At some point, every search engineer hits the same wall:
“I know the data is there, but I can’t quickly understand what’s happening inside the cluster.
This is where escope comes in.
👉 https://github.com/mertbahardogan/escope
The Real Problem: Slow Feedback Loops
In production environments, especially in high-throughput search systems, speed of understanding is critical.
Yet, basic questions still require too much effort:
- Is the cluster actually healthy, or just “green”?
- Are shards balanced across nodes?
- Which node is under pressure?
- Did something change in index settings?
- Is this cluster behaving differently from another one?
This creates a slow feedback loop, which is especially painful during incidents.
One Command to Understand Your Cluster
escope is a lightweight CLI designed to make Elasticsearch instantly understandable. At the center of escope is a single command:
~ escope check
╔══════════════════════════════════════════════════════════════╗
║ ESCOPE CLUSTER ANALYSIS ║
╠══════════════════════════════════════════════════════════════╣
║ CRITICAL ISSUES: 2 ║
║ • Cluster status is RED - immediate action required! ║
║ • 5 unassigned shards detected ║
╠══════════════════════════════════════════════════════════════╣
║ WARNING ISSUES: 4 ║
║ • Node 'data-1' heap usage at 87% (threshold: 85%) ║
║ • 2 indices in YELLOW status ║
║ • Index 'logs-2024' has 150 segments (high fragmentation) ║
║ • Index 'metrics' is over-scaled: 10 shards → recommend 3 ║
╚══════════════════════════════════════════════════════════════╝This is not just a wrapper. It’s a curated diagnostic snapshot of your cluster.
Why This Matters
In real-world scenarios:
- During an incident → you don’t have time to explore
- Before a deployment → you want a quick sanity check
- While debugging → you need a reliable baseline
check becomes your first instinct, not your last step.
Technical Architecture
escope is built with a simple, performance-first approach.
It uses Go to deliver a fast, portable single binary, with Cobra for a clean CLI structure and the official go-elasticsearch client for reliable ES integration.
Configuration is handled via YAML, keeping it simple and human-readable. The focus is minimalism: fast, clear, and efficient.
Cluster Overview: Quick Snapshot
escope provides a cluster command for a fast view of your cluster’s state:
~ escope cluster
Cluster: production-cluster [ GREEN ]
+-------------------------------------------------------------+
| RESOURCES |
+-------------------------------------------------------------+
| DISK ██████████░░░░░░░░░░ 50.0% 250gb / 500gb |
| HEAP █████████░░░░░░░░░░░ 45.0% 1.8gb / 4gb |
| MEMORY █████████████░░░░░░░ 62.0% 6.2gb / 10gb |
+-------------------------------------------------------------+
+----------------+-------------------------------+
| Metric | Value |
+----------------+-------------------------------+
| Nodes | 3 (Data: 2, Master: 1) |
| Indices | 15 |
| Documents | 1,200,000 |
| Primary Shards | 15 |
| Total Shards | 30 |
| Avg Shard Size | 8.33 GB |
+----------------+-------------------------------+All in a single, readable output — no need to combine multiple APIs. It shows resource usage (disk, heap, memory), node and shard distribution, index and document stats.
Configuration: Multi-Cluster, Simplified
Managing multiple clusters should be simple. escope provides a minimal config layer to define, list, and switch between clusters:
escope config --alias prod --host="https://..." --username="..." --password="..."
escope config list
escope config switch prod
escope config current
escope config timeout 10Add clusters, switch instantly, and keep your context clear — all with a few commands.
Nodes
escope node— Node table: roles, CPU/memory/disk, heap, shard/doc counts, etc.escope node dist— How work and shards relate to nodes (distribution-style view).escope node gc— JVM garbage-collection stats (optionally filtered by node name).
Indices and shards
escope index— Without--name: list user indices with summary metrics; with--name: detail for one index (optional--topwhere supported).escope index system— Same style of listing, but for system indices.escope index sort— Sort the index list by a field (asc/desc).escope index use [name]— Remember index/alias for subcommands;--clearforgets it.escope index mapping— Show mappings for the chosen index (via--nameoruse).escope index settings— Show index settings.escope index analyzer— Show analyzer configuration for the index.escope index exists— Document counts: field exists, or exact term if it--valueis set.escope index cardinality— Approximate cardinality (unique values) for a field.escope shard— Shard table: state, size, node, index (user indices).escope shard dist— Shard distribution across nodes.escope shard system— Shards for system indices only.escope shard sort— Sort shard rows by a column.
Segments and Lucene
escope segments— Segment-level view and practical optimization hints.escope lucene— Deeper Lucene stats (optionally scoped--nameto one index/alias).
Text Analysis
escope analyze <analyzer_or_tokenizer> "<text>"— Run the_analyzeAPI (--typefor analyzer vs tokenizer).escope termvectors <index> <doc_id> [term]— Term vectors/term lookup (--fieldsfor the field list).
Tooling
escope upgrade— Update escope itself to the latest version (go installflow).
Contributing
escope is built to make Elasticsearch easier to understand in real-world systems.
Contributions are welcome — especially around improving check, adding new diagnostics, or enhancing multi-cluster workflows.
If it helps engineers understand clusters faster, it belongs here.
