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
-
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 thedivak_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 headerReturn 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 ofHeaderRelayTransformer
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 orFalse
otherwiseReturn type: bool
- header_name (str) – the name of the request header to propagate.
If this value is unspecified, then the header name defaults to
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 callingadd_divak_tag()
are automatically made available in log messages. Thedivak_request_id
value is guaranteed to be available in all log messages provided that you are usingApplication
in your application’s class list.The
logger
attribute is set inprepare()
and will wrap an existinglogger
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 theextra
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
oflogging.LogRecord
instances for messages that were logged.
-