opscode-analytics-ctl (executable)¶
Note
This documentation is meant to support existing Chef customers using Analytics.
If you are a new Chef customer, or are looking to gain better insight into your fleet, try Chef Automate. You’ll get a graphical interface and query language that gives you insight into operational, compliance, and workflow events. Download Chef Automate here.
The Chef Analytics installations that are done using the Chef installer include a command-line utility named opscode-analytics-ctl. This command-line tool is used to start and stop individual services, reconfigure the Chef Analytics server, run smoke tests, and tail the Chef Analytics log files.
Note
This feature is included as part of the Chef Automate license agreement and is available via subscription.
cleanse¶
The cleanse
subcommand is used to re-set the server to the state it was in before the first time the reconfigure
subcommand is run to destroy all data, configuration files, and logs.
This subcommand has the following syntax:
$ opscode-analytics-ctl cleanse
help¶
The help
subcommand is used to print a list of all available opscode-analytics-ctl commands.
This subcommand has the following syntax:
$ opscode-analytics-ctl help
preflight-check¶
The preflight-check
subcommand is check that all configuration files have been copied over from the Chef server when configured for a standalone deployment. This subcommand has the following syntax:
$ opscode-analytics-ctl preflight-check
and will return details on any missing required configuration and the following exit codes:
Exit Code | Description |
---|---|
0 |
Success. |
1 |
Error. |
2 |
Warning. |
purge-node¶
Chef Analytics stores Ohai data for every chef-client run. This data often takes up a considerable amount of disk space in PostgreSQL, which may lead to capacity and performance issues. A purge-nodes
command has been added to opscode-analytics-ctl
, which destructively removes node data from PostgreSQL.
To purge the Chef Analytics database of node information, run the following commands:
$ opscode-analytics-ctl stop
$ opscode-analytics-ctl start postgresql
$ opscode-analytics-ctl purge-nodes
This command may take some time to run. Upon completion, restart Chef Analytics:
$ opscode-analytics-ctl start
reconfigure¶
The reconfigure
subcommand is used when changes are made to the opscode-analytics.rb file to reconfigure the server. When changes are made to the opscode-analytics.rb file, they will not be applied to the Chef Analytics configuration until after this command is run. This subcommand will also restart any services for which the service_name['enabled']
setting is set to true
.
This subcommand has the following syntax:
$ opscode-analytics-ctl reconfigure
show-config¶
The show-config
subcommand is used to view the configuration that will be generated by the reconfigure
subcommand. This command is most useful in the early stages of a deployment to ensure that everything is built properly prior to installation.
This subcommand has the following syntax:
$ opscode-analytics-ctl show-config
uninstall¶
The uninstall
subcommand is used to remove the Chef Analytics application, but without removing any of the data. This subcommand will shut down all services (including the runit
process supervisor).
This subcommand has the following syntax:
$ opscode-analytics-ctl uninstall
Note
To revert the uninstall
subcommand, run the reconfigure
subcommand (because the start
subcommand is disabled by the uninstall
command).
Service Subcommands¶
This command has a built in process supervisor that ensures all of the required services are in the appropriate state at any given time. The supervisor starts two processes per service and provides the following subcommands for managing services: hup
, int
, kill
, once
, restart
, service-list
, start
, status
, stop
, tail
, and term
.
hup¶
The hup
subcommand is used to send a SIGHUP
to all services. This command can also be run for an individual service by specifying the name of the service in the command.
This subcommand has the following syntax:
$ opscode-analytics-ctl hup name_of_service
where name_of_service
represents the name of any service that is listed after running the service-list
subcommand.
int¶
The int
subcommand is used to send a SIGINT
to all services. This command can also be run for an individual service by specifying the name of the service in the command.
This subcommand has the following syntax:
$ opscode-analytics-ctl int name_of_service
where name_of_service
represents the name of any service that is listed after running the service-list
subcommand.
kill¶
The kill
subcommand is used to send a SIGKILL
to all services. This command can also be run for an individual service by specifying the name of the service in the command.
This subcommand has the following syntax:
$ opscode-analytics-ctl kill name_of_service
where name_of_service
represents the name of any service that is listed after running the service-list
subcommand.
once¶
The supervisor for Chef Analytics is configured to restart any service that fails, unless that service has been asked to change its state. The once
subcommand is used to tell the supervisor to not attempt to restart any service that fails.
This command is useful when troubleshooting configuration errors that prevent a service from starting. Run the once
subcommand followed by the status
subcommand to look for services in a down state and/or to identify which services are in trouble. This command can also be run for an individual service by specifying the name of the service in the command.
This subcommand has the following syntax:
$ opscode-analytics-ctl once name_of_service
where name_of_service
represents the name of any service that is listed after running the service-list
subcommand.
restart¶
The restart
subcommand is used to restart all services enabled on Chef Analytics or to restart an individual service by specifying the name of that service in the command.
This subcommand has the following syntax:
$ opscode-analytics-ctl restart name_of_service
where name_of_service
represents the name of any service that is listed after running the service-list
subcommand. When a service is successfully restarted the output should be similar to:
$ ok: run: service_name: (pid 12345) 1s
service-list¶
The service-list
subcommand is used to display a list of all available services. A service that is enabled is labeled with an asterisk (*).
This subcommand has the following syntax:
$ opscode-analytics-ctl service-list
start¶
The start
subcommand is used to start all services that are enabled in Chef Analytics. This command can also be run for an individual service by specifying the name of the service in the command.
This subcommand has the following syntax:
$ opscode-analytics-ctl start name_of_service
where name_of_service
represents the name of any service that is listed after running the service-list
subcommand. When a service is successfully started the output should be similar to:
$ ok: run: service_name: (pid 12345) 1s
The supervisor for the Chef server is configured to wait seven seconds for a service to respond to a command from the supervisor. If you see output that references a timeout, it means that a signal has been sent to the process, but that the process has yet to actually comply. In general, processes that have timed out are not a big concern, unless they are failing to respond to the signals at all. If a process is not responding, use a command like the kill
subcommand to stop the process, investigate the cause (if required), and then use the start
subcommand to re-enable it.
status¶
The status
subcommand is used to show the status of all services available to Chef Analytics. The results will vary based on the configuration of a given server. This subcommand has the following syntax:
$ opscode-analytics-ctl status
and will return the status for all services. Status can be returned for individual services by specifying the name of the service as part of the command:
$ opscode-analytics-ctl status name_of_service
where name_of_service
represents the name of any service that is listed after running the service-list
subcommand.
When service status is requested, the output should be similar to:
$ run: service_name: (pid 12345) 12345s; run: log: (pid 1234) 67890s
where
run:
is the state of the service (run:
ordown:
)service_name:
is the name of the service for which status is returned(pid 12345)
is the process identifier12345s
is the uptime of the service, in seconds
For example:
$ down: actions: (pid 35546) 10s
By default, runit will restart services automatically when the services fail. Therefore, runit may report the status of a service as run:
even when there is an issue with that service. When investigating why a particular service is not running as it should be, look for the services with the shortest uptimes. For example, the list below indicates that the actions should be investigated further:
run: actions: (pid 6361) 4132s; run: log: (pid 6173) 4146s
run: actions_consumer: (pid 6374) 5s; run: log: (pid 6227) 4139s
run: actions_messages: (pid 6392) 4131s; run: log: (pid 6324) 4133s
run: memcached: (pid 6115) 4157s; run: log: (pid 6129) 4156s
Log Files¶
A typical status line for a service that is running in Chef Analytics in a combined or standalone topology is similar to the following:
run: name_of_service: (pid 1486) 7819s; run: log: (pid 1485) 7819s
where:
run
describes the state in which the supervisor attempts to keep processes. This state is eitherrun
ordown
. If a service is in adown
state, it should be stoppedname_of_service
is the service name, for example:actions
(pid 1486) 7819s;
is the process identifier followed by the amount of time (in seconds) the service has been runningrun: log: (pid 1485) 7819s
is the log process. It is typical for a log process to have a longer run time than a service; this is because the supervisor does not need to restart the log process in order to connect the supervised process
If the service is down, the status line will appear similar to the following:
down: actions: 3s, normally up; run: log: (pid 1485) 8526s
where
down
indicates that the service is in a down state3s, normally up;
indicates that the service is normally in a run state and that the supervisor would attempt to restart this service after a reboot
stop¶
The stop
subcommand is used to stop all services enabled on Chef Analytics. This command can also be run for an individual service by specifying the name of the service in the command.
This subcommand has the following syntax:
$ opscode-analytics-ctl stop name_of_service
where name_of_service
represents the name of any service that is listed after running the service-list
subcommand. When a service is successfully stopped the output should be similar to:
$ ok: diwb: service_name: 0s, normally up
For example:
$ opscode-analytics-ctl stop
will return something similar to:
ok: down: actions: 1s, normally up
ok: down: actions_consumer: 0s, normally up
ok: down: actions_messages: 0s, normally up
ok: down: memcached: 1s, normally up
tail¶
The tail
subcommand is used to follow all Chef Analytics logs for all services. This command can also be run for an individual service by specifying the name of the service in the command.
This subcommand has the following syntax:
$ opscode-analytics-ctl tail name_of_service
where name_of_service
represents the name of any service that is listed after running the service-list
subcommand.
term¶
The term
subcommand is used to send a SIGTERM
to all services. This command can also be run for an individual service by specifying the name of the service in the command.
This subcommand has the following syntax:
$ opscode-analytics-ctl term name_of_service
where name_of_service
represents the name of any service that is listed after running the service-list
subcommand.