Observability Engineering, 2nd Edition

Chapter 7. Instrumenting Your Code with OpenTelemetry

OpenTelemetry promises a unified standard for telemetry. But, for the uninitiated, it can sometimes feel a bit overwhelming in its complexity. There’s a dizzying array of terminology, a broad application programming interface (API) and SDK surface area, and a learning curve sometimes described as more of a “learning cliff.” Should you use zero-code or library instrumentation? Which signals should you emit? Is switching to OTel even worth the effort?

This chapter is not an in-depth guide for everything you need to know about OTel (for that, we recommend reading Learning OpenTelemetry by Ted Young and Austin Parker). Here, we’ll focus on making OTel less intimidating and more practical to approach. Think of this as your set of ropes, harnesses, belay devices, helmets, and situational awareness training so that you won’t fall off of that learning cliff.

In this chapter, we’ll cover fundamental design philosophies to help you understand why and how OTel is built as the project you see today and how to gauge when it is (or isn’t) a good fit. We’ll also guide you through understanding trace-first design principles in complex architectures you’re likely to encounter. From there, we’ll dive into trade-offs behind its various signal types and how to use them effectively. Lastly, we’ll also show you how AI-assisted coding helps with OTel instrumentation, especially when migrating from other existing frameworks.

What It Means to Use ...