API reference

.com_kx_log. configure configure the logging interface endpointIDs endpoint IDs endpoints public data for all the endpoints getRoutings endpoint routings for a component and level i.messager publish message init initialize the logging library lclose remove a logger from the list of endpoints lcloseAll remove all endpoints lopen initialize a logging endpoint msg write to logging endpoints new create log interface handlers for new component setCorrelator set the log correlator setRouting configure log routing for a component setServiceDetails set service details metadata unsetCorrelator unset the log correlator

.com_kx_log.configure

Configure the logging interface

The argument is a dictionary with entries as follows (all are optional and have defaults)

customFormatter: Specifies a custom formatter for the logging interface (overrides formatMode). Must be a function taking a single dictionary parameter. Symbol, default: `
formatMode: Logging mode to use: JSON or text. Symbol, default: `json
jsonTime: Timestamp name and type appended to JSON messages. Symbol list, default: `time`z
logLevels: Ordered list of log severity levels. Symbol list, default: `TRACE`DEBUG`INFO`WARN`ERROR`FATAL
textTemplate: Token-based template string for text mode. String, default: ""

Must be called before configuring any endpoints or creating any handlers

Parameter:

Name	Type	Description
opts	dict	Config options

Example: Text mode & non-default log levels

 q).com_kx_log.configure[`formatMode`logLevels!(`text; `DEBUG`INFO`WARNING`ERROR)]
 q).com_kx_log.init[`:fd://stdout; ()]
 q).mon.log:.com_kx_log.new[`Monitor; ()]
 q)key .mon.log
 `debug`info`warning`error
 q).mon.log.info["Test message"]
 2020-12-11 14:48:48.239 [Monitor] INFO Test message

Example: Custom formatter

 q).app.fmt:{[entry] :", " sv "=" sv' flip (string@key@; value)@\: .j.j each `time xcols update time:.z.t from entry }
 q).com_kx_log.configure[enlist[`customFormatter]!enlist `.app.fmt]
 q).com_kx_log.init[`:fd://stdout; ()]
 q).mon.log:.com_kx_log.new[`Monitor; ()]
 q).mon.log.info["Test message"]
 time="15:24:08.959", component="Monitor", level="INFO", message="Test message"

Example: Text mode & updated template

 q).com_kx_log.configure[`formatMode`textTemplate!(`text; "%P [%c] %l %m")]
 q).com_kx_log.init[`:fd://stdout; ()]
 q).mon.log:.com_kx_log.new[`Monitor; ()]
 q).mon.log.info["Test message"]
 2020-12-16D17:25:26.058811000 [Monitor] INFO Test message

Example: JSON time

 q).com_kx_log.configure[enlist[`jsonTime]!enlist `timestamp`T]
 q).com_kx_log.init[`:fd://stdout; ()]
 q).mon.log:.com_kx_log.new[`Monitor; ()]
 q).mon.log.info[("Test message %1"; 10)]
 {"timestamp":"20:19:54.718","level":"INFO","component":"Monitor","message":"Test message 10"}

Example: Service details

 q).com_kx_log.configure[enlist[`serviceDetails]!enlist `service`PID!(`rdb; .z.i)]

.com_kx_log.endpointIDs

The endpoint IDs

Returns a list of endpoint IDs

Returns:

Type	Description
guid[]

Example:

 q).com_kx_init[`:fd://stdout; ()]
 q).com_kx_log.endpointIDs[]
 ,8c6b8b64-6815-6084-0a3e-178401251b68

.com_kx_log.endpoints

Public data for all the endpoints

Returns a table of public data for the endpoints.

Returns:

Type	Description
table	Endpoints

Example:

 q).com_kx_init[`:fd://stdout; ()]
 q).com_kx_log.endpoints[]
 id                                   url          provider formatter metadata
 -----------------------------------------------------------------------------
 8c6b8b64-6815-6084-0a3e-178401251b68 :fd://stdout fd                 ()!()

.com_kx_log.getRoutings

Endpoint routings for a component and level

Returns the IDs of corresponding endpoints as GUIDs.

Parameters:

Name	Type	Description
level	symbol	Log level
component	symbol	Component name

Returns:

Type	Description
guid[]	IDs

Example:

 q)stdout:`:fd://stdout
 q)gcp:`url`metadata`provider!(`:https://logging.googleapis.com; ()!(); `gcp)
 q)ids:.com_kx_log.init[(stdout; gcp); `ALL`ERROR]
 q).com_kx_log.getRouting[`ERROR; `Monitor]
 8c6b8b64-6815-6084-0a3e-178401251b68 5ae7962d-49f2-404d-5aec-f7c8abbae288

 q).com_kx_log.setRouting[`Monitor; ids!`ALL`FATAL]
 q).com_kx_log.getRouting[`ERROR; `Monitor]
 ,8c6b8b64-6815-6084-0a3e-178401251b68

.com_kx_log.i.messager

Publish a log message

Documented for reference only. Not intended to be called directly

This API generates the formatted log messages, checks the endpoint routing and publishes.

When log components are created using .com_kx_log.new, the handlers returned are projections of this function with the level and component arguments fixed.

Parameters:

Name	Type	Description
level	symbol	Level
component	symbol	Component name
entry	string \| dict	Log message

Example:

 .qlog.sd:.com_kx_log.new[`Discovery; ()];
 res:get .qlog.sd.info;
 res[0] ~ .com_kx_log.i.messager
 /=> 1b
 res[1 2]
 /=> `INFO`Discovery

.com_kx_log.init

Initialize the logging library

Initializes the logging library with endpoints and routing and returns as a GUID vector a list of endpoint IDs for routing and calls to lclose. and routing. It returns a set endpoint IDs to be used for routing and calls to lclose.

Each endpoint in eps is a symbol or dictionary.

The lvls vector specifies endpoint routing by level, i.e. which log levels to send to which endpoints. This allows the application to route priorities differently.

NONE suppresses publication
a null, or ALL routes all levels to all endpoints

.com_kx_log.new to create log handlers for publishing

The eps parameter provides a list of endpoints to setup. Each element of the list is a symbol or dict.

The levels parameter dictates endpoint routing by level, i.e. which log levels to send to which endpoints. This allows the application to route priorities differently. Can be left blank to route to all by default. This is best illustrated with an example;

Default ordered list of log levels; TRACE, DEBUG, INFO, WARN, ERROR, FATAL
Two endpoints with different levels - stdout=ALL, gcp=ERROR
All log messages with TRACE and above, would be written to stdout
All messages with ERROR and above, would be written to gcp.

The example below has

Default ordered list of log levels: TRACE, DEBUG, INFO, WARN, ERROR, FATAL
Two endpoints with different levels: stdout=ALL, gcp=ERROR
All log messages with TRACE and above to be written to stdout
All log messages with ERROR and above to be written to gcp

Parameters:

Name	Type	Description
eps	list	Endpoints
levels	symbol[]	Default level routing

Returns:

Type	Description
guid[]	IDs

Example:

 stdout:`:fd://stdout;
 gcp:`url`metadata`provider!(`:https://logging.googleapis.com; ()!(); `gcp);
 0N!ids:.com_kx_log.init[(stdout; gcp); `ALL`ERROR];
 /=> 893df855-e1c9-2f1e-36ad-c601521c3d2b 3375050d-b799-713f-6033-b19c387862f8

 // Create two sets of logging APIs
 // Discovery component uses default log levels
 .qlog.sd:.com_kx_log.new[`Discovery; ()];
 // Monitor uses own routing
 .qlog.mon:.com_kx_log.new[`Monitor; ids!`ALL`WARN];

.com_kx_log.lclose

Remove a logger from the list of endpoints

Parameter:

Name	Type	Description
id	guid	Endpoint ID

Example:

 q)id:.com_kx_log.lopen[`:fd://stdout]
 q).com_kx_log.lclose[id]

.com_kx_log.lcloseAll

Remove all endpoints

Example:

 q)ids:.com_kx_log.init[`:fd://stdout`:fd://file.log; ()]
 q).com_kx_log.lcloseAll[]

.com_kx_log.lopen

Initiate a logging endpoint

ep can be one of the following

