Skip to main content

A wrapper around the Tornado web framework that supports logs with traceId.

Project description

    _____            _ 
   |_   _|   _ _ __ | |__  based on Tornado
     | || | | | '_ \| '_ \ / _ \ / _ \| '_ \ 
     | || |_| | |_) | | | | (_) | (_) | | | |
     |_| \__, | .__/|_| |_|\___/ \___/|_| |_|

Typhoon is a wrapper around the Tornado web framework. It offers the ability to attach log records with a trace id, which is used to trace individual HTTP requests. By default Typhoon obtains trace id from the request's header X-TRACEID. To change this behavior, subclass typhoon.web.Application and overwrite the get_trace_id method.


  • tornado >= 5.1


  • Use pip:
    pip install typhoon-web
    pip install typhoon-web --upgrade
  • Clone repository and install with:
    python install

Hello, world

Here is a simple “Hello, world” example web app for Typhoon:

import logging
import time

import tornado.ioloop
import typhoon.web
import typhoon.log

class MainHandler(typhoon.web.RequestHandler):
    def process(self):'go to sleep')
        time.sleep(3)'wake up')
        return 'Hello, world'

    async def get(self):
        result = await self.process()
    # Native coroutine (using async def and await) was introduced in Python 3.5.
    # For previous version, use generator-based coroutine. 
    # For example:
    # @tornado.gen.coroutine
    # def get(self):
    #     result = yield self.process()
    #     self.write(result)

def make_app():
    return typhoon.web.Application([
        (r'/', MainHandler),

if __name__ == '__main__':
    app = make_app()

In this example, three different log files will be generated in the log_path:

  • access.log records summaries of each http request.
  • stats.log records messages for statistics and analysis.
  • app.log contains all logs that are neither access logs nor stats logs.

To log to stats.log, use an instance of typhoon.log.StatsLogger:

import typhoon.log

stats_log = typhoon.log.StatsLogger(){'user_count': 100}){'job_register': 20}, topic='register')

Notice that logging methods of StatsLogger only accept a dict object as message.

Trace id

By default trace id is automatically obtained and handled by Typhoon only when the client sends a request with a header X-TRACEID: some-value:

$ curl -H "X-TRACEID: ceon1haa6cau1dung1"

To customize the way trace id is passed, subclass typhoon.web.Application and overwrite the get_trace_id method.

import typhoon.web

class MyApplication(typhoon.web.Application):
    def get_trace_id(self, handler):
        # obtain trace id from URL Parameter.
        return handler.get_argument('traceId', '-')

In the above example, trace id is passed through an URL parameter:

$ curl

You may have to call another service and pass down the trace id. In this case, use typhoon.log.TRACE_ID() to obtain current trace id:

import requests
import typhoon.web
import typhoon.log

class MainHandler(typhoon.web.RequestHandler):
    def process(self):
        # call another service and pass down current trace id.
        r = request.get('', header={'X-TRACEID': typhoon.log.TRACE_ID()})
        if r.status_code == 200:
            return 'Hello, world'
            return 'oops!'

    async def get(self):
        result = await self.process()

<font color='green'>[new]</font> High-Level API

For those who are not familiar with Tornado, Typhoon provides high-level api since v1.0.2.

Neither RequestHandler, nor Application. Just subclass, and decorated method with decorator.

Here is a “Hello, world” example.

from import RestController, RestResult, route, start_server
from typhoon.status import OK

class Controller(RestController):
    @route(uri=r'/hello', method='get')
    def greet(self, user=None):
        if user is not None:
            content = f'Hello, {user}'
            content = 'Hello, world'
        return RestResult(status=OK, content=content)

if __name__ == '__main__':
        controller = Controller(),

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

typhoon-web-2.0.0.tar.gz (13.7 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page