fix: DEBUG harmony

Author: erights

docs/env.md

@@ -64,11 +64,15 @@ If not set, then default (`console.info` and above) logging is enabled.
 If set to an empty string, or running in `ag-chain-cosmos start` mode, don't
 print any logs.  This is part of "consensus mode."
 
-If set to a value that contains the substring `agoric`, then print all console
-messages for the entire SDK.
+Otherwise, set to a comma-separated list of strings.
 
-Otherwise, set to a comma-separated list of prefixes, where each prefix is the
-context given to `makeConsole`.  For example:
+If one of those strings is
+- `agoric`, then print all console messages for the entire `agoric-sdk``.
+- `track-turns`, then log errors at the top of the event-loop that may otherwise be unreported. See also the TRACK_TURNS environment variable below.
+- `label-instances`, then log exo instances with a unique label per instance. HAZARD This causes an information leak in the messages of thrown errors, which are available even to code without access to the console. Use with care.
+
+For each of those strings begins with a prefix recognized as indicating what
+console messages to enable, pass it to `makeConsole`. For example:
 
 - `DEBUG=SwingSet:ls` enable all console messages for liveslots, regardless of vat.
 - `DEBUG=SwingSet:ls:v13` enable for liveslots in vat 13.
@@ -97,6 +101,10 @@ Description: When nonempty, create pretend prepopulated tokens like "moola" and
 
 Lifetime: until chain is mature enough not to need any pretend tokens
 
+## LOCKDOWN_*
+
+For the envoronment variables beginning with `LOCKDOWN_` , see [`lockdown` Options](https://github.com/endojs/endo/blob/master/packages/ses/docs/lockdown.md).
+
 ## OTEL_EXPORTER_PROMETHEUS_PORT
 
 Affects: cosmic-swingset
@@ -238,3 +246,8 @@ records individually. `config.defaultManagerType` has a higher priority so that
 tests which require a specific worker (e.g. which exercise XS heap snapshots,
 or metering) can override the env var, so they won't break under `yarn
 test:xs`.
+
+## TRACK_TURNS
+
+Log the deep causality stack behind logged errors if possible. See also the
+`DEBUG` setting `DEBUG=track-turns` above.

packages/agoric-cli/package.json

@@ -58,6 +58,7 @@
     "@endo/bundle-source": "^2.5.2",
     "@endo/captp": "^3.1.2",
     "@endo/compartment-mapper": "^0.8.5",
+    "@endo/env-options": "^0.1.1",
     "@endo/far": "^0.2.19",
     "@endo/init": "^0.5.57",
     "@endo/marshal": "^0.8.6",

packages/agoric-cli/src/anylogger-agoric.js

@@ -1,13 +1,15 @@
-/* global process */
+import { getEnvironmentOptionsList } from '@endo/env-options';
 import anylogger from 'anylogger';
 import chalk from 'chalk';
 
 // Turn on debugging output with DEBUG=agoric
-const { DEBUG } = process.env;
+
+const DEBUG_LIST = getEnvironmentOptionsList('DEBUG');
+
 let selectedLevel = 'info';
-if (DEBUG === undefined) {
+if (DEBUG_LIST.length === 0) {
   selectedLevel = 'log';
-} else if (DEBUG.includes('agoric')) {
+} else if (DEBUG_LIST.includes('agoric')) {
   selectedLevel = 'debug';
 }
 const defaultLevel = anylogger.levels[selectedLevel];

packages/cosmic-swingset/package.json

@@ -31,6 +31,7 @@
     "@agoric/swingset-vat": "^0.32.2",
     "@agoric/telemetry": "^0.6.2",
     "@agoric/vm-config": "^0.1.0",
+    "@endo/env-options": "^0.1.1",
     "@endo/far": "^0.2.19",
     "@endo/import-bundle": "^0.3.5",
     "@endo/init": "^0.5.57",

packages/cosmic-swingset/src/anylogger-agoric.js

@@ -1,25 +1,25 @@
-/* global process */
+import { getEnvironmentOptionsList } from '@endo/env-options';
 import anylogger from 'anylogger';
 
 // Turn on debugging output with DEBUG=agoric
 
-const { DEBUG: debugEnv = '' } = process.env;
+const DEBUG_LIST = getEnvironmentOptionsList('DEBUG');
 let debugging;
 
 const filterOutPrefixes = [];
 // Mute vat logging unless requested, for determinism.
-if (!debugEnv.includes('SwingSet:vat')) {
+if (!DEBUG_LIST.includes('SwingSet:vat')) {
   filterOutPrefixes.push('SwingSet:vat:');
 }
 // Mute liveSlots logging unless requested, for determinism.
-if (!debugEnv.includes('SwingSet:ls')) {
+if (!DEBUG_LIST.includes('SwingSet:ls')) {
   filterOutPrefixes.push('SwingSet:ls:');
 }
 
-if (process.env.DEBUG === undefined) {
+if (DEBUG_LIST.length === 0) {
   // DEBUG wasn't set, default to info level; quieter than normal.
   debugging = 'info';
-} else if (debugEnv.includes('agoric')) {
+} else if (DEBUG_LIST.includes('agoric')) {
   // $DEBUG set and we're enabled; loudly verbose.
   debugging = 'debug';
 } else {

packages/smart-wallet/test/test-addAsset.js

@@ -37,7 +37,7 @@ test.before(async t => {
   t.context = await makeDefaultTestContext(t, withBankManager);
 });
 
-const DEBUG = false;
+const LOG_NEWS_HEAD = false;
 const bigIntReplacer = (_key, val) =>
   typeof val === 'bigint' ? Number(val) : val;
 
@@ -67,7 +67,7 @@ test.serial('avoid O(wallets) storage writes for a new asset', async t => {
       const news = await E(current).subscribeAfter(publishCount);
       publishCount = news.publishCount;
       chainStorageWrites += 1;
-      if (DEBUG) {
+      if (LOG_NEWS_HEAD) {
         console.log(JSON.stringify(news.head, bigIntReplacer, 2));
       }
     }

packages/solo/src/start.js

@@ -371,9 +371,9 @@ const deployWallet = async ({ agWallet, deploys, hostport }) => {
 
   // Use the same verbosity as our caller did for us.
   let verbosity;
-  if (process.env.DEBUG === undefined) {
+  if (process.env.DEBUG === undefined || process.env.DEBUG === '') {
     verbosity = [];
-  } else if (process.env.DEBUG.includes('agoric')) {
+  } else if (process.env.DEBUG.split(',').includes('agoric')) {
     verbosity = ['-vv'];
   } else {
     verbosity = ['-v'];

packages/swingset-liveslots/package.json

@@ -20,6 +20,7 @@
     "@agoric/assert": "^0.6.0",
     "@agoric/internal": "^0.3.2",
     "@agoric/store": "^0.9.2",
+    "@endo/env-options": "^0.1.1",
     "@endo/eventual-send": "^0.17.3",
     "@endo/exo": "^0.2.3",
     "@endo/far": "^0.2.19",

packages/swingset-liveslots/src/virtualObjectManager.js

@@ -1,6 +1,7 @@
 /* global globalThis */
 /* eslint-disable no-use-before-define, jsdoc/require-returns-type */
 
+import { environmentOptionsListHas } from '@endo/env-options';
 import { assert, Fail } from '@agoric/assert';
 import { assertPattern, mustMatch } from '@agoric/store';
 import { defendPrototype, defendPrototypeKit } from '@endo/exo/tools.js';
@@ -14,26 +15,17 @@ import {
   checkAndUpdateFacetiousness,
 } from './facetiousness.js';
 
+// TODO Why is this here but commented out? If no longer relevant, remove
+// import { kdebug } from './kdebug.js';
+
 /** @template T @typedef {import('@agoric/vat-data').DefineKindOptions<T>} DefineKindOptions */
 
 const { hasOwn, defineProperty, getOwnPropertyNames, entries } = Object;
 const { ownKeys } = Reflect;
-const { quote: q } = assert;
-
-// See https://github.com/Agoric/agoric-sdk/issues/8005
-// Once agoric-sdk is upgraded to depend on endo post
-// https://github.com/endojs/endo/pull/1606 then remove this
-// definition of `b` and say instead
-// ```js
-//   const { quote: q, base: b } = assert;
-// ```
-const b = index => q(Number(index));
-
-// import { kdebug } from './kdebug.js';
-
-// TODO Use environment-options.js currently in ses/src after factoring it out
-// to a new package.
-const env = (globalThis.process || {}).env || {};
+// TODO https://github.com/Agoric/agoric-sdk/issues/8005
+// TODO https://github.com/endojs/endo/issues/1703
+// @ts-expect-error
+const { quote: q, bare: b } = assert;
 
 // Turn on to give each exo instance its own toStringTag value which exposes
 // the SwingSet vref.
@@ -42,9 +34,7 @@ const env = (globalThis.process || {}).env || {};
 // confidential object-creation activity, so this must not be something
 // that unprivileged vat code (including unprivileged contracts) can do
 // for themselves.
-const LABEL_INSTANCES = (env.DEBUG || '')
-  .split(':')
-  .includes('label-instances');
+const LABEL_INSTANCES = environmentOptionsListHas('DEBUG', 'label-instances');
 
 // This file implements the "Virtual Objects" system, currently documented in
 // {@link https://github.com/Agoric/agoric-sdk/blob/master/packages/SwingSet/docs/virtual-objects.md})