Module: Kitchen
- Defined in:
- lib/kitchen.rb,
lib/kitchen/cli.rb,
lib/kitchen/ssh.rb,
lib/kitchen/util.rb,
lib/kitchen/color.rb,
lib/kitchen/suite.rb,
lib/kitchen/config.rb,
lib/kitchen/driver.rb,
lib/kitchen/errors.rb,
lib/kitchen/logger.rb,
lib/kitchen/command.rb,
lib/kitchen/logging.rb,
lib/kitchen/version.rb,
lib/kitchen/instance.rb,
lib/kitchen/platform.rb,
lib/kitchen/verifier.rb,
lib/kitchen/lazy_hash.rb,
lib/kitchen/shell_out.rb,
lib/kitchen/transport.rb,
lib/kitchen/collection.rb,
lib/kitchen/diagnostic.rb,
lib/kitchen/rake_tasks.rb,
lib/kitchen/state_file.rb,
lib/kitchen/thor_tasks.rb,
lib/kitchen/data_munger.rb,
lib/kitchen/driver/base.rb,
lib/kitchen/loader/yaml.rb,
lib/kitchen/provisioner.rb,
lib/kitchen/command/exec.rb,
lib/kitchen/command/list.rb,
lib/kitchen/command/sink.rb,
lib/kitchen/command/test.rb,
lib/kitchen/configurable.rb,
lib/kitchen/driver/dummy.rb,
lib/kitchen/driver/proxy.rb,
lib/kitchen/base64_stream.rb,
lib/kitchen/command/login.rb,
lib/kitchen/login_command.rb,
lib/kitchen/transport/ssh.rb,
lib/kitchen/verifier/base.rb,
lib/kitchen/command/action.rb,
lib/kitchen/generator/init.rb,
lib/kitchen/transport/base.rb,
lib/kitchen/verifier/dummy.rb,
lib/kitchen/verifier/shell.rb,
lib/kitchen/command/console.rb,
lib/kitchen/command/package.rb,
lib/kitchen/driver/ssh_base.rb,
lib/kitchen/transport/dummy.rb,
lib/kitchen/transport/winrm.rb,
lib/kitchen/verifier/busser.rb,
lib/kitchen/command/diagnose.rb,
lib/kitchen/metadata_chopper.rb,
lib/kitchen/provisioner/base.rb,
lib/kitchen/provisioner/dummy.rb,
lib/kitchen/provisioner/shell.rb,
lib/kitchen/provisioner/chef_base.rb,
lib/kitchen/provisioner/chef_solo.rb,
lib/kitchen/provisioner/chef_zero.rb,
lib/kitchen/provisioner/chef_apply.rb,
lib/kitchen/command/driver_discover.rb,
lib/kitchen/generator/driver_create.rb,
lib/kitchen/provisioner/chef/berkshelf.rb,
lib/kitchen/provisioner/chef/librarian.rb,
lib/kitchen/provisioner/chef/policyfile.rb,
lib/kitchen/provisioner/chef/common_sandbox.rb
Overview
Author:: Fletcher Nichol ([email protected])
Copyright (C) 2013, Fletcher Nichol
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
Defined Under Namespace
Modules: Base64Stream, Color, Command, Configurable, Driver, Error, Generator, Loader, Logging, Provisioner, ShellOut, Transport, Util, Verifier Classes: ActionFailed, CLI, ClientError, Collection, Config, DataMunger, Diagnostic, Instance, InstanceFailure, LazyHash, Logger, LoginCommand, MetadataChopper, Platform, RakeTasks, SSH, SSHFailed, StandardError, StateFile, StateFileLoadError, Suite, ThorTasks, TransientFailure, UserError
Constant Summary collapse
- DEFAULT_LOG_LEVEL =
Default log level verbosity
:info
- DEFAULT_LOG_OVERWRITE =
Overwrite the log file when Test Kitchen runs
true
- DEFAULT_TEST_DIR =
Default base directory for integration tests, fixtures, etc.
"test/integration".freeze
- DEFAULT_LOG_DIR =
Default base directory for instance and common log files
".kitchen/logs".freeze
- VERSION =
"1.14.2".freeze
Class Attribute Summary collapse
-
.logger ⇒ Logger
The common Kitchen logger.
-
.mutex ⇒ Mutex
A common mutex for global coordination.
Class Method Summary collapse
-
.debug_log(lines) ⇒ Object
private
Writes an array of lines to the common Kitchen debugger with debug severity.
-
.default_file_logger(level = nil, log_overwrite = nil) ⇒ Logger
Returns a default file logger which emits on standard output and to a log file.
-
.default_logger ⇒ Logger
Returns a default logger which emits on standard output.
-
.env_log ⇒ Symbol?
private
Determine the default log level from an environment variable, if it is set.
-
.env_log_overwrite ⇒ Boolean?
private
Determine the log overwriting logic from an environment variable, if it is set.
-
.file_log(level, lines) ⇒ Object
private
Writes an array of lines to the common Kitchen logger's file device at the given severity level.
-
.handle_error(e) ⇒ Object
private
Handles an unexpected failure exception.
-
.handle_instance_failure(e) ⇒ Object
private
Handles an instance failure exception.
-
.source_root ⇒ Pathname
Returns the root path of the Kitchen gem source code.
-
.stderr_log(lines) ⇒ Object
private
Writes an array of lines to the
STDERR
device. -
.tty? ⇒ true, false
Returns whether or not standard output is associated with a terminal device (tty).
-
.with_friendly_errors ⇒ Object
Yields to a code block in order to consistently emit a useful crash/error message and exit appropriately.
Class Attribute Details
.logger ⇒ Logger
Returns the common Kitchen logger.
58 59 60 |
# File 'lib/kitchen.rb', line 58 def logger @logger end |
.mutex ⇒ Mutex
Returns a common mutex for global coordination.
61 62 63 |
# File 'lib/kitchen.rb', line 61 def mutex @mutex end |
Class Method Details
.debug_log(lines) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Writes an array of lines to the common Kitchen debugger with debug severity.
217 218 219 |
# File 'lib/kitchen/errors.rb', line 217 def self.debug_log(lines) Array(lines).each { |line| Kitchen.logger.debug(line) } end |
.default_file_logger(level = nil, log_overwrite = nil) ⇒ Logger
Returns a default file logger which emits on standard output and to a log file.
83 84 85 86 87 88 89 90 91 92 93 94 95 |
# File 'lib/kitchen.rb', line 83 def default_file_logger(level = nil, log_overwrite = nil) level ||= env_log log_overwrite = log_overwrite.nil? ? env_log_overwrite : log_overwrite log_location = File.(File.join(DEFAULT_LOG_DIR, "kitchen.log")) log_location = log_location.to_s Logger.new( stdout: $stdout, logdev: log_location, level: Util.to_logger_level(level), log_overwrite: log_overwrite ) end |
.default_logger ⇒ Logger
Returns a default logger which emits on standard output.
73 74 75 |
# File 'lib/kitchen.rb', line 73 def default_logger Logger.new(stdout: $stdout, level: Util.to_logger_level(env_log)) end |
.env_log ⇒ Symbol?
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Determine the default log level from an environment variable, if it is set.
110 111 112 |
# File 'lib/kitchen.rb', line 110 def env_log ENV["KITCHEN_LOG"] && ENV["KITCHEN_LOG"].downcase.to_sym end |
.env_log_overwrite ⇒ Boolean?
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Determine the log overwriting logic from an environment variable, if it is set.
119 120 121 122 123 124 125 126 127 128 |
# File 'lib/kitchen.rb', line 119 def env_log_overwrite case ENV["KITCHEN_LOG_OVERWRITE"] && ENV["KITCHEN_LOG_OVERWRITE"].downcase when nil, "" nil when "false", "f", "no" false else true end end |
.file_log(level, lines) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Writes an array of lines to the common Kitchen logger's file device at the given severity level. If the Kitchen logger is set to debug severity, then the array of lines will also be written to the console output.
191 192 193 194 195 196 197 198 199 |
# File 'lib/kitchen/errors.rb', line 191 def self.file_log(level, lines) Array(lines).each do |line| if Kitchen.logger.debug? Kitchen.logger.debug(line) else Kitchen.logger.logdev && Kitchen.logger.logdev.public_send(level, line) end end end |
.handle_error(e) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Handles an unexpected failure exception.
238 239 240 241 242 243 |
# File 'lib/kitchen/errors.rb', line 238 def self.handle_error(e) stderr_log(Error.formatted_exception(e)) stderr_log("Please see .kitchen/logs/kitchen.log for more details") stderr_log("Also try running `kitchen diagnose --all` for configuration\n") file_log(:error, Error.formatted_trace(e)) end |
.handle_instance_failure(e) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Handles an instance failure exception.
226 227 228 229 230 231 |
# File 'lib/kitchen/errors.rb', line 226 def self.handle_instance_failure(e) stderr_log(e..split(/\s{2,}/)) stderr_log(Error.formatted_exception(e.original)) file_log(:error, e..split(/\s{2,}/).first) debug_log(Error.formatted_trace(e)) end |
.source_root ⇒ Pathname
Returns the root path of the Kitchen gem source code.
66 67 68 |
# File 'lib/kitchen.rb', line 66 def source_root @source_root ||= Pathname.new(File.("../../", __FILE__)) end |
.stderr_log(lines) ⇒ Object
This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.
Writes an array of lines to the STDERR
device.
205 206 207 208 209 210 |
# File 'lib/kitchen/errors.rb', line 205 def self.stderr_log(lines) Array(lines).map { |line| ">>>>>> #{line}" }.each do |line| line = Color.colorize(line, :red) if Kitchen.tty? $stderr.puts(line) end end |
.tty? ⇒ true, false
Returns whether or not standard output is associated with a terminal device (tty).
101 102 103 |
# File 'lib/kitchen.rb', line 101 def tty? $stdout.tty? end |
.with_friendly_errors ⇒ Object
Yields to a code block in order to consistently emit a useful crash/error message and exit appropriately. There are two primary failure conditions: an expected instance failure, and any other unexpected failures.
Note This method may call Kernel.exit
so may not return if the
yielded code block raises an exception.
Instance Failure
This is an expected failure scenario which could happen if an instance
couldn't be created, a Chef run didn't successfully converge, a
post-convergence test suite failed, etc. In other words, you can count on
encountering these failures all the time--this is Kitchen's worldview:
crash early and often. In this case a cleanly formatted exception is
written to STDERR
and the exception message is written to
the common Kitchen file logger.
Unexpected Failure
All other forms of Kitchen::Error
exceptions are considered unexpected
or unplanned exceptions, typically from user configuration errors, driver
or provisioner coding issues or bugs, or internal code issues. Given
a stable release of Kitchen and a solid set of drivers and provisioners,
the most likely cause of this is user configuration error originating in
the .kitchen.yml
setup. For this reason, the exception is written to
STDERR
, a full formatted exception trace is written to the common
Kitchen file logger, and a message is displayed on STDERR
to the user
informing them to check the log files and check their configuration with
the kitchen diagnose
subcommand.
170 171 172 173 174 175 176 177 178 179 180 181 182 |
# File 'lib/kitchen/errors.rb', line 170 def self.with_friendly_errors yield rescue Kitchen::InstanceFailure => e Kitchen.mutex.synchronize do handle_instance_failure(e) end exit 10 rescue Kitchen::Error => e Kitchen.mutex.synchronize do handle_error(e) end exit 20 end |