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 logging endpoint msg write a log entry 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

Default formatters: aws.fmt AWS az.fmt Azure fd.fmt generic gcp.fmt Google Cloud

Default formatters for AWS and Azure[entry;metadata][entry;metadata]


  • entry (string or dict) is the log entry
  • metadata (dict) is endpoint metadata

returns the formatted message as a dictionary.


Configure the logging interface

.com_kx_log.configure dict

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


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


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


Timestamp name and type appended to JSON messages. Symbol pair, default: `time`z


Ordered list of log severity levels. Symbol list, default: `TRACE`DEBUG`INFO`WARN`ERROR`FATAL


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)[`Monitor; ()]
q)key .mon.log
q) "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)[`Monitor; ()]
q) "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)[`Monitor; ()]
q) "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)[`Monitor; ()]
q) ("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)


The endpoint IDs


Returns the endpoint IDs as a GUID vector.

q).com_kx_init[`:fd://stdout; ()]


Public data for all the endpoints


Returns a table of public data for the endpoints.

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


Default generic formatter



  • entry (string or dict) is the log entry
  • metadata (dict) is endpoint metadata

uses entry as the entire message body (it ignores extra dictionary fields or endpoint metadata) and returns a string.


Default formatter for Google Cloud



  • entry (string or dict) is the log entry
  • metadata (dict) is endpoint metadata

returns the formatted message as a dictionary.


Endpoint routings for a component and level



  • 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)gcp:`url`metadata`provider!(`:; ()!(); `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]


Publish a log message



  • 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, the handlers returned are projections of this function with the level and component arguments fixed.

q)[`Discovery; ()]
q)res[0] ~ .com_kx_log.i.messager
q)res 1 2


Initialize the logging library



  • 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 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)gcp:`url`metadata`provider!(`:; ()!(); `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[`Discovery; ()]
// Monitor uses own routing[`Monitor; ids!`ALL`WARN]


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.

.com_kx_log.lclose id


Remove all endpoints


Removes all endpoints.

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


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:


GCP with metadata:

q)metadata:`logName`resource! (
    .j.j `type`labels!("gce_instance"; ()!()) )
q)dict:`url`provider`metadata!(`:; `gcp; metadata)
q).com_kx_log.lopen dict

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


Write an entry in the log

.com_kx_log.msg entry

Where entry is a log entry as a string or dictionary, writes it in the log.

/ string
.com_kx_log.msg (string .z.Z)," INFO - Initialization complete"

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

Log interface handlers for a new component[component;routing]


  • 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)[`Discovery; ()]

Monitor with custom routing:

q)ids:exec id from endpoints[]
q)[`Monitor; ids!`ALL`WARN]


Set the log correlator

.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) "Test"

Own correlator:

 q) "Test"


Configure log routing for a component



  • 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]


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)


Unset the log correlator