API Reference

Application Configuration

class divak.api.Recorder(*args, **kwargs)

Imbues an application with recording abilities.

add_divak_propagator(propagator)

Add a propagation instance that inspects each request.

Parameters:propagator – a propagator instance to inspect requests and potentially modify responses

add_divak_reporter(reporter)

Add a reporter instance.

Parameters:reporter – a reporter instance to receive observations

log_request(handler)

Override log_request to improve logging format.

Parameters:handler (tornado.web.RequestHandler) – the handler that processed the request

set_divak_service(service_name)

Set the name of the service for reporting purposes.

Parameters:service_name (str) – name to use when reporting to an observer

Header Modifiers

class divak.api.RequestIdPropagator(header_name='Request-Id', *args, **kwargs)

Propagates Request-IDs between services.

Parameters:

• header_name (str) – the name of the request header to propagate. If this value is unspecified, then the header name defaults to Request-ID.
• value_factory – if this keyword is specified, then it’s value is called to generate a response header if a new header value is required. If this value is unspecified, then a UUID4 will be generated.

This class implements propagation of a request header into the response. If the incoming request does not include a matching header, then a new value will be generated by calling value_factory. You can disable the generation of new values by setting value_factory to None.

An instance of HeaderRelayTransformer is wired in to transform the request output by inserting the header value from the divak_request_id property of the active request.

handle_request(request)

Initial transform function.

Parameters:request (tornado.web.httpserver.HTTPRequest) – the request that is being processed Returns:a new instance of HeaderRelayTransformer that is configured to insert the request ID header Return type:HeaderRelayTransformer

This function is called to process each request. It pulls the header value out of the request and assigns it to request.divak_request_id. If the incoming request does not have a request ID header, then a new value may be generated before assigning it. Finally, a new instance of HeaderRelayTransformer is created to process the output generated by processing request.

install(application)

Install the propagator into the application.

Parameters:application (tornado.web.Application) – the application to install this propagator into Returns:True if the propagator wants to be called in the future or False otherwise Return type:bool

Observation Points

class divak.api.Logger(*args, **kwargs)

Imbues a tornado.web.RequestHandler with a contextual logger.

This class adds a logger attribute that inserts divak tags into the logging record. Tags added by calling add_divak_tag() are automatically made available in log messages. The divak_request_id value is guaranteed to be available in all log messages provided that you are using Application in your application’s class list.

The logger attribute is set in prepare() and will wrap an existing logger attribute or create a new one using the self’s class module and class name as the logger name.

logger

A logging.LoggerAdapter that inserts divak tags into log records using the extra dict.

Test Helpers

class divak.testing.RecordingLogHandler(*args, **kwargs)

Log handler that keeps track of log records.

Install an instance of this class as a handler on a logging.Logger to keep track of messages that are logged.

records

list of logging.LogRecord instances for messages that were logged.