Learning OpenTelemetry

Chapter 6. Instrumenting Libraries

The price of reliability is the pursuit of the utmost simplicity. It is a price which the very rich find most hard to pay.

Sir Antony Hoare¹

Internet applications are all very similar. Their code is not written in a vacuum; their developers apply a common set of tools—network protocols, databases, thread pools, HTML—to solve a specific problem. That’s why we call them applications. The tools these applications leverage are called libraries, and that is what we will focus on in this chapter.

Shared libraries are those that have been widely adopted across many applications. Most shared libraries are open source, but not all: two notable proprietary shared libraries are the Cocoa and SwiftUI frameworks provided by Apple. Regardless of its license, the wide adoption of a library can create additional challenges that are not present when you’re instrumenting ordinary application code. When we use the term library in this chapter, this type of shared library is what we mean.

OpenTelemetry is designed for library instrumentation. If you’re a maintainer of one of these libraries, this chapter is for you. Even libraries that are internal to a single organization will benefit from the advice that follows. If you’re just looking for best practices, you’ll find those sections at the end of the chapter.

As a maintainer, the idea of instrumenting your own library may be a novel concept. We call this practice native instrumentation, and we hope to convince ...