osearch

A command line client for OpenSearch

osearch is a command-line tool for searching and streaming logs from OpenSearch.

It is inspired by tools like logcli from Grafana Loki and provides a fast terminal-based workflow for inspecting OpenSearch log data.

The main goals are simple:

• search documents quickly
• follow new document events in almost real time
• inspect structured documents fields
• work efficiently directly from the terminal
• export documents to textfile for importing them to issue trackers
• pipe output to specialized problem-oriented analytics tools (i.e. when the capabilities of opensearch-dashboards are not enough)
• automate error analysis

This tool is not intended to compete with the existing tools opensearch-cli and sql-cli, but rather to cover other functions that cannot be achieved with the familiar tools—or can only be achieved through cumbersome workarounds.

Features

• Live log streaming (tail --follow)
• OpenSearch query support
• Time based filtering
• JSON output mode
• Human-readable text output
• Field value discovery (labels)
• Shell completions
• Configuration file support
• TLS verification override for development environments

Installation

From Source

Requirements:

• Rust stable
• Cargo

Clone the repository:

git clone https://github.com/example/osearch.git
cd osearch
cargo build
cargo run -- --help
export PATH="$PWD/target/debug/:$PATH"
source <(osearch completions bash)

From Github

VERSION=$(curl -s https://api.github.com/repos/scoopex/osearch/releases/latest \
  | sed -n 's/.*"tag_name":[[:space:]]*"\([^"]*\)".*/\1/p')

curl -LO "https://github.com/scoopex/osearch/releases/download/${VERSION}/osearch-${VERSION}-x86_64-unknown-linux-gnu"
mv osearch-${VERSION}-x86_64-unknown-linux-gnu osearch
chmod +x osearch
export PATH="$PWD/target/debug/:$PATH"
source <(osearch completions bash)

Usage

A OpenSearch document CLI

Usage: osearch [OPTIONS] <COMMAND>

Commands:
  labels       Print the value permutations of the field in a specific index pattern
  fields       Print the fields and their type for all matching indexes
  tail         Stream documents
  query        Execute a search query
  completions  Generate shell completions
  help         Print this message or the help of the given subcommand(s)

Options:
      --url <URL>            The opensearch uri [env: OPENSEARCH_URL=] [default: http://localhost:9200]
      --user <USER>          The basic auth username [env: OPENSEARCH_USER=]
      --password <PASSWORD>  The basic auth password [env: OPENSEARCH_PASSWORD=]
      --insecure <INSECURE>  Disable TLS certificate verification [possible values: true, false]
      --pretty <PRETTY>      Pretty print document [possible values: true, false]
  -h, --help                 Print help
  -V, --version              Print version



Configuration
-------------

"osearch" can use a configuration file to load the session defaults.
The default location can be overloaded by specifying the OSEARCH_CONFIG
environment variable.

- Create a configuration directory
  mkdir -p $HOME/.config/osearch
- Create a configuration file `$HOME/.config/osearch/config.toml`
  ---
  url = "https://opensearch-api.my.umon.cloud/"
  user = "admin"
  password = "THEVERYSECUREPASSWORD"
  insecure = true

  [index]
  default = "logs-*"
  ---

Usage
-----

- Run directly from build dir
  $ cargo run -- tail logs-* --follow
- Run a query which filters the index patter `logs-*` for documents where the field `system_environment` is set to `DevEx`
  $ osearch query \
      --query "system_environment:DevEx" \
      logs-*
- Follow all received documents
  $ osearch tail logs-* --follow
  $ osearch tail logs-* \
      --follow \
      --since 15m

  $ osearch tail logs-* \
      --follow \
      --query "system_environment:DevEx"
- Use json output instead of text
  $ osearch tail logs-* \
      --follow \
      --output json
- Give a overview about the permutations of the field values
  $ osearch labels logs-* system_environment
- Give a overview about fields and their types
  $ osearch labels logs-*