Usage

The general syntax to use stethoscope is:

stethoscope [OPTIONS] -d DATABASE

or

stethoscope [OPTIONS] -I FILE

The user provides the specification of the desired pipeline using the following options:

--transformer (--transformer/-t)

statement, prereqs, obfuscate, mask, dummy, and identity. Can be specified in any order multiple times.

--formatter (--formatter/-F)

json, json_pretty, line, and raw.

Alternatively the user can specify a number of predefined pipelines using --pipeline (-l) (see section Predefined pipelines). This option overrides all other given options.

Connection and filesystem options

database (--database/-d database)

The name of the database to connect to. Either this or the --input must be given.

file input (--input/-I file name)

A file from which to get input. Either this or the --database must be given.

username (--username/-u username)

The name of the user for the database connection. The default value is monetdb.

password (--password/-P password)

The password to be used for the database connection. The default value is monetdb.

output (--output/-o filename)

The file where stethoscope will write its output. If this is omitted, the output will be written to the standard output.

flush (--flush/-U)

Immediatelly flush the output stream.

Logging and reporting options

During the processing of JSON objects errors and warnings might be reported. Normally these are handled and emitted separately for each object, but in order to reduce noise, stethoscope by default will dispaly the message just the first time it is emitted.

The default configuration outputs events through the python logging framework. By default it uses the the console logger. The following options contol the behavior of logging.

--verbose/-V

Show all error and warnings.

--no-console/-C

Disable logging to the console.

--log-file/-O filename

Write log events to filename. Logging in a file logs all the events.

Reading and Parsing

Reading and parsing happen automatically in every pipeline, (with the exception of the raw pipeline as in Predefined pipelines), and as such the user does not have any control over it.

Transforming

The user can specify a number of transformers that can change the content of the JSON objects. Most transformers add key-value pairs in objects. Currently stethoscope implements the following transformers:

statement

Recreates a rendering of the MAL statement that this object represents. This transformer adds the key stmt in the JSON object with a string value that represents the MAL statement.

Warning

This transformer will not work with MonetDB server versions earlier than Jun2020.

Note

Specifying this transformer implicitly adds the key stmt to the list of included keys.

prereqs

Adds the key prereq in the JSON object. Its value is a list of program counter values (see section MAL profiler JSON format) of MAL instructions that need to be completed before the current instruction can start executing.

Note

Specifying this transformer implicitly adds the key prereq to the list of included keys.

mask

This transformer replaces all the literal values in the JSON object with three asterisks.

Warning

This transformer will not work with MonetDB server versions earlier than Jun2020.

obfuscate

This transformer uses one-way functions to replace numeric values, alphabet reshuffings for strings, and replaces DDL objects with dummy names.

identity

This transformer leaves the object unchanged. In itself this is not particularly useful to the user, but it might be useful in the future as a base case for recursive transformers and to denote the absence of other operations.

dummy

This transformer adds the key L0 with a value 'dummy value'. This is used mostly for debugging.

Key inclusion and exclusion transformers

There are two special transformers that take a list of keys as arguments:

--include-keys (-i key1 key2 ...)

This transformer takes a space separated list of keys and removes all other keys from the JSON object.

--exclude-keys (-e key1 key2 ...)

This transformer takes a space separated list of keys and removes them from the JSON object.

Formatting

The following formatters are currently available:

json

Formats the object as a valid JSON string.

json_pretty

Formats the object as a human readable valid JSON string.

line

Presents the values in the object in one line separated by the string ,\t and enclosed in square brackets.

raw

Sends the object as is to the output stream. This usually uses the default Python rendering for dictionaries. The exception to this rule is the raw pipeline (see Predefined pipelines).

Predefined pipelines

The following are the predefined pipelines that stethoscope currently has:

raw

This pipeline is intended for accessing the raw output of the MonetDB server’s profiler. When using this pipeline stethoscope will connect to the server, read strings, and print them to the output stream. No other processing happens, and specifically no parsing takes place. This is mainly useful for debugging the profiler module of the MonetDB server.

Note

The raw pipeline can be used with earlier than Jun2020 versions of MonetDB.