We will provide a "metlog" library that will both ease generation of these messages and that will handle packaging them up and delivering them (via UDP) into the message processing infrastructure. Implementations of this library will likely be available in both Python and Javascript, but the Python library will be available first and this document will, for now, only describe the Python API. The Javascript API will be similar, modulo syntactic sugar that is available in Python but not in JS (e.g. decorators, context managers), and will be documented in detail in the future. The proposed Python API is as follows:
; '''set_metlog_dest(host, port)''': Specifies the address and port of the metlog listener, the destination of the UDP packets that will be sent out as a result of subsequent ''metlog'' calls. The Services Python framework will provide a mechanism to specify this via configuration files so services authors won't have to make this call themselves.
; '''set_default_logger(logger)''' : Specifies a logger value to use as the address and port of the metlog listener, the destination of the UDP packets that will be sent out as a result of default for all subsequent ''metlog'' calls. The Services Python framework will provide in which a mechanism to specify this via configuration files so services authors won't have to make this call themselveslogger value is not explicitly provided.
; '''set_default_loggerset_message_flavor(loggerflavor_name, metadata)''': The metadata for a given message can be used to label and categorize that message. This function expects a string value ''flavor_name'' and a dictionary ''metadata''. The flavor name value can be passed in as a ''flavor'' to subsequent ''metlog'' calls as shorthand for including the specified metadata in the outgoing message.
Specifies a logger value to use as the default for all subsequent ; '''metlog(timestamp=None, logger=None, severity=6, message="", metadata=None, flavors=None)''' calls in which : Sends a logger value is not explicitly single log message to the previously specified metlog listener. Most of the arguments correspond to the message fields described above. None of them are strictly required, but most of them will be populated by reasonable defaults if they aren't provided.:
* ''timestamp'set_message_flavor': Defaults to current system time.* ''logger'': Defaults to what has been specified using the ''set_default_logger'' call, or to an empty string if ''set_default_logger'' hasn't been called.* ''severity'': Defaults to 6 (flavor_name, "Informational")* ''message'': Defaults to an empty string* ''metadata)'': Defaults to an empty dictionary* ''flavors'': Any specified flavors will cause this message's metadata value to be updated to contain the flavor's metadata; defaults to an empty list
The ; '''timer(name, timestamp=None, logger=None, severity=6, metadata for a given message can =None, flavors=None, rate=1)''' : Can be used as either a context manager or a decorator. Will calculate the time required to label execute the enclosed code, and will generate and categorize that send a metlog messagecontaining the timing information upon completion. This function expects a string value ''flavor_namename'' and is a dictionary ''required string label for the timer that will be added to the message metadata''. The flavor name value can be passed in as a ''flavorrate'' to subsequent ''metlog'' calls as shorthand for including represents what fraction of these invocations should actually be timed, so a value of 0.3 would mean that the code would be timed and the specified metadata in results sent off approximately 30% of the outgoing messagetime it was executed.
'''metlog(timestamp=None, logger=None, severity=6, message="", metadata=None, flavors=None)''' Sends a single log message to the previously specified metlog listener. Most of the arguments correspond to the message fields described above. None of them are strictly required, but most of them will be populated by reasonable defaults if they aren't provided: * ''timestamp'': Defaults to current system time. * ''logger'': Defaults to what has been specified using the ''set_default_logger'' call, or to an empty string if ''set_default_logger'' hasn't been called. * ''severity'': Defaults to 6 ("Informational") * ''message'': Defaults to an empty string * ''metadata'': Defaults to an empty dictionary * ''flavors'': Any specified flavors will cause this message's metadata value to be updated to contain the flavor's metadata; defaults to an empty list '''timer(name, timestamp=None, logger=None, severity=6, metadata=None, flavors=None, rate=1)''' Can be used as either a context manager or a decorator. Will calculate the time required to execute the enclosed code, and will generate and send a metlog message containing the timing information upon completion. ''name'' is a required string label for the timer that will be added to the message metadata. ''rate'' represents what fraction of these invocations should actually be timed, so a value of 0.3 would mean that the code would be timed and the results sent off approximately 30% of the time it was executed. '''incr(name, timestamp=None, logger=None, severity=6, metadata=None, flavors=None)''' : Sends an "increment counter" message to metlog. ''name'' is a required string label for the counter that will be added to the message metadata.
== Use Cases ==
