Big Data/Analytics Zone is brought to you in partnership with:

A veteran of MIT’s Lincoln Labs, TR is a reformed physicist and full-stack hacker – for some limited definition of full stack. After a few years as Software Development Lead with Thermopylae Science and Techology, he left to join Tracelytics as its first engineer. Following Tracelytics merger with AppNeta, TR was tapped to run all of its developer and market evangelism efforts. TR still harbors a not-so-secret love for Matlab-esque graphs and half-baked statistics, as well as elegant and highly-performant code. Tr has posted 3 posts at DZone. You can read more from them at their website. View Full User Profile

Tracing Python — An API

06.11.2013
| 2745 views |
  • submit to reddit

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.

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:

  • The @trace decorator 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_method decorator 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!
  • The @profile_block and @profile_function allows 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 @profile_block

PythonAPI-1

… 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.

High-Level API
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.

PythonAPI-2

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.

Low-Level API
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.

Related Articles

Published at DZone with permission of its author, Tr Jordan.

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)