File Upload (ze Tool)

The ze tool is the Zebrium command-line interface for uploading log events from files or streams. For more information, see https://github.com/zebrium/ze-cli.

The ze tool was recently updated to version 2.0.0, and these documents refer to that version.

Getting Started

Prerequisites

A collector token, which you can find by clicking the Other button under Log Collectors on the Integrations & Collectors page (Settings () Integrations & Collectors) > in the Zebrium user interface.
The URL to your instance of Zebrium, which you can also find by clicking the Other button under Log Collectors on the Integrations & Collectors page (Settings () Integrations & Collectors) > in the Zebrium user interface.

Installing ze

Download the corresponding release from the ze-cli GitHub Releases page: https://github.com/zebrium/ze-cli/releases.
Set up your path in your shell config to include the new binary.
Start a new terminal and test your installation by running the following command:

ze -v

Before you start uploading log files with the ze tool, you will need to set Enable Historic Incident Detection to Yes in the Zebrium user interface. If you do not enable this setting, Zebrium cannot create Root Cause reports for logs that are older than a few hours.

In the Zebrium user interface, go to the Root Cause Settings page (Settings () > Root Cause Settings).
Set Enable Historic Incident Detection to Yes, and then click Apply. An Apply Change dialog appears.
Click OK. Historic incident detection is enabled.

Configuration

The ze tool supports a variety of ways to set its parameters. You can set all parameters using arguments. To find out the arguments that are available and required for each call, use ze -help or ze <subcommand> -help.

When leveraging the configuration file or environment variables, the ze tool uses the following precedence: configuration file > environment files > command-line arguments.

Configuration File

The ze tool supports setting global variables in a .ze file for easy configuration. The default location of this is $HOME/.ze; however, you can override this by passing a new path with the --config option.

The contents of the .ze file are as follows:

url: <ze_log_collector_url>

ze_token: <ze_log_collector_token>

where <ze_log_collector_token> is the collector token, which you can find by clicking the Other button under Log Collectors on the Integrations & Collectors page (Settings () Integrations & Collectors) > in the Zebrium user interface:

Environment Variables

The ze tool supports setting the following environment variables:

ZE_AUTH: XXXXXXXXXXXX

ZE_URL: https://cloud.zebrium.com

Commands and Help

Run the following command to upload log event data to your Zebrium instance from a file or stream (STDIN) with appropriate metadata:

ze up

Run the following command for a complete list of upload options:

ze up -help

Run the following command for a complete list of ze command options:

ze -help

Examples

Ingest three log files associated with the same support case "sr12345" (does not assume a .ze configuration file exists):

ze up --file=/casefiles/sr12345/messages.log --svcgrp=sr12345 --host=node01 --log=messages --url=<ZE_LOG_COLLECTOR_URL> --auth=<ZE_LOG_COLLECTOR_TOKEN>

ze up --file=/casefiles/sr12345/application.log --svcgrp=sr12345 --host=node01 --log=application --url=<ZE_LOG_COLLECTOR_URL> --auth=<ZE_LOG_COLLECTOR_TOKEN>

ze up --file=/casefiles/sr12345/db.log --svcgrp=sr12345 --host=db01 --log=db --url=<ZE_LOG_COLLECTOR_URL> --auth=<ZE_LOG_COLLECTOR_TOKEN>
Ingest a continuous tail of /var/log/messages. When reading from a stream, such as STDIN, rather than from a file, ze requires the –log flag (assumes a .ze configuration file exists):

tail -f /var/log/messages | ze up --log=varlogmsgs --svcgrp=monitor01 --host=mydbhost

Batch Uploads

The ze tool supports batch uploads. For more information, see Zebrium batch uploads and ze CLI.

Migrating from the Perl-based ze Tool (version 1.0.0)

The previous Perl-based application, version 1.0.0 of the ze tool, can be found at https://github.com/zebrium/ze-cli/tree/master/bin.

Replacing the .zerc File

Starting with version 2.0.0 of the ze tool, the .zerc file was replaced with a .ze file that accepts the configuration in yaml. This is described in the version 1.0.0 Configuration section: https://github.com/zebrium/ze-cli#configuration-file.

As a result, the configurations that were specified as:

url=<ZE_LOG_COLLECTOR_URL>

auth=<ZE_LOG_COLLECTOR_TOKEN>

will now need to be listed as the following:

url: <ZE_LOG_COLLECTOR_URL>

auth: <ZE_LOG_COLLECTOR_TOKEN>

Environment Variables

The ze tool now supports setting the following environment variables:

ZE_URL = <ZE_LOG_COLLECTOR_URL>

ZE_AUTH = <ZE_LOG_COLLECTOR_TOKEN>