Package: pflog
AbstractThis software is a lightweight user of thepftel-clientlibrary that
allows for logging to a remote logging service. Both stand-alone and
modular use cases are supported. At the moment only minimal coverage of
server API is provided.Overviewpflogis a simple app that is both a stand alone client as well as a
module for logging to apfteltelemetry server.InstallationLocal python venvForon the metalinstallations,pipit:pipinstallpflogdocker containerdockerpullfnndsc/pflogRunnningScript modeTo usepflogin script mode you simply call the script with
appropriate arguments (and of course this assumes you have a server
instance at the$PFTELlocation)exportPFTEL=http://localhost:22223# obviously change this as neededpflog\--log"Hello, world!"\--pftelURL$PFTEL\--verbosity1\Module modeTo usepflogin python module mode, you declare an object and
instantiate with a dictionary of values. The dictionary keys areidenticalto the script CLI keys:frompflogimportpfloglog:pflog.Pflog=pflog.Pflog({'log':'Hello, world!','pftelURL':'http://localhost:22223','verbosity':'1'})d_tlog:dict=log.run()# You can use this same object to log more messages:log('This is another message')log('and so is this!')This writes messages to alogObjectcalleddefaultunder alogCollectionthat is the timestamp of the event transmission.
Within thelogCollectionwill belogEvents prefixed by an
incremental counter, so000-event,001-event, etc.Decorators and convenience functionsConvenience helperThe python module additionally offers a convience functionpfprintthat offers a function-likethrow backto C-stylefprintfwhile
hiding the complexity of creating and using aPflogobject:pfprint('https://some.telemetry.server/api/v1/weather/MA/boston','Brrr... it is freezing today!')will log the messageBrr...it is freezing today!in the event
calledbostonof the collectionMAof the set/object calledweather. Note that each call ofpfprintwill create effectively
a singleton object and a new connection to the telemetry server that is
not reused (unlike the snippet above).Timing and logging with decoratorsA decorator calledtel_logTimeis also available. In the simplest
case@tel_logTimeweather_model(arg1,arg2)will simply print the total execution time of the functionweather_model. This information can be additionally logged to a
telemetry service using@tel_logTime(pftelDB='https://some.telemetry.server/ap1/v1/weather/MA/boston-%timestamp',log='Weather prediction execTime')weather_model(arg1,arg2)which will record the execution time of the function to thepftelDB.
Note that the%timestampin theeventfieldboston-%timestampwill be parsed at runtime with as apftagstring and appropriately substituted. Thelog = 'Weather prediction execTime'is simply an optional logging
string that is also written to the log event. Equivalently one could do@tel_logTime(pftelDB='https://some.telemetry.server/ap1/v1/weather/MA/event',event='boston-%timestamp'log='Weather prediction execTime')weather_model(arg1,arg2)Finally, note the special case where the function to be decorated
contains a pythonNamespacewith an attribute calledpftelDB. In
this case, the decorator will determine thepftelDBfrom the
decorated function’s arguments. This is particularly useful when the
main entry point for a python program uses these options and we wish to
log telemetry:# Imagine we have a python program called 'weather_app' and it has a CLI option:weather_app--pftelDBhttps://some.telemetry.server/ap1/v1/weather/MA/boston-%timestamp# In python, assuming we have parsed the CLI with Argparser into a Namespace variable# called 'options', we could simply do@tel_logTimemain(options)And the decorator will determinepftelDBfrom theoptions. For
simplicity theeventandlognamed args have been omitted. Note
that the first decorator example was assumed tonothave aNamespacein eitherarg1norarg2.Arguments--pftelURL<pftelURL>| --pftelDB<URLDBpath>The URL of the pftel instance. Typically:

        --pftelURL http://some.location.somewhere:22223

either this or '--pftelDB' MUST be specified. See below for --pftelDB.

--log<logMessage>The actual message to log. Use quotes to protect messages that
contain spaces:

        --log "Hello, world!"

[--logObject<logObjectInPTFEL>] "default"
[--logCollection<logCollectionInPFTEL>] `timestamp`
[--logEvent<logEventInPFTEL>] "event"
[--appName<appName>]
[--execTime<execTime>]
Logs are stored within the pftel database in

    `{logObjectInPFTEL}`/`{logCollectionInPFTEL}`/`{logEventInPFTEL}`

if not specified, use defaults as shown. The<appName>and<execTime>are stored within the<logEventInPFTEL>.

[--pftelDB<DBURLpath>]
This is an alternate CLI that specifies a DB POST URL:

    --pftelDB<URLpath>/<logObject>/<logCollection>/<logEvent>for example

    --pftelDB http://localhost:22223/api/v1/weather/massachusetts/boston

Indirect parsing of each of the object, collection, event strings is
available through `pftag` so any embedded pftag SGML is supported. So

    http://localhost:22223/api/vi/%platform/%timestamp_strmsk|**********_/%name

would be parsed to, for example:

    http://localhost:22223/api/vi/Linux/2023-03-11/posix

[--asyncio]
If specified, use asyncio, else do sync calls.

[--detailed]
If specified, return detailed responses from the server.

[--test]
If specified, run a small internal test on multi-logger calls.

[--pftelUser<user>] ("chris")
The name of the pftel user. Reserved for future use.

[--inputdir<inputdir>]
An optional input directory specifier. Reserverd for future use.

[--outputdir<outputdir>]
An optional output directory specifier. Reserved for future use.

[--man]
If specified, show this help page and quit.

[--verbosity<level>]
Set the verbosity level. The app is currently chatty at level 0 and level 1
provides even more information.

[--debug]
If specified, toggle internal debugging. This will break at any breakpoints
specified with 'Env.set_trace()'

[--debugTermsize<253,62>]
Debugging is via telnet session. This specifies the<cols>,<rows>size of
the terminal.

[--debugHost<0.0.0.0>]
Debugging is via telnet session. This specifies the host to which to connect.

[--debugPort<7900>]
Debugging is via telnet session. This specifies the port on which the telnet
session is listening.DevelopmentInstructions for developers.To debug, the simplest mechanism is to trigger the internal remote
telnet session with the--debugCLI. Then, in the code, simply addEnv.set_trace()calls where appropriate. These can remain in the
codebase (i.e. you don’t need to delete/comment them out) since they are
onlylivewhen a--debugflag is passed.TestingRun unit tests usingpytest. Coming soon!-30-