Chronoctl

Chronoctl is a Chronosphere-supplied app that lets you manage your organization's Chronosphere Observability Platform resources from the command line.

For example, to list your team's monitor definitions:

chronoctl monitors list

Getting started

To install Chronoctl, see Install Chronoctl.

To use Chronoctl, you must provide an API token and organization name to authenticate as an account with administrative privileges, either by configuring them as environment variables or passing them with the command. You can also securely authenticate by using the chronoctl auth command.

After you're ready to use Chronoctl, refer to its commands to directly control your Observability Platform environment.

Supported resources

Use Chronoctl commands to take actions on Observability Platform resources, such as dashboards, teams, or collections. To display a list of the resources supported by your installed version of Chronoctl, view the Chronoctl help:

chronoctl --help

The list of available resources displays in the Chronosphere Configuration section of the output.

Command list

Requires Chronoctl version 0.53.0 or later.

Chronoctl is based on the structure of the Chronosphere API, which helps its commands be as consistent with one another as possible. This also better reflects features as they're presented for use in the Chronosphere API itself.

Flags

Each command has several flags for customizing its output or behavior.

In addition to the authentication flags, flags that are common among commands include:

• -h, --help: Outputs help text for the given command.
• --timeout: Defines a duration in seconds for the request before it times out and fails. Defaults to 30 seconds.

Chronoctl commands that return data representations of resources have additional common flags:

• -o, --output: Defines the output format. Accepts json for JSON, jsonl for JSON Lines, or defaults to yaml for YAML.

Chronoctl commands that can change the state of a resource in Observability Platform, such as chronoctl apply or resource create and update subcommands, also have:

• -d, --dry-run: If set, Chronoctl simulates but doesn't apply the manifest or change in a dry run, and then displays the predicted result.
• --no-strict: If set, Chronoctl accepts manifests or changes that contain unknown fields.

Slugs

Observability Platform identifies each resource by a unique slug, which has a 255-character length limit and contains only letters, numbers, underscores (_), and dashes (-). Slugs are case-sensitive. By default, Observability Platform generates a random slug (containing less than 255 characters) for each resource. Chronoctl lets you optionally specify a slug when creating resources.

Configuration commands

Configuration commands are the recommended way to interact with Observability Platform resources. Use the apply command for interacting with multiple resources, but in most cases, uses the configuration commands.

Each of these commands are specific to Observability Platform resource types, which have the same following subcommands:

• create
• delete
• list
• read
• scaffold
• update

create

Creates one resource of the given type. For example:

chronoctl RESOURCE create -f FILE_NAME.yaml

Replace the following:

• RESOURCE: The resource you want to take action on.
• FILE_NAME: The name of the definition file you want to use.

For more information about the subcommand, including its usage and accepted flags, see the Chronoctl command line help.

chronoctl RESOURCE create --help

Replace RESOURCE with the resource you want to take action on.

delete

Deletes one resource of the given type. For example:

chronoctl RESOURCE delete SLUG

Replace the following:

• RESOURCE: The resource you want to take action on.
• SLUG: The slug of the resource you want to delete.

For more information about the subcommand, including its usage and accepted flags, see the Chronoctl command line help.

chronoctl RESOURCE delete --help

Replace RESOURCE with the resource you want to take action on.

list

Lists all resources of the given type. For example:

chronoctl RESOURCE list

Replace RESOURCE with the resource you want to take action on.

For more information about the subcommand, including its usage and accepted flags, see the Chronoctl command line help.

chronoctl RESOURCE list --help

Replace RESOURCE with the resource you want to take action on.

read

Outputs one resource of the given type. For example:

chronoctl RESOURCE read SLUG

Replace the following:

• RESOURCE: The resource you want to take action on.
• SLUG: The slug of the resource you want to output.

For more information about the subcommand, including its usage and accepted flags, see the Chronoctl command line help.

chronoctl RESOURCE read --help

Replace RESOURCE with the resource you want to take action on.

scaffold

Outputs an example resource definition of the given type, including inline comments documenting its properties. For example:

chronoctl RESOURCE scaffold

Replace RESOURCE with the resource you want to take action on.

update

Updates a resource of the given type. For example:

chronoctl RESOURCE update -f FILE_NAME.yaml

Replace the following:

• RESOURCE: The resource you want to take action on.
• FILE_NAME: The name of the definition file you want to use.

