Introducing the Coherence CLI

We are excited to announce the immediate availability of a new command line interface (CLI) for Coherence.

The Coherence CLI orcohctl, 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 cohctl to 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.

The Coherence CLI in action

Why Use the CLI?

The CLI complements your existing Coherence management tools and allows you to:

1. Interactively monitor your Coherence clusters from a lightweight terminal-based interface
2. Monitor service StatusHA during rolling restarts of Coherence clusters
3. Script Coherence monitoring and incorporate results into other management tooling
4. Output results in various formats including text, JSON and utilize JsonPath to extract attributes of interest
5. Gather information that may be useful for Oracle Support to help diagnose issues
6. Connect to standalone or WebLogic Server based clusters from commercial versions 12.2.1.4 and 14.1.1.0 and above as well as all Coherence Community Edition (CE) versions
7. Retrieve thread dumps and Java Flight Recordings across members
8. 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

Command Structure

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 get and 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:

Coherence CLI Features

Discovering Clusters

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-cluster
Current 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.

Describing Resources

You can 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.

Diagnostic Commands

There are also a number of commands that can be used to obtain diagnostic information sometimes required by Oracle Support. These include:

1. Retrieve thread dumps for all or specific nodes
2. Dump the cluster heap for all or specific roles
3. Create and manage Java Flight Recordings
4. Start/stop Reporters
5. Use Coherence NameService lookup to retrieve cluster information

Conclusion

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.

Useful Resources

See the following pages for information on the the CLI:

• Coherence CLI on GitHub
• Coherence CLI Documentation
• Coherence Community
• Slack — Visit this site to get an invitation

Coherence CLI Screencast