Tracing Python — An API
In this article, I'll review a new Python instrumentation version — Oboeware 1.1.
We’ve added a few new libraries recently, but we’re really excited about the new customization API we’ve introduced in this version. More than just a Python bump, this is the first package we’re releasing with an implementation of our new Oboe API. The Oboe API is a common set of idioms and metaphors for extending Tracelytics instrumentation or quickly writing your own from the ground up. We’re excited to get it out there, and we’re even more excited to see what you build with it!
Conceptually, the Oboe API is a multi-tiered system that allows instrumentation of everything from simple function calls to crazy distributed asynchronous event-driven applications. There are three parts: the low-level API, the high-level API, and language-specific functions.
The language-specific functions are just that: language-specific idioms that give you the most tracing bang for your buck. In Python, we’ve put together four:
@tracedecorator allows you to start a trace wherever you want. While we catch most web requests, sometimes it can be valuable to trace your backend processes as well. This can give you visibility into celery jobs, command-line scripts, or cron jobs.
- In an existing trace, the
@log_methoddecorator creates a new layer. We use this extensively in oboeware to actually instrument the standard python libraries like urllib2, pylibmc, or pymongo. If you’ve got an internal API client, or even just a wrapper around an existing library, use this to make sure you’re seeing exactly how performant that library is!
@profile_functionallows you to mark particular blocks of code in your app, and we’ll keep track of them in Tracelytics. If you’ve got a particularly thorny algorithm, or just a lot of log parsing to do, throw it inside a
… and make sure you’re never losing sight of how long that job is taking.
We understand that modifying your code with performance annotations can be trying. These functions aim to be one-line modifications that open up whole new areas of visibility in your app, with no change in functionality.
Do you want to trace your custom-built, high-performance, NumPy simulation library? Are you looking for a simple way to instrument your internal-but-open-sourced RPC protocol? Or do you maybe want to trace all 7 custom tiers in your in your 7-tier web app?
The high-level API provides a logging-like set of functions that report to the Tracelyzer agent. With these functions, you can control exactly what, where, and how you report your performance information. Additionally, this lets you control the key/value pairs reported, which can be used to mark certain layers for special treatment in Tracelytics. For instance, adding the KVOp key identifies the layer as cache. Adding these keys to a fictional hybrid Cassandra / memcache cache would allow visualization in the same place.
Layers introduced by the high-level API aren’t an afterthought — they’re treated exactly the same as any other layer within the Tracelytics interface. Each layer gets its own visualization and a set of filters, and you can set Alerts on it just as you would full requests or application times.
For the truly hardcore, we also have a low-level API. In addition to all of the power and flexibility of the High-Level API, this level adds the concept of a Context — an object that encapsulates the request context needed to trace a request through your full stack, under whatever evented, microthread, or serializable paradigm you’re working.
Build it out!
We hope this release is the start of a long and varied journey to tracing everything under the sun. Are you building something with it? Let us know! Are you thinking about it? Sign up for a free Traceview account, and get started today.