For more information about the subcommand, including its usage and accepted flags, see the Chronoctl command line help.

chronoctl RESOURCE update --help

Replace RESOURCE with the resource you want to take action on.

Core commands

Chronoctl core commands are independent of any resource type.

apply

Applies a configuration change to resources from a YAML or JSON file, or from standard input. When you apply resources with Chronoctl, Observability Platform creates them if they don't already exist.

The apply command accepts input from a file by providing the path as the value of the -f (--filename) flag.

For example, to apply a file containing a resource's YAML manifest:

chronoctl apply -f resources.yml

To apply a resource passed from standard input, use the - value of the -f flag:

chronoctl apply -f -

Upon success, the command returns the list of changes applied.

The apply command accepts the dry run (-d, --dry-run) flag, which displays the changes without applying them.

chronoctl apply -f resources.yml -d

auth

Requires Chronoctl version 1.8.0 or later (or Chronoctl 0.65.0 or later if you're using a version earlier than 1.0.0).

Handles secure programmatic access to Observability Platform. This command lets users access their organizations' applications after authentication with Chronoctl.

• login: Authenticate the Chronoctl session as your Observability Platform user.
• list: List all authenticated Observability Platform organizations the current user can access. Users might have access to multiple organizations such as a production and a test organization.
• print-session-id: Print the stored session id for an Observability Platform organization.
• set-default-org: Sets the default Observability Platform organization for future commands.

To sign in, use this command:

chronoctl auth login --org-name YOUR-ORG-NAME

Replace YOUR-ORG-NAME with the organization you want to sign in to. For example, if your Observability Platform tenant is https://acme.chronosphere.io, replace YOUR-ORG-NAME with acme, and then follow the prompts.

This process generates a session_ID, which is cached on your machine and valid for 24 hours. If a personal access token or service account token isn't passed to Chronoctl using an environment variable or command line flag, Chronoctl uses the cached session_ID to authenticate your command.

State commands

These commands evaluate the current state of Observability Platform.

rule-evaluations list

The list subcommand is the only subcommand for rule-evaluations.

Returns a list of rule evaluation failures, including the rule's type, slug, failure count, message, and detection timestamp.

Sync commands

The sync command accepts the prometheus subcommand only. Use the sync prometheus command to sync a Prometheus rules YAML file and a Prometheus Alertmanager YAML configuration file into Chronosphere format.

You include a chronoconfig.yaml file to assign the rules to a team, and to specify a team to own the related notification policy. This command converts and applies the assets and resources to your tenant.

chronoctl sync prometheus

To sync Prometheus rules into Chronosphere format:

1. Define a chronoconfig.yaml file to assign the converted rules to a team, and specify a team to own the related notification policy:

   use_collections: "TRUE"
   group_teams:
     - group_regex: ".*"
       team_slug: "OWNER_TEAM"
   notification_policy_team_slug: "POLICY_TEAM"

   Replace the following:

   • OWNER_TEAM: The slug of the Observability Platform team to own the converted rules.
   • POLICY_TEAM: The slug of the Observability Platform team to own the notification policy.

2. Run the sync prometheus command and pass in your Prometheus rules file, Prometheus Alertmanager configuration file, and chronoconfig.yaml file:

   chronoctl sync prometheus -a [ALERTMANAGER_CONFIG] -p [PROM_RULES] -c chronoconfig.yaml [FLAGS]

   Replace the following:

   • ALERTMANAGER_CONFIG: The file containing your Prometheus Alertmanager configuration.
   • PROM_RULES: The file containing your Prometheus rules.
   • FLAGS: Any flags to include with the command. Run chronoctl sync prometheus --help to display supported flags.

Additional commands

These commands provide additional information as you use Chronoctl.

help

Displays help text for the tool and any specified subcommand.

chronoctl help

version

Displays the version, revision, build date, and Go version for Chronoctl. Provide this information when reporting an issue with Chronoctl to Chronosphere Support.

chronoctl version

Command autocompletion

You can add support for shell command autocompletion with Chronoctl for the Bash, Zsh, Fish, and PowerShell by using the chronoctl completion command.

This section provides detailed steps for Bash and Zsh on macOS. For Linux-specific details and instructions for Fish and PowerShell, see the output of chronoctl help completion.

You can now press Tab on the command line to automatically complete Chronoctl commands.