-
Notifications
You must be signed in to change notification settings - Fork 88
Configuring Logging
Imperative CLI Framework uses log4js as a framework for logging. Logging is available after Imperative.init()
and in your command handlers.
You can direct logs to be written to the same log file that is used by Imperative CLI Framework or to a custom log file that contains information that is relevant to the application and is isolated from the imperative log files. You can control the log file names to use, the level of logging, and to which log files the data is written using the logging configuration. The level of logging (for example, TRACE
, DEBUG
, INFO
, and so on) are also controllable programmatically.
The Imperative configuration document allows you to configure logging via the logging
property. See the IImperativeLogsConfig interface for full typedoc.
To set up Imperative CLI Framework, configure the following configuration files:
-
IImperativeLoggingConfig.ts
(Imperative CLI Framework Logging):The following example illustrates how to configure the
IImperativeLoggingConfig.ts
configuration file:export interface IImperativeLoggingConfig { /** * Specify a log level name. An app's logging object is accessible via the * Imperative.api.appLogging object. * * Default will direct log output to * ~/.<app-name>/logs/<app-name>.log * * <app-name> is controlled via "name" setting in IImperativeConfig. */ logFile?: string; /** * Select a specific log level setting, for example, if a log setting of "fatal" * is used, only "fatal" level messages will appear within the log. However, * if "debug" level messages are selected, "debug", "info", "warn", "error", * and "fatal" messages will appear within the log. * * Accepted values are: * trace, debug, info, warn, error, fatal * * Default: * debug */ level?: string; /** * "imperative", "app", and "console" are reserved. Use this field to * create additional log API entities. * There is no default. This field is required when defining extra entries, * and its content is ignored for predefined loggers (imperative, console, and app loggers) */ apiName?: string;
-
IImperativeLogsConfig.ts
(Imperative CLI Framework Logs):The following example illustrates how to configure the
IImperativeLogsConfig.ts
configuration file:export interface IImperativeLogsConfig { /** * Use this property to configure imperative logging preferences. Defaults are provided and this * property must only be supplied to override defaults. See the IImperativeLoggingConfig document for more * information. */ imperativeLogging?: IImperativeLoggingConfig; /** * Use this property to configure your applications logging preferences. Defaults are provided and this * property must only be supplied to override defaults. See the IImperativeLoggingConfig document for more * information. */ appLogging?: IImperativeLoggingConfig; /** * Use this property to configure additional log files and preferences if needed. */ additionalLogging?: IImperativeLoggingConfig[]; [key: string]: any; }
-
IImperativeConfig.ts
(Imperative CLI Framework Command Line Application Configuration): The following interface illustrates how to configure your command line application to use Imperative CLI Framework, includingIImperativeConfig.ts
.
The following examples illustrate how to configure logging using the logging API.
Use the following syntax:
import { Imperative } from "@brightside/imperative";
const appLogger = Imperative.api.appLogger;
appLogger.debug("My debug data");
Use the following syntax:
import { Imperative } from "@brightside/imperative";
const imperativeLogger = Imperative.api.imperativeLogger;
imperativeLogger.debug("My debug data");
Use the following syntax:
import { Imperative } from "@brightside/imperative";
const consoleLogger = Imperative.api.consoleLogger;
consoleLogger.debug("My debug data");
Important!: Use console logging for only debugging purposes. You should remove console logging after you diagnose the problem. We recommend this approach because console logging can become interleaved with JSON output commands that are invoked with --response-format-json
, which prevents the output from being parsed properly.
You cannot create the Imperative CLI Framework API object when Imperative.init()
fails. As a result, you cannot use the Imperative.api
logging objects. Optionally, you can use Imperative.console
to write error messages and issue general debugging messages when Imperative.init()
fails.
The following syntax illustrates the syntax that you can use when Imperative.init()
fails:
import { Imperative } from "@brightside/imperative";
Imperative.defaultConsole.debug("My debug data");
Imperative.console.debug("My debug data");
-
Core Features
- Imperative Configuration
- Defining Commands
- Command Handlers
- Command Option Precedence
- Environment Variables
- Help Generator
- Experimental Commands
- Creating Commands Using Chained Handlers
- Configuring Logging
- Working with Team Configuration
- Defining and Programming Profiles
- Managing Secure Properties
- Deprecated User Profiles
- Consuming REST APIs Using the REST Client
- Implementing Progress Bars
- Plugins