Chronoctl

Chronoctl

Chronoctl, the Chronosphere command-line tool, helps you manage your organization's Chronosphere resources. For example, you can use it to inspect and update your team's Monitor definitions.

Chronosphere prevents users from modifying Terraform-managed resources in the user interface, with Chronoctl, or by using the API. For details, see the Terraform provider documentation.

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.

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

Command list

Chronoctl v0.53.0 changed the structure and options of commands to make them more consistent with each other, and to better reflect features in the Chronosphere API.

This list doesn't match the commands available in older versions of Chronoctl. To view the commands available in an older version of Chronoctl, Refer to its built-in help text by running chronoctl help or chronoctl -h.

Likewise, commands that worked in older versions of Chronoctl still work, but produce a deprecation warning because Chronosphere will remove them in a future version.

Newer versions of Chronoctl also change the format for resource output to be more consistent with the Chronosphere API. To review your existing resources in the new format, run the list subcommand for the resource type that you want to review, such as chronoctl monitors list to list all monitors.

If you've stored Chronoctl YAML or JSON code representations of resources, you must update them to the new format to apply them using the new version of Chronoctl.

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 Chronosphere, 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

Chronosphere 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, Chronosphere generates a random slug for each resource. Chronoctl lets you optionally specify a slug when creating resources.

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, Chronosphere 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

convert

Converts configuration files for other tools into their equivalent consolidated Chronosphere configuration files. The convert command supports:

  • Prometheus rules (-p, --prometheusFile)
  • Alertmanager configurations (-a, --alertmanagerFile)
  • Grafana 7.5 dashboards, which Chronoctl converts by the directory (-D, --directory`)

For example, to convert a Prometheus rules file and Alertmanager configuration to Chronosphere-compatible YAML:

chronoctl convert prometheus -p prometheus_rules.yml -a alertmanager.yml

To write a separate file for each Chronosphere object to a specified directory, use the --create-file-per-object flag, with the optional --output-dir flag to specify where to write the files:

chronoctl convert prometheus -p prometheus_rules.yml -a alertmanager.yml --output-dir=out --create-file-per-object

Files from this command use the naming convention <OBJECT_TYPE>_<SLUG_NAME> followed by the format extension.

To output to Chronosphere configuration format, use the -c (--chronoConfigFile) flag:

chronoctl convert prometheus -p prometheus_rules.yml -a alertmanager.yml -c chronoconfig.yml

When converting Grafana dashboards, use these additional flags to further configure the result:

  • --bucket-slug: Adds the dashboards to the bucket with the same slug as this flag's value.
  • --graphite-datasource and --prometheus-datasource: By default, Chronoctl replaces all data sources in a converted dashboard with Chronosphere's equivalent data sources. To force Chronosphere to replace only the data sources that have a specific name, provide it as the value to these flags for Graphite and Prometheus data source types, respectively.
  • --rename-duplicate-titles-mode: If given the value directory, Chronoctl prefixes dashboards that have duplicate titles with their Grafana folder name. If given the value autoincrement, Chronoctl appends an incrementing number to duplicate titles. Use this flag only if the input preserves the externally hosted Grafana instance's folder structure. Otherwise, title uniqueness cannot be guaranteed.
  • --skip-version-check: By default, Chronoctl confirms that the provided Grafana dashboard is from a supported Grafana version, which is 7.5.17 or lower. Use this flag To force Chronoctl to convert a dashboard from a newer Grafana version. This might result in a dashboard that Chronosphere cannot import.

When converting Alertmanager rules, you can use the optional --alerting-format flag to define the result's alerting format. The value defaults to auto but can be monitors or alert-groups.

search

Searches for metrics used across all supported Chronosphere resources. This command requires the use of the --metric-regex flag, which takes a regular expression as a value and attempts to match it against metrics in Chronosphere.

For example, to search for the use of collector metrics in dashboards, monitors, recording rules, rollup rules, drop rules, and mapping rules:

chronoctl search --metric-regex "collector"

To search for Collector latency metrics:

chronoctl search --metric-regex "collector.+latency"

sync prometheus

The sync command contains a single subcommand, sync prometheus, which synchronizes Prometheus and Alertmanager settings with Chronosphere. This command reads the given Alertmanager and Prometheus configurations and converts them into their equivalent Chronosphere entities, which lets you use those configurations as your source of truth for Chronosphere's configuration.

Chronoctl compares the Chronosphere configuration with the input, applies the required changes, and marks all of the synchronized entities as created or updated by the synchronization process. This ensures that on future runs of the sync prometheus command, Chronosphere can delete any entities that are no longer present in Prometheus or Alertmanager.

To use sync prometheus, provide it with:

For example, to synchronize Prometheus rules and Alertmanager rules stored in prometheus_rules.yml and alertmanager.yml, respectively:

chronoctl sync prometheus -p prometheus_rules.yml -a alertmanager.yml

Configuration commands

Configuration commands are specific to Chronosphere resource types:

  • buckets
  • dashboards
  • derived-labels
  • derived-metrics
  • drop-rules
  • grafana-dashboards
  • mapping-rules
  • monitors
  • muting-rules
  • notification-policies
  • notifiers
  • recording-rules
  • rollup-rules
  • service-accounts
  • teams

Each resource type has the same subcommands.

create

Creates one resource of the given type.

The create subcommand accepts the common flags of commands that can change the Chronosphere state, and the -f (--filename) flag similar to the apply command.

To create resources that require SysAdmin access, such as teams and accounts, you must authenticate as a user or service account that's a member of a team with SysAdmin access.

delete

Creates one resource of the given type that has the specified slug.

The delete subcommand accepts the common flags of commands that can change the Chronosphere state.

To delete resources that require SysAdmin access, such as teams and accounts, you must authenticate as a user or service account that's a member of a team with SysAdmin access.

list

Lists all resources of the given type.

The list subcommand also accepts these flags:

  • --create-file-per-object: Generates a file for each resource, with the optional --output-dir flag to specify where to write the files.
  • --limit: Defines the limit of many resources to return.
  • --names, --slugs: Returns results by their resource name or slug, respectively.
  • --page-token: Begins listing resources from the start of a given pagination token.

Additionally, for grafana-dashboards, mapping-rules, monitors, notification-policies, recording-rules, and rollup-rules:

  • --bucket-slugs: Lists rules associated with the given bucket.

read

Outputs one resource of the given type that has the specified slug.

The read subcommand accepts the common flags of commands that only read the Chronosphere state.

scaffold

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

For example, to output an example recording rule:

chronoctl recording-rules scaffold

update

Updates a resource of the given type.

The update subcommand accepts the common flags of commands that can change Chronosphere state, and the -f (--filename) flag similar to the apply command, and a --create-if-missing flag that creates the given resource if it doesn't already exist.

The create and update subcommands all use the common flags for commands that can change Chronosphere state.

To update resources that require SysAdmin access, such as teams and accounts, you must authenticate as a user or service account that's a member of a team with SysAdmin access.

State commands

These commands evaluate the current state of Chronosphere.

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.

Additional commands

The chronoctl help command displays help text for the tool and any given subcommand.

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

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.

  1. Update or install bash-completion:

    brew install bash-completion
  2. In a shell initialization script, such as ~/.bashrc, add the following:

    source "$(brew --prefix bash-completion)/etc/bash_completion"
    eval "$(chronoctl completion bash)"
  3. Restart the shell.

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

Manage v2 alerts

If you still use the deprecated v2 version of alerts, you can still create and manage those alerts with Chronoctl. See Manage v2 alerts with Chronoctl.