an endpoint URL as a symbol atom
a dictionary with the URL, provider type and metadata

Initializes the endpoint and returns its ID as a GUID atom.

Parameter:

Name	Type	Description
ep	symbol \| dict	Logging endpoint

Returns:

Type	Description
guid

Example: URL only

 q).com_kx_log.lopen[`:fd://stdout]
 8c6b8b64-6815-6084-0a3e-178401251b68

Example: GCP with metadata

 q)metadata:`logName`resource!("projects/[PROJECT_ID]/logs/[LOG_ID]"; .j.j `type`labels!("gce_instance"; ()!()));
 q)dict:`url`provider`metadata!(`:https://logging.googleapis.com; `gcp; metadata);
 q).com_kx_log.lopen[dict]
 8c6b8b64-6815-6084-0a3e-178401251b68

Example: With custom formatter

 q).app.fmt:{[entry; metadata] $[99h = type entry; .j.j entry; entry]}
 q)dict:`url`formatter!(`:fd://stdout; `.app.fmt)
 q).com_kx_log.lopen[dict]
 8c6b8b64-6815-6084-0a3e-178401251b68

.com_kx_log.msg

Log publish API. Takes a log string or dictionary of message and metadata.

Parameter:

Name	Type	Description
entry	string \| dict	Log entry

Example: String

 entry:string[.z.Z], " INFO - Initialisation complete";
 .com_kx_log.msg[entry]

Example: Dictionary

 dict:`message`severity`logName!("Initialisation complete"; "INFO"; "projects/[PROJECT_ID]/logs/[LOG_ID]");
 .com_kx_log.msg[dict];

.com_kx_log.new

Create log interface handlers for a new component

Call after .com_kx_log.init

Parameters:

Name	Type	Description
component	symbol	Component name
routing	dict	Endpoint routing
routing.id	guid
routing.level	symbol

Returns:

Type	Description
dict	Logging handlers

Example: Discovery with default routing

 q)ids:exec id from endpoints[]
 q).qlog.sd:.com_kx_log.new[`Discovery; ()]
 q)key .qlog.sd
 `trace`debug`info`warn`error`fatal

Example: Monitor with custom routing

 q)ids:exec id from endpoints[]
 q).qlog.mon:.com_kx_log.new[`Monitor; ids!`ALL`WARN]

.com_kx_log.setCorrelator

Set the log correlator

Where the function is called as a nullary, it generates a correlator, sets it and returns its ID as a string.

Where the function is called as a unary, corr is the ID of a correlator (string or symbol atom), sets it and returns it as a string.

Parameter:

Name	Type	Description
id	string \| guid \| null	Correlator

Returns:

Type	Description
string	Correlator

Example: Generate correlator

 q)0N!id:.com_kx_log.setCorrelator[]
 "a4c18095-5d5e-5585-3f20-32d49b67b873"
 q).mon.log.info "Test"
 {"time":"2020-12-14T16:02:20.063794000z","corr":"a4c18095-5d5e-5585-3f20-32d49b67b873","level":"INFO","component":"Monitor","message":"Test"}

Example: Own correlator

 q).com_kx_log.setCorrelator["app-123"]
 "app-123"
 q).mon.log.info "Test"
 {"time":"2020-12-14T16:02:35.763427000z","corr":"app-123","level":"INFO","component":"Monitor","message":"Test"}

.com_kx_log.setRouting

Configure log routing for a component

Parameters:

Name	Type	Description
component	symbol	Component name
dict	dict	Dictionary mapping endpoints to log levels
dict.id	guid
dict.level	symbol

Example:

 q)ids:exec id from endpoints[]
 q).com_kx_log.setRouting[`Monitor; ids!`ALL`ERROR]

.com_kx_log.setServiceDetails

Set the service details metadata

Parameter:

Name	Type	Description
args	dict	Service details

Example:

 q).com_kx_log.setServiceDetails[`service`PID!(`rdb; .z.i)]

.com_kx_log.unsetCorrelator

Unset the log correlator

See .com_kx_log.setCorrelator for full example

Example:

 q).com_kx_log.unsetCorrelator[]