Introducing the Coherence CLI
We are excited to announce the immediate availability of a new command line interface (CLI) for Coherence.
The Coherence CLI or
cohctl, is a lightweight tool, in the tradition of tools such as
kubectl, which can be scripted or used interactively to manage and monitor Coherence clusters. You can use
cohctlto view all cluster information such as clusters, machines, members, services, caches, federation, persistence and much more, as well as perform various management operations against clusters.
The CLI accesses clusters using the HTTP Management over REST interface and therefore requires this to be enabled on any clusters you want to monitor or manage.
Why Use the CLI?
The CLI complements your existing Coherence management tools and allows you to:
- Interactively monitor your Coherence clusters from a lightweight terminal-based interface
- Monitor service
StatusHAduring rolling restarts of Coherence clusters
- Script Coherence monitoring and incorporate results into other management tooling
- Output results in various formats including text, JSON and utilize JsonPath to extract attributes of interest
- Gather information that may be useful for Oracle Support to help diagnose issues
- Connect to standalone or WebLogic Server based clusters from commercial versions 18.104.22.168 and 22.214.171.124 and above as well as all Coherence Community Edition (CE) versions
- Retrieve thread dumps and Java Flight Recordings across members
- Make changes to various modifiable JMX attributes on services, caches and members
Where can I Get the CLI?
The Coherence CLI is Open Source and available on GitHub at https://github.com/oracle/coherence-cli.
It is downloadable as a binary binary for Linux and Windows and an installable package for macOS.
See the installation guide to install and then the quick start guide to get going with the CLI.
Using the CLI
The CLI is built in Go and uses the Cobra CLI library which creates a standard and consistent CLI user experience. For all commands there is comprehensive help available. The command structure is:
cohctl verb noun [args] [options]
You can issue
describe on most Coherence objects, including: clusters, machines, members, services, caches, topics, executors, proxies, federation, http-servers, persistence, to name a few.
There are also various other commands for inspecting or managing resources including but not limited to reporters, Java Flight Recordings (when supported by the JVM), thread dumps and snapshots.
The online documentation contains the full list of available commands.
The follow graphic outlines the comprehensive list of features and commands available:
Before working with a cluster, you need to add the cluster connection. You can discover clusters using the Coherence Name Service or manually add clusters using the Coherence Management over REST endpoint. If you don’t specify a host/port the CLI will discover clusters on the local machine.
Adding a cluster Manually
If you know the Management over REST host and port you can also manually add the cluster using the following:
Setting a Context
When you issue commands against a cluster you can use the
-c option to specify the connection, but you can also set a context to be used in all subsequent commands:
$ cohctl set context my-clusterCurrent context is now my-cluster
Displaying list of resources
You can use the
get command to display a list of resources. In the example below we use
get members to display the list of members. You can also provide the
-o wide option to many commands to display additional information.
describe an individual instance of a resource as mentioned above, such as members, services, etc. In the following example we display all the caches and describe an individual cache named orders.
Changing Output Format
By default, the output format is
table but can be changed to
wide as we saw earlier. You also have the option to output in JSON format using
-o json or applying a JSONPath expression to retrieve attributes of interest.
Below we issue the
get caches command and change the output format to JSON and pipe through
jq to format the output.
You can also pass a JSONPath expression using
-o jsonpath= option. In the example below we are retrieving node ids from all members where the available memory is < 250MB.
There are also a number of commands that can be used to obtain diagnostic information sometimes required by Oracle Support. These include:
- Retrieve thread dumps for all or specific nodes
- Dump the cluster heap for all or specific roles
- Create and manage Java Flight Recordings
- Start/stop Reporters
- Use Coherence NameService lookup to retrieve cluster information
The Coherence CLI is a great addition to your toolkit for monitoring and managing Coherence clusters. Visit the home page on GitHub and take it for a spin. Join our Slack channel to keep up to date with the latest on the CLI and other Coherence projects.
See the following pages for information on the the CLI: