Skip to content

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 loggig endpoint 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 

.com_kx_log.configure dict

Where dict is a dictionary with entries as follows (all are optional and have defaults)

customFormatter

Custom formatter for the logging interface (overrides formatMode) as a symbol atom naming a unary function taking a dictionary argument. Default: `

formatMode

Logging mode to use. Symbol atom, either `json (default) or `text.

jsonTime

Timestamp name and type appended to JSON messages. Symbol pair, 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

Example: Text mode and 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 and 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

.com_kx_log.endpointIDs[]

Returns the endpoint IDs as a GUID vector.

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

.com_kx_log.endpoints[]

Returns a table of public data for the endpoints.

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

.com_kx_log.getRoutings[level;component]

Where

  • level is the logging level (symbol atom)
  • component is the components name (symbol atom)

returns the IDs of corresponding endpoints as a GUID vector.

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 

.com_kx_log.i.messager[level;component;entry]

Where

  • level is the logging level (symbol)
  • component is a component name (symbol)
  • entry is a log message (string or dictionary)

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

For reference only: not intended to be called directly

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.

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

.com_kx_log.init

Initialize the logging library

.com_kx_log.init[eps;levels]

Where

  • eps is a list of endpoints, each item a symbol or dictionary
  • levels is the default level routing (symbol vector)

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.

The levels 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

Use .com_kx_log.new to create log handlers for publishing

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 to be written to stdout
  • All log messages with ERROR and above to be written to gcp
q)stdout:`:fd://stdout
q)gcp:`url`metadata`provider!(`:https://logging.googleapis.com; ()!(); `gcp)
q)show 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

.com_kx_log.lclose id

Where id is an endpoint ID as a GUID atom, removes it from the list of endpoints.

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

.com_kx_log.lcloseAll

Remove all endpoints

.com_kx_log.lcloseAll[]

Removes all endpoints.

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

.com_kx_log.lopen

Initiate a logging endpoint

.com_kx_log.lopen ep

Where ep is either

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

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

URL only:

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

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

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.new

Log interface handlers for a new component

.com_kx_log.new[component;routing]

Where

  • component is the name of a component (symbol)
  • routing is the endpoint routing as a dictionary of endpoint IDs and their logging levels

returns the logging handlers as a dictionary with logging levels as keys.

Call after .com_kx_log.init

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

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

.com_kx_log.setCorrelator[]
.com_kx_log.setCorrelator id

Where the function is called as a

  • nullary, it generates a correlator
  • unary, id is the ID of a correlator (string or symbol)

sets it and returns its ID as a string.

Generate correlator:

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

Own correlator:

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

.com_kx_log.setRouting

Configure log routing for a component

.com_kx_log.setRouting[component;dict]

Where

  • component is the name of a component (symbol)
  • dict is a dictionary of endpoints (GUIDs) to their logging levels (symbols)

sets the logging levels as specified.

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

.com_kx_log.setServiceDetails

Set the service details metadata

.com_kx_log.setServiceDetails args

Where args is a dictionary of service details, sets them.

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

.com_kx_log.unsetCorrelator

Unset the log correlator

.com_kx_log.unsetCorrelator[]

.com_kx_log.setCorrelator