Type alias LoggingConfig

Overview

The configuration for logging events that may be logged or emitted by the DataAPIClient or any of its children classes.

This can be set at any level of the major class hierarchy, and will be inherited by all child classes.

Configuration inheritance

Logging is configured through a list of hierarchical rules, determining which events to emit where. Each rule layer overrides previous rules for the same events.

Logging configuration is inherited by child classes, but may be overridden at any level (e.g. pass a base config to the DataAPIClient constructor, and then override it for a specific Collection).

Configuration & shorthands

There are multiple ways to configure logging, and the rules may be combined in various ways:

logging: 'all'

• This will enable all events with default behaviors (see below)

logging: [{ events: 'all', emits: 'event' }]

• This will enable all events, but only emit them as events

logging: '<event>' | ['<events>']

• This will enable only the specified event(s) with default behaviors

logging: /<regex>/ | [/<regex>/]

• This will enable only the matching event(s) with default behaviors

logging: [{ events: ['<events>'], emits: ['<outputs>'] }]

• This will allow you to define the specific outputs for specific events

logging: ['all', { events: ['<events>'], emits: [] }]

• Example of how 'all' may be used as a base configuration, to be overridden by specific rules
• The empty emits array effectively disables outputs for the specified events

Event types & defaults

See DataAPIClientEventMap for more information on the types of events emitted & their defaults.

As a TL;DR, when enabled, all events are emitted as events by default, and commandStarted and commandSucceeded are the only events not logged to stderr as well by default; all other events are logged to stderr.

Output types

The emits field can be set to either 'event', 'stdout', 'stderr', or their verbose variants.

• 'event' will emit the event to each HierarchicalEmitter in the hierarchy
  • e.g. first to the Collection, then the Db, then the DataAPIClient
  • See HierarchicalEmitter for more information on how events are emitted
• 'stdout' & 'stderr' will log the event to stdout or stderr, respectively
  • The 'stdout:verbose' & 'stderr:verbose' variants will use a verbose format containing all the events properties
  • These are useful for debugging, but may be overwhelming for normal use

You may use BaseClientEvent.setDefaultFormatter to change the format of the events as they're logged to stdout/stderr. See EventFormatter for more information.

Examples

For more advanced examples, see the examples/logging directory in the astra-db-ts repository

Hierarchical usage example:

Example

// Create a `DataAPIClient` with emission enabled for all failed/warning commands
const client = new DataAPIClient('*TOKEN*', {
  logging: [{ events: /.*(Failed|Warning)/, emits: ['stderr:verbose', 'event']}],
});

client.on('commandFailed', (event) => {
  console.error('Some command failed:', event.commandName);
});

// Override the logging config for this `Db` to emit *all* events as events
const db = client.db('*ENDPOINT*', {
  logging: [{ events: 'all', emits: 'event' }],
});

db.on('commandStarted', (event) => {
  console.log('Command started:', event.commandName);
});

db.on('commandSucceeded', (event) => {
  console.log('Command succeeded:', event.commandName);
});

// Resulting output:
// 'Command started: "createCollection"'
// 'Some command failed: "createCollection"'
await db.createCollection('$invalid-name$');
Copy

Various configuration examples:

Example

// Set sane defaults for logging
const client = new DataAPIClient({
  logging: 'all',
});

// Just emit all events as events
const client = new DataAPIClient({
  logging: [{ events: 'all', emits: 'event' }],
});

// Define specific outputs for specific events
const client = new DataAPIClient({
  logging: [
    { events: ['commandStarted', 'commandSucceeded'], emits: ['stdout', 'event'] },
    { events: ['commandFailed'], emits: ['stderr', 'event'] },
  ],
});

// Use 'all' as a base configuration, and override specific events
const client = new DataAPIClient({
  logging: ['all', { events: /.*(Started|Succeeded)/, emits: [] }],
});

// Enable specific events with default behaviors
const client = new DataAPIClient({
  logging: ['commandSucceeded', 'adminCommandStarted'],
});
Copy

See

• DataAPIClientEventMap
• LoggingEvent
• LoggingOutput