Observe Command Line Interface Tool Overview¶
The Observe Command Line Interface (CLI) Tool allows you to interact with an Observe instance from the command line using the Observe API without requiring cURL at the command prompt. Observe provides a cloud-based observability platform that models machine data to help you debug issues with software and businesses fast.
Installing the Observe CLI Tool¶
You must install Go version 1.19.8, an open-source programming language supported by Google.
If you have Go installed, use the following command to install the Observe CLI tool:
go install https://github.com/observeinc/observe
Depending on how you installed Go and your environment, the binary appears in your
You can find documentation for the Observe API here.
Download pre-built binaries for popular operating systems at Observe Releases. Put the binary somewhere in your
Observe CLI Tool Quick Start¶
Observe Customer ID - your 12-digit customer ID for your Observe instance, for example,
Observe instance URL - the hostname of your Observe instance, such as
Email address and password - the email address and password used to log into your Observe instance
Once you gather your prerequisites, run the following command:
$ observe --customerid 123456789012 --cluster observeinc.com login [email protected] --read-password --save Password for 123456789012.observeinc.com: "[email protected]": XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX login: saved authtoken to section "default" in config file "/home/myname/.config/observe.yaml"
Then, test your access using the following command:
$ observe query -q 'pick_col timestamp, log | limit 10' -i 'Default.kubernetes/Container Logs' | timestamp | log | ----------------------------------------------------------------------------------- | 1679497866772157872 | E0420 16:20:00.123456 1 package/file.go:123] Hello World! | ...
login command saves the generated Authentication Token in a local profile to reuse when you execute other commands. If you don’t want to save your Authentication Token in the profile, you can specify
--authtoken on the command line, and not use the command,
--save when logging into the instance.
If you use an SSO SAML integration such as Okta, Azure AD, Google, or PingOne, then see the section about the login command for how to generate credentials.
The name of the dataset input for your query may vary based on the installed or built datasets in your workspace, as well as the name of your workspace. Explore the Datasets page on your Observe instance to find more datasets. You can also use a dataset ID directly, such as
41007104, to specify the dataset to read. To specify more than one dataset to use for joins and unions, see the Query command section.
Configuring the CLI Command¶
Observe uses the following format for CLI commands:
observe [config-options] "command" [command-options]
The CLI uses
config-options to specify general options such as the tenant and user for your interactions and where to read and write data.
command, selects the major operating mode such as
login. The parameter,
command-options, specifies the specific action for the selected command.
Commands require three parameters to interact with the Observe service:
Customer ID - the numeric identifier of your customer account used in the URL, such as
Observe instance URL - the hostname of your Observe instance such as
Authentication token - your credentials that identify you and your privileges on the Observe instance. Similar to a password, you should store this token securely.
Specify the Customer ID using the parameter
Specify the Observe instance using the parameter
Specify the Authentication token using the parameter
You can also create a profile, such as a
default profile, in the Configuration file and select the shape using the parameter,
config-options, has different parameters than the
command-options command. You may not specify any
config-options after a command, and
command-options may not be specified before the command.
Configuring Profile Files¶
~/.config/observe.yaml, can store your commonly used configuration options, such as the customer ID and the cluster URL. If you want, you can include the authentication token if handled securely. The YAML file contains a list of profiles, and you can choose a profile using the
--profile command line option. If you do not specify a specific profile, Observe uses the default profile. You can specify another file for this using the parameter,
--config, or the environment variable
The name of each option within the profile matches the name of the corresponding
config-option. For example,
profiles: default: customerid: "123456789012" cluster: "observeinc.com" authtoken: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" testing: customerid: "234567890123" cluster: "observe-testing.com" authtoken: "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY" timestamp: true workspace: Testing
With this profile configuration, you can use the
default profile using the
observe command ... and the
testing profile using the
observe --profile=testing command ....
If you don’t specify a profile on the command line but you set the
Observe_Profile environment profile, then Observe uses that profile.
Output and Printing of the CLI Tool¶
The CLI options in the table can provide more information about your Observe instance.
Displays the current configuration used from the command line, profile, or environment. Or, it can be a combination of all three options.
Prints more verbose output about the current state, which may be helpful when automating actions and debugging failed actions. The output prints to the standard error output stream.
Prints less verbose output about an ongoing activity which may be preferred.
Timestamps each progress, debug, or error message, which may be useful when you use this tool to automate tasks but harder to read when using the tool interactively.
Observe sends error, progress, and debug information to the standard error stream. The CLI sends actual data output from a command to the standard output stream or to a file specified using the
--output=filename. Data output redirection is a global configuration option and not an option for a specific command.