Usage

aiolocals can be used to track any task-local state and comes with integration with aiohttp to track the necessary bits to track request ids across log statements.

Simple example

This example tracks state across all coroutines in the current task. The output will be “foo.bar is baz”:

foo = aiolocals.Local()

@asyncio.coroutine
def do_nothing():
  yield from asyncio.sleep(.1)
  print("foo.bar is {}".format(foo.bar))

with Context(locals=[foo]):
  foo.bar = "baz"
  yield from do_nothing()

Request tracking

To use the built-in aiohttp request tracking functionality, first initialize the logs to include request id information:

aiolocals.configure_logging()

Next, add the context tracking middleware to your aiohttp.web application:

myapp = aiohttp.web.Application(middlewares=[aiolocals.context_middleware_factory])

Now, every log message fired within the handling of a request will include the request id and path information. Ids coming from incoming requests are automatically handled by using the value of the “X-REQUEST-ID” header as the request id.

Job tracking

To track log messages from a single job execution, you can use the job_context() decorator:

@aiolocals.job_context("myjob")
@asyncio.coroutine
def myjob():
  yield from asyncio.sleep(.1)
  print("job complete: {}".format(aiolocals.request.id))

State tracking across tasks

The state tracking works fine as long as there is one root task, but what if your HTTP request handling needs to spawn off other tasks, but you want to keep the same state in these new tasks? Use ‘aiolocals.wrap_async’ to spawn a new task and know that it’ll get a copy of the state automatically.

This example will fire off a background task in the process of handling a request, printing the same request id to the console.

@asyncio.coroutine
def backgrounded_task():
  print("background id: {}".format(aiolocals.request.id))

@asyncio.coroutine
def handler(request):
  print("request: {}".format(aiolocals.request.id))
  aiolocals.wrap_async(backgrounded_task())