basant307/AI_Governance_Project

1# Google Logging Tools2 3## About4This package defines an ad-hoc debug logger utility that can be used as a lightweight alternative to "printf debugging" via `console.log`, and provides more, and more structured information. It is based largely on the ideas of the Node `util.debuglog` function, and the `debug` npm package.5 6## Contracts7These are logging utilities meant primarily for use as an "adhoc debug logger" inside Google libraries. It's possible to use this outside of that context, but it is currently not supported. (You're on your own.)8 9Additionally, everything about the debug logging is not intended to be a stable interface - you can't rely on messages to remain the same, or to continue to exist from one version to the next. For now, it is meant to be a tool for local usage by users, to get the equivalent of "printf debugging" output. In the future, it may tie into more things (OpenTelemetry Logging, etc). Structured log output is possible for vacuuming into Cloud Logging.10 11This npm package itself is intended to follow semver standards for its own interfaces, but no guarantees are made for supported time windows, etc.12 13## Usage14The user interface for this logging is very similar to Node's built-in logging. The primary unit of logging is called a "system", and some libraries may have sub-units called "subsystems". You separate the system and subsystem with a colon, like "pubsub:leasing" or similar. Wildcards may be used (e.g. "pubsub:*"), and multiple of these system/system:subsystem pairs may be listed out, separated by commas. For generated GAPIC libraries, the "system" will generally be the part of the package name specific to the library (e.g. `@google-cloud/translate` will be `translate`).15 16The environment variable for activating logging is `GOOGLE_SDK_NODE_LOGGING`. So you could run your application similarly to this:17 18```19GOOGLE_SDK_NODE_LOGGING=translate node yourApp.js20```21 22Or even enable everything, though you might end up with a firehose if you have multiple libraries as dependencies:23 24```25GOOGLE_SDK_NODE_LOGGING=* node yourApp.js26```27 28## Logging29Logging functions are created by calling the `log()` function. You pass a system or system:subsystem identifier, and a function is returned. This function may be called directly:30 31```32const logger = log('test');33logger({other:{metadata: 'foo'}}, 'format string %j', {formatted: 'parameter'});34```35 36You may also call shorthands that set the `severity` metadata field, and use defaults for the metadata object generally:37 38```39logger.debug('format string %s', 'string');40logger.info('format string %s', 'string');41logger.warn('format string %s', 'string');42logger.error('format string %s', 'string');43```44 45Finally, the logger function may be used to create a "sub-log", i.e. adding a sub-system to a system:46 47```48const sublogger = logger.sublog('specific');49logger.info('big one');50sublogger.info('specific!');51```52 53This will output two logs, filed under `test` and `test:specific`, respectively.54 55## Backends56Additionally, there is a concept of a logging backend. You can manually set where you want logs to go, by default, and how you want them processed. The `setBackend()` function lets you set a backend manually. `undefined` (reset to defaults) and `null` (disable logging) are also possible options.57 58The package provides several built-in options:59 60* `getNodeBackend()` This is the default that comes with setting the environment variable. It detects the possibility of coloration in the terminal and formats outputs using `util.format()`.61* `getDebugBackend(debugpkg)` This interfaces with the `debug` npm package. You'd essentially do something like `setBackend(getDebugBackend(require('debug')))`.62* `getStructuredBackend(upstream?)`. This converts log output into structured log JSON objects, suitable for feeding into Cloud Logging. An optional `upstream` parameter lets you funnel the output through another backend instead of `console.log`.63 64## Hooking logs65The log objects you receive from calling `log()` can be hooked as event emitters, like so:66 67```68loggingFunc.on('log', (fields: LogFields, args: unknown[]) => {69  // Process logs as you like.70});71```72 73This will not prevent normal log output, and system/system:subsystem identifiers will be cached to make sure that all logs of the same name will output to the same event handlers.74