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. cURL is a command line tool for transferring data. 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¶

Prerequisite

You must install Go version 1.19.8 or higher. Go is 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 github.com/observeinc/observe@latest

Depending on how you installed Go and your environment, the binary appears in your go/bin directory.

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 go PATH.

Observe CLI Tool Quick Start¶

Prerequisites

Observe Customer ID - your 12-digit customer ID for your Observe instance, for example, 123456789012
Observe instance URL - the hostname of your Observe instance, such as observeinc.com
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 ${OBSERVE_CUSTOMER_ID} --site observeinc.com login [email protected] --read-password 
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! |
...

Note

You must visit the Observe website using the link provided when logged in as the appropriate user, and authorize the login request in the Web app. If you don’t want to use this flow, and you have a direct email address and password) login, you can skip the --sso flag and enter the password directly. If you use SSO for Observe with an SSO provider that doesn’t provide your email address as a user property, you can use the User ID instead of the email address. Your User ID for your user can be found in the Observe Web instance in the Settings -> Account Settings tab, at the bottom of the page.

The 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.

The parameter, command, selects the major operating mode such as query or 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 https://123456789012.observeinc.com/.
Observe instance URL - the hostname of your Observe instance such as observeinc.com.
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 --customerid.

Specify the Observe instance using the parameter --site.

Specify the Authentication token using the parameter --authtoken.

You can also create a profile, such as a default profile, in the Configuration file and select the shape using the parameter, --profile.

Note

The command, 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¶

The file, ~/.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 OBSERVE_CONFIG.

The name of each option within the profile matches the name of the corresponding config-option. For example,

profile:
  default:
    customerid: "123456789012"
    site: "observeinc.com"
    authtoken: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
  testing:
    customerid: "234567890123"
    site: "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 Options¶

The CLI options in the table can provide more information about your Observe instance.

Parameter	Option
`--authtoken string`	The bearer token for Observe authorization. May be two-part with a space separator. Does not include ‘Bearer’ word.
`--config string`	Read configuration from given file rather than ~/config/observe.yaml. Can also be specified in environment OBSERVE_CONFIG.
`--debug`	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.
`--output string`	The output file name for data output. If empty or ‘-’, output goes to stdout.
`--profile string`	The name of a section in the ~/.config/observe.yaml config file. Make empty to read no profile. Can also be specified in environment OBSERVE_PROFILE (default “default”)
`--quiet`	Prints less verbose output about an ongoing activity which may be preferred.
`--quiet-exit`	Return successful exit code even on failure.
`--show-config`	Print configuration before running command.
`--site string`	The domain of your Observe tenant site. Can include `:port` if needed.
`--timestamp`	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.
`--workspace string`	Default workspace to assume for objects if none is specified.

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.