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
Users cannot modify Terraform-managed resources in the user interface, with Chronoctl, or by using the API. Learn more.
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.
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.
Versions of Chronoctl earlier than version 0.53.0 have a different set of commands
than what's documented here. To view the commands available in an older version of
Chronoctl, use its built-in help text by running chronoctl help
or chronoctl -h
.
Commands from older versions of Chronoctl work, but produce a deprecation warning. Chronosphere will remove deprecated commands in a future version.
Newer versions of Chronoctl change the resource output format to be more consistent
with the Chronosphere API. To review existing resources in this format, run
the list
subcommand for the resource type that you want to review.
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. Acceptsjson
for JSON,jsonl
for JSON Lines, or defaults toyaml
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:
The following syntax applies to all configuration commands:
chronoctl RESOURCE COMMAND
Replace the following variables:
RESOURCE
: The resource you want to take action on, such asdashboards
,monitors
, orteams
.COMMAND
: The subcommand you want to use, such ascreate
,delete
, orlist
.
create
Creates one resource of the given type.
The create
subcommand accepts the common flags of commands that can
change the Observability Platform 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, or start a session using chronoctl auth
.
For example, to create a monitor based on a monitor definition:
chronoctl monitors create -f FILE_NAME.yaml
Replace FILE_NAME
with the name of the definition file you want to use.
delete
Deletes one resource of the given type that has the specified slug.
The delete
subcommand accepts the common flags of commands that can
change the Observability Platform 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, or start a session using chronoctl auth
.
For example, to delete a monitor:
chronoctl monitors delete SLUG
Replace SLUG
with the slug of the monitor you want to delete.
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.
For example, to display a list of all monitors:
chronoctl monitors list
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 Observability Platform state.
For example, to read the trace behavior definition:
chronoctl trace-behavior-config read
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 Observability Platform 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 the Observability Platform 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, or start a session using chronoctl auth
.
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
Handles secure programmatic access to Observability Platform. This command enables users to access their organizations' applications after authentication with Chronoctl.
This command uses a session_ID
rather than an API token.
login
: Authenticate the Chronoctl session as your Observability Platform user.list
: List all authenticated Observability Platform organizations the current user can access. Users may 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 log in, use the command:
chronoctl auth login --org-name YOUR-ORG-NAME
Where YOUR-ORG-NAME
is the organization you want to log in to. 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 is not passed to Chronoctl
using an environment variable or command line flag, Chronoctl will use 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.
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
.
-
Update or install
bash-completion
:brew install bash-completion
-
In a shell initialization script, such as
~/.bashrc
, add the following:source "$(brew --prefix bash-completion)/etc/bash_completion" eval "$(chronoctl completion bash)"
-
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.