Add UDS API for post-launch log level tuning.

[edwbuck]

see spiffe/spire#4785

This commit introduces:

New Data Types

• Logger : a representation of a logger

  • name : the logger's name, empty for the root logger
  • current_level : the current log level of the logger
  • default_level : the log level of the logger configured
    in the application's config file

• LoggerMask : which Logger fields must be populated on a
  query response

  • current_level : populate the current log level
  • default_level : populate the default log level

Single Logger Operations:

• GetLogger : Fetches the log level of the logger

  • Input: name, the logger name
    (optional, unset is root logger)
  • Input: output_mask, the desired logger output fields
    (optional, unset is all fields)
  • Output: a Logger record

• AdjustLogger : Changes the log level of the logger

  • Input: name, the logger name
    (optional, unset is the root logger)
  • Input: log_level, the logger's new LogLevel
    (required)
  • Output: none

Plural Logger Operations:

• CountLoggers : Returns the number of loggers

  • Input: none
  • Output: the number of loggers

• ListLoggers : Show Logger details for a number of loggers

  • Input: filter, the control over which loggers are returned.
    (optional, unset is the root logger with all sub-loggers)
    • filter.by_name : the name of the logger forming the root
      of the returned loggers
    • filter.with_subloggers : a flag indicating if sub-loggers
      are to be included in the response
  • Input: output_mask, the fields to be returned in the output
    • output_mask.current_level : show the current log level of
      the logger
    • output_mask.default_level : show the log level of the logger
      configured in the process config
      file

[edwbuck]

• example of how to list all loggers (in pseudo-code)

ListLoggers {
}

• example of how to list all logger's current log levels only (without the default log level) (in pseudo-code)

ListLoggers {
  output_mask: {
    current_level = true,
    default_level = false,
  },
}

• example of how to list the loggers and sub-loggers under "agent-attestor" (future implementation, currently this logger does not exist)

ListLoggers {
  filter: {
    by_name: "agent-attestor",
  }
}

• example of how to list only the logger "agent-attestor" (future implementation, currently this logger does not exist)

ListLoggers {
  filter: {
    by_name: "agent-attestor",
    with_subloggers: false,
  },
}

Paging is planned to be supported, even though I doubt the number of pages will exceed one.

GetLogger is a simplified API for when only one logger is to be listed. It defaults to the ListLoggers behavior with an optional by_name and with_subloggers hard-wired to false.

Deciding which fields are to be returned is controlled with the LoggerMask type. LoggerMask.current_level will ensure that the logger's current log level is returned. LoggerMask.default_level will ensure that the logger's default (configured at launch time) level is returned. If no logging levels are desired, setting both to false will only return logger names.

The defaults for these being unset is to assume the values are to be returned. The defaults for not including a LoggerMask is to return both the current level and the default level.

LoggerMask {
  current_level = true,
  default_level = true,
}

• example of how to adjust the root logger and all sub-loggers to a new debug level (in pseudo-code)

AdjustLoggers {
  log_level: DEBUG
}

• example of how to adjust only the root logger to the debug level (in pseudo-code)

AdjustLoggers {
  log_level: DEBUG,
  adjust_subloggers: false,
}

• example of how to reset the loggers to the process's "at launch time" log level.

AdjustLoggers {
  log_level: DEFAULT,
}

• example of how to reset the logger "agent-attestor" and sub-loggers to their "at launch time" log level.

AdjustLoggers {
  name: "agent-attestor",
  log_level: DEFAULT,
}

• example of how to reset the logger "agent-attestor" to the "at launch time" log level without adjusting any sub-loggers of the "agent-attestor" logger.

AdjustLoggers {
  name: "agent-attestor"
  log_level: DEFAULT,
  adjust_subloggers: false,
}

The count API is for optimized counting, avoiding the retrieval of all loggers for client-side counting. As a root logger always exists, the minimum count should be 1. No assurances exist that the count is stable, for systems that require storage of all items, use ListLoggers to obtain all items and store off the count of the returned logger list. Do not call LoggerCount to allocate the size, as the ListLoggers can return a different count should the system initialize a new logger between the two API calls.