What Is an Instrumentation Library in OpenTelemetry?
A beginner-friendly guide to the ready-made add-ons that teach popular libraries and frameworks to report on themselves: what they are, how they work, how they differ from the SDK and the API, and how to use them wisely.
Imagine you buy a modern car and want to know how it is doing. You could hire an engineer to drill into the engine, fix a sensor to every moving part, and wire them all to a dashboard. That would take weeks and require deep knowledge of the engine. Or you could plug a small diagnostic device into the port that the manufacturer already provides, and instantly see speed, temperature and fuel use. Software has the same two choices. You can add measuring code to every part of your program by hand, or you can use a ready-made add-on that already knows how to measure a particular popular component. That add-on is called an instrumentation library.
This guide starts from zero. You do not need to know what instrumentation is, what a library is, or why anyone would build a library whose only job is to watch another library. We will build each idea step by step, using everyday comparisons and simple pictures, until you can explain the topic to a colleague with confidence.
1The Problem: Software Does Not Report on Itself
Before we meet the instrumentation library, let us feel the work it removes.
Software is silent by default
When a program runs, it does thousands of things: it receives web requests, reads from databases, sends messages, calls other services and writes files. By default, none of this is visible from the outside. The program does not announce “I just spent forty milliseconds waiting for the database”. Unless someone has added code to measure and report it, the information simply disappears.
What is instrumentation?
Instrumentation means adding the ability for software to produce telemetry, which is data about its own behaviour, such as traces, metrics and logs. The word comes from scientific instruments: a thermometer or a pressure gauge is an instrument that makes something invisible visible. Instrumenting software means attaching such gauges to it.
The cost of doing it all by hand
A typical application uses many popular components. It might use a web framework to receive requests, a database driver to talk to storage, a message client to publish events, and an HTTP client to call other services. To trace a single request through all of these by hand, a developer would have to find every place where each component is used and wrap it with measuring code. In a large system, that could mean thousands of places, and every new feature would add more. It is slow, repetitive and easy to get wrong.
Imagine a city that wants to count the cars passing through every junction. One approach is to send a worker to stand at each junction with a notepad. Another approach is to install standard traffic counters, built by experts, that clip neatly onto the standard lamp posts used in every junction. Instrumentation libraries are those standard counters, built once and reused everywhere.
Many beginners think that adding observability means rewriting their application. In most cases, it does not. Instrumentation libraries let you gain a great deal of visibility with little or no change to your own code.
2A Quick Refresher: OpenTelemetry in One Page
The instrumentation library is one piece of a larger puzzle, so let us see the whole picture.
OpenTelemetry, often shortened to OTel, is an open-source project that defines a common way for software to create and send telemetry. It brings several parts together.
Specification
The written rulebook describing what traces, metrics and logs must look like.
API
A thin set of interfaces that code uses to create telemetry. It describes what can be done, but does not do the heavy work itself.
SDK
The engine that actually processes, batches and exports telemetry. It is chosen and configured by the application owner.
Instrumentation Libraries
Ready-made add-ons that use the API to create telemetry on behalf of popular libraries and frameworks. This is our topic.
Collector
A separate program that receives, processes and forwards telemetry to monitoring tools.
Semantic Conventions
Agreed names and meanings for common attributes, so telemetry from different sources looks consistent.
flowchart LR
A["Your application code"] --> L["Libraries you use: web, database, messaging"]
I["Instrumentation libraries"] -->|"watch"| L
I -->|"call"| API["OpenTelemetry API"]
A -->|"manual calls"| API
API --> SDK["OpenTelemetry SDK"]
SDK --> EX["Exporter"]
EX --> COL["Collector and backend"]
Think of a restaurant. The API is the standard order form that every waiter uses. The SDK is the kitchen that actually prepares and delivers the food. Instrumentation libraries are trained waiters stationed at particular tables, who already know how to fill in the order form for that table’s usual requests, so the kitchen receives clear, consistent orders.
3So, What Is an Instrumentation Library?
A plain definition first, then the reasons behind each word.
An instrumentation library is a piece of software whose job is to produce OpenTelemetry telemetry on behalf of another library or framework. It sits beside a popular component, such as a web framework or a database driver, notices when that component does something interesting, and records a span, a metric or a log about it, using the OpenTelemetry API.
The library being watched is called the instrumented library. The add-on that does the watching is the instrumentation library. These two names are easy to mix up, so keep the roles clear: one is the patient, the other is the doctor with the stethoscope.
It watches another library
Its purpose is to observe something else, not to do business work. It does not serve web pages or store data. It only reports on those who do.
It speaks the OpenTelemetry language
It creates spans, metrics and logs using standard names and shapes, so every monitoring tool can understand them.
It saves you from writing the same code again
Experts write the measuring code once, test it, and share it. Thousands of applications then benefit without each writing their own.
4Examples: What Instrumentation Libraries Actually Do
The idea becomes clear when you see what these add-ons record.
Every popular kind of component has a matching instrumentation library in most languages. Here are the most common families and what each typically records.
| Kind of Component | What the Instrumentation Library Records | Typical Details Captured |
|---|---|---|
| Web server framework | A span for each incoming request, and metrics for request counts and durations | Method, route, status code, duration |
| HTTP client | A span for each outgoing call to another service | Target address, method, result, duration |
| Database driver | A span for each query or command | Database type, operation, duration, errors |
| Message queue client | Spans for publishing and receiving messages | Queue name, operation, message size |
| Cache client | A span for each cache read or write | Operation type, hit or miss, duration |
| Remote procedure call framework | Spans for each call, both client and server side | Service name, method name, status |
| Runtime and process | Metrics about memory, threads and garbage collection | Memory used, thread count, pause times |
A worked example in words
Suppose a customer clicks “Buy”. The web framework’s instrumentation library notices the incoming request and starts a root span. Your code runs, and calls the payment service using an HTTP client. The client’s instrumentation library creates a child span and also writes the trace context into the outgoing call. Inside the payment service, its own web framework instrumentation picks up that context and continues the same trace. A database driver library records a span for each query. Without you writing a single line of tracing code, a connected trace of the whole request appears on your dashboard.
sequenceDiagram
participant C as Customer
participant W as Web Framework plus its instrumentation
participant H as HTTP Client plus its instrumentation
participant P as Payment Service plus its instrumentation
participant D as Database Driver plus its instrumentation
C->>W: Click Buy
Note over W: Instrumentation starts root span
W->>H: Your code calls payment
Note over H: Instrumentation starts child span, injects context
H->>P: Request with trace context
Note over P: Instrumentation extracts context, continues trace
P->>D: Query
Note over D: Instrumentation records database span
D-->>P: Result
P-->>H: Reply
H-->>W: Reply
W-->>C: Confirmation
Think of a relay race where each runner wears a small tracker that records their lap time and automatically passes the race number to the next runner. The coach does not need to time anyone by hand. The trackers, fitted by experts, do it all and join the results into one race report.
5Three Ways Telemetry Gets Into a Library
An instrumentation library is only one of several routes, and it helps to compare them.
Native Instrumentation
The library itself contains OpenTelemetry calls, written by its own authors. No add-on is needed. This is ideal, because the experts who know the library best maintain the telemetry.
Instrumentation Library
A separate add-on, often written by the OpenTelemetry community, hooks into the library from outside and produces telemetry on its behalf.
Manual Instrumentation
You, the application developer, add OpenTelemetry calls to your own code for the business steps that matter to you.
| Question | Native | Instrumentation Library | Manual |
|---|---|---|---|
| Who writes the telemetry code? | The library’s own authors | The community or a vendor | You |
| Extra package needed? | No | Yes | Only the API |
| Depth of knowledge | Deepest, from the inside | Good, limited by available hooks | Exactly what you choose |
| Maintenance burden on you | Lowest | Low, but you must keep versions compatible | Highest |
| Best for | Libraries designed for observability | Popular libraries that lack native support | Your own business logic |
Why native is the goal, and add-ons are the bridge
In the long run, the best situation is for every library to include its own OpenTelemetry support, so that nobody needs an extra add-on. Many modern libraries are heading this way. But the world is full of older libraries whose authors have not yet added native support, and some never will. Instrumentation libraries bridge that gap, so you can get visibility today.
If a library already has native OpenTelemetry support, you normally do not need an instrumentation library for it. Check the library’s documentation first, and avoid enabling both, because they may both create spans for the same work.
6How an Instrumentation Library Works Without Changing Your Code
The trick is that it hooks into the library from the outside.
You may wonder how an add-on can watch a library without the library’s authors changing anything. The answer depends on the programming language, but they all follow the same idea: find a place where the library’s behaviour passes through, and attach a listener there.
Built-in Hooks and Events
Some libraries publish events or offer plug-in points, such as middleware or interceptors. The add-on simply registers itself there.
Wrapping
The add-on provides a thin wrapper around the original library. Your code uses the wrapper, which does the measuring and then calls the original.
Runtime Patching
In languages that allow it, the add-on swaps or wraps functions of the library while the program starts, so every call passes through the measuring code.
Bytecode Agents
In some languages, a special agent modifies the compiled code as it loads, inserting measuring steps at well-known places without touching the source.
Kernel-Level Observation
For compiled languages that offer few hooks, a separate tool can observe calls from outside the program at the operating-system level and produce spans from what it sees.
Imagine a water pipe that you want to measure. You could use the meter port the plumber already left (built-in hook), fit a new section of pipe with a meter (wrapper), strap a clamp-on sensor around the outside (runtime patching or agent), or listen to the vibrations from the wall (kernel-level observation). The water flows exactly as before, but now someone is watching it.
Zero-code and low-code
The best-known experience is called automatic instrumentation or zero-code instrumentation. In several languages, you start your application together with an OpenTelemetry agent or launcher, set a few options such as the service name and destination, and a whole set of instrumentation libraries are switched on at once. Your source code stays untouched. In other languages, you add a short setup step that registers the instrumentation libraries you want, which is called low-code.
“Automatic means magic and covers everything.” Automatic instrumentation covers the popular libraries it knows about. It cannot understand your own business steps, such as “calculate loyalty discount”. For those, you add a few manual spans yourself.
7The API and SDK Split: Why Libraries Depend Only on the API
A clever design keeps instrumentation libraries lightweight and safe.
Remember that OpenTelemetry separates the API from the SDK. The API is a thin set of interfaces: it lets code say “start a span” or “record a number”. The SDK is the engine that decides what happens to those requests, including how to batch them and where to send them. An instrumentation library uses only the API. It never chooses an exporter, a sampling rule or a destination. Those decisions belong to the application owner, who installs and configures the SDK.
Why Depending Only on the API Is Good
- The library stays small and has few dependencies
- If no SDK is installed, the calls do almost nothing and cost very little
- The application owner alone decides where telemetry goes
- Library authors can add telemetry without forcing a vendor choice
If a Library Bundled Its Own SDK
- Two engines might conflict inside one application
- Users would be forced to accept the library’s choices
- Dependencies would grow and clash between libraries
- Changing destinations would require changing the library
Think of a standard electric wall socket. Every appliance maker builds a plug that fits the socket, but none of them builds their own power station. The power company decides how electricity is produced. The API is the socket, the instrumentation library is the appliance’s plug, and the SDK is the power company that you choose.
What happens when no SDK is present
If an application does not install an SDK, the API quietly falls back to a “no-operation” behaviour. Calls to start spans or record metrics are accepted and discarded at almost no cost. This means a library can include instrumentation safely, even if most of its users never turn telemetry on.
If you ever see no telemetry at all after adding instrumentation libraries, check that an SDK is installed and configured. Without it, everything is being politely thrown away.
8Instrumentation Scope: The Name Tag on Every Signal
Every piece of telemetry says which instrumentation library produced it.
When an instrumentation library obtains a tracer, a meter or a logger from the SDK, it identifies itself with a name and, usually, a version. This identity travels with all the telemetry the library creates, and it is called the instrumentation scope. In older documents, you may see the phrase “instrumentation library” used for the same idea, because the name of the scope was originally the name of the library that created the telemetry. The newer wording, scope, is more accurate, because telemetry can come from any named piece of code, not only from a library.
Name
Identifies the code that produced the telemetry, such as the instrumentation library for a particular web framework.
Version
The version of that code, so that behaviour changes between versions can be spotted.
Schema Address
Optionally points to the version of the naming rules the telemetry follows, helping tools handle changes over time.
Attributes
Optional extra labels describing the scope itself.
Why the scope matters
The scope is a powerful debugging aid. If you notice strange or duplicated spans, the scope tells you which instrumentation library created them. If a bug is fixed in version two of a library, you can find telemetry from version one and know why it looks different. Tools can also let you switch off or filter telemetry from one noisy scope without touching the rest.
Think of the maker’s mark stamped on every piece of pottery in a shop. If one piece has a crack, the mark tells you which workshop and which batch made it. The instrumentation scope is the maker’s mark on every span, metric and log.
A good habit during an investigation is to group telemetry by scope name. It quickly shows which libraries are producing the most data and which are responsible for odd results.
9Following the Common Language: Semantic Conventions
A good instrumentation library speaks the shared vocabulary.
If every instrumentation library invented its own attribute names, a database span from one library would look nothing like a database span from another. OpenTelemetry therefore publishes semantic conventions, which are agreed names, units and meanings for common situations such as web requests, database calls, messaging and cloud services.
Instrumentation libraries are the main carriers of these conventions. When a library records a web request, it uses the standard attribute names for method, route and status. When it records a database call, it uses the standard names for the database system and the operation. Because of this, a monitoring tool can recognise a database span from any library, draw a ready-made database dashboard, and compare behaviour across different systems.
Consistent span names
Libraries follow naming rules, such as using the route pattern rather than the full address, so span names stay few and meaningful.
Standard attributes
Common facts such as method, status code, server address and database operation use the same names everywhere.
Standard units and metric names
Durations are recorded in standard units, and metrics such as request duration have agreed names, enabling shared dashboards.
Evolving over time
The conventions are improved from time to time. Newer versions of an instrumentation library may rename attributes to follow updated conventions, so upgrades can change what your dashboards see.
Upgrading an instrumentation library without reading the release notes. Renamed attributes can silently break saved dashboards and alerts that filter on the old names. Test upgrades in a safe environment first.
10Context Propagation: A Hidden Superpower of Instrumentation Libraries
Instrumentation libraries do far more than start and stop spans.
One of the most valuable jobs of an instrumentation library is carrying the trace context across service boundaries. When your service calls another service, the HTTP client’s instrumentation library automatically writes the current trace identifiers into the outgoing message. When the other service receives it, its web framework’s instrumentation library reads those identifiers and continues the same trace.
This pairing is what makes distributed tracing possible without any effort from application developers. If one side is instrumented and the other is not, the trace breaks into pieces. This is why it is important to cover both the client and the server side of every connection.
The sender’s library starts a span
The client-side instrumentation library notices an outgoing call and starts a span for it.
It injects the context
It writes the trace and span identifiers into the outgoing message, usually as an extra label on the request.
The receiver’s library extracts it
The server-side instrumentation library reads the label from the incoming request.
A child span joins the same trace
The receiver starts a span as a child of the sender’s span, keeping one connected trace.
If your traces appear broken in the middle of a request, look at the boundary where they break. Often one side lacks an instrumentation library, or a gateway in the middle is removing the context labels.
11Finding and Choosing Instrumentation Libraries
There is a large catalogue, so it helps to know where to look.
The OpenTelemetry community maintains instrumentation libraries for many languages, covering popular web frameworks, database drivers, messaging systems and more. Individual projects and vendors also publish their own. The project keeps a public registry on its website where you can search for an instrumentation library by language and by the name of the library you want to observe.
Questions to ask before choosing
Does the library already have native support?
If yes, use it and skip the add-on. Native support is usually the best maintained.
Does the add-on support your library version?
Instrumentation libraries are tied to specific versions of the library they watch. A mismatch can cause missing data or errors.
How mature and active is it?
Look at its stability level, how often it is updated, and whether issues are answered. Some are marked as experimental.
Does it follow current semantic conventions?
Check that its attribute and metric names match the conventions your dashboards expect.
What does it capture, and what does it cost?
Check whether it records sensitive values or large amounts of data, and test its effect on performance.
Installing every available instrumentation library “just in case”. More add-ons mean more data, more cost and more things to maintain. Choose the ones that cover your real critical paths.
12Configuring Instrumentation Libraries
You are not stuck with the defaults.
Most instrumentation libraries offer settings that let you tune what they record. Settings differ from library to library, but several common ideas appear again and again.
Turn On or Off
Enable only the libraries you want, or disable specific ones that are noisy or unneeded.
Ignore Some Requests
Skip health-check and monitoring endpoints that fire constantly and add nothing but volume.
Capture More or Less Detail
Choose whether to record extra details such as selected headers, or whether to record database statements.
Hooks for Custom Labels
Some libraries let you add your own attributes to the spans they create, such as a customer tier.
Resource and service name
Alongside library settings, you must tell the SDK who your service is, using the resource: the service name, version and environment. Every instrumentation library inherits this, so all telemetry from your application carries the same identity. Forgetting to set a service name is one of the most common beginner issues: all traces appear under a generic or unknown name.
Start with defaults, look at the data for a day, and then adjust. Disabling the loud, low-value sources first often cuts costs more than any other single change.
13Combining Automatic and Manual Instrumentation
The best results come from using both together.
Instrumentation libraries give you breadth: every incoming request, every outgoing call, every database query. But they cannot see inside your own business logic. A trace with only library-created spans tells you that a request spent 800 milliseconds inside your service, but not which part of your code took the time. That is where a few manual spans help.
Automatic Instrumentation Gives You
- Fast coverage of all popular libraries
- Consistent names following the conventions
- Context propagation across services for free
- A useful first picture within hours
Manual Instrumentation Adds
- Spans around important business steps
- Attributes meaningful to your domain, such as order type
- Insight into code that uses no popular library
- Business metrics such as orders completed
Automatic instrumentation is like security cameras at every door of a building: you know who comes and goes. Manual instrumentation is a camera inside the one room where something special happens. The door cameras give breadth, and the room camera gives depth.
A sensible approach
Start with automatic instrumentation
Get the skeleton of your traces and key metrics with little effort.
Study real traces
Look for large unexplained gaps inside your service, which point to code worth instrumenting.
Add a few manual spans
Wrap the important business steps and attach attributes you would genuinely search by.
Review and trim
Remove spans nobody uses, and keep naming consistent.
14Writing Your Own Instrumentation Library
Sometimes the library you need has no add-on, and you may build one.
If your company has an internal framework, or if you use a library that has no instrumentation library available, you can write your own. The same principles that guide the community add-ons apply to yours.
Depend only on the API
Never bundle an SDK or choose an exporter inside the library. Leave those decisions to the application owner.
Use a clear name and version for the scope
Name the library so people can recognise which add-on produced the telemetry, and publish its version.
Follow semantic conventions
Use standard attribute names and units wherever they exist, and document any custom ones carefully.
Keep overhead low
Instrumentation runs on hot paths. Avoid heavy work, large allocations and unbounded attribute values.
Never break the host
If telemetry code fails, the library being watched must carry on working. Catch errors, never let observability crash business code.
Propagate context faithfully
Inject and extract trace context at every boundary so that traces stay connected.
Respect privacy
Do not record secrets or personal data by default. Offer opt-in settings for any sensitive details.
Before writing your own, search the registry once more and ask the community. Often an existing add-on can be extended or improved, which is better for everyone.
15Security, Privacy and Performance
Add-ons that watch everything must be handled with care.
An instrumentation library sees what your libraries see, including web addresses, headers, query parameters and sometimes database statements. If it records these without care, it can copy sensitive information into your telemetry. It also runs inside your application, so it uses processor time and memory.
Privacy
Check what is captured by default
Review which headers, parameters and statements each library records. Disable or limit anything that might carry secrets or personal data.
Watch full web addresses
Addresses may include tokens or user identifiers in their query parts. Prefer route patterns, and remove sensitive query values.
Use the Collector as a safety net
Add redaction rules in a Collector so sensitive values are masked before leaving your network, even if a library records them.
Performance
Measure the overhead
Instrumentation is designed to be light, but in busy systems the cost can add up. Test with and without it under realistic load.
Use sampling
Recording every trace in a high-traffic service can be expensive. Sampling reduces volume while keeping what matters.
Disable what you do not need
Switch off instrumentation for libraries that are not on important paths, to save both overhead and data cost.
Supply chain care
Instrumentation libraries are third-party code running inside your application with broad visibility. Treat them like any other dependency: pin versions, review updates, scan for known weaknesses and prefer well-maintained projects.
Problem
A team turns on database instrumentation with full statement capture, and queries containing customer emails and card details are stored in span attributes.
Why It’s Harmful
Sensitive data is copied into a tracing tool with many readers and long retention. A single mistake or leak exposes customer information.
Correct Approach
Capture only the shape of queries, disable statement capture where not needed, and add redaction rules in the Collector as a safety net.
16Best Practices and Anti-patterns
Habits that keep instrumentation useful, light and trustworthy.
Good habits
Prefer native support, then instrumentation libraries
Use a library’s own OpenTelemetry support when it exists, and reach for an add-on only when it does not.
Cover both sides of every connection
Instrument clients and servers, so context propagation keeps traces connected end to end.
Set a clear service name and environment
Define the resource once, so every signal from every add-on says who produced it.
Pin and test versions
Keep instrumentation library versions compatible with the libraries they watch, and test upgrades before release.
Tune the noise
Ignore health checks, disable low-value sources, and limit captured detail to what you really use.
Send through a Collector
It lets you redact, sample and change destinations centrally, without touching application code.
Add manual spans for business steps
Use a few well-named manual spans where automatic coverage cannot see.
Mistakes to avoid
Problem
Both a library’s native OpenTelemetry support and a separate instrumentation library for the same library are enabled at once.
Why It’s Harmful
Each creates its own span for the same work, producing duplicated spans, inflated counts and confusing traces.
Correct Approach
Check which scopes appear in your telemetry, and keep only one source of instrumentation for each library.
Problem
An instrumentation library bundles its own SDK or exporter settings and forces them on every application that uses it.
Why It’s Harmful
It can clash with the application’s own SDK, remove the owner’s control over destinations and sampling, and create dependency conflicts.
Correct Approach
Depend only on the API, and let the application owner configure the SDK.
Problem
Only the web framework is instrumented, while the HTTP client, database driver and message client are left dark.
Why It’s Harmful
Traces show large gaps where outgoing calls happen, and context is never passed to other services, so traces break at the first hop.
Correct Approach
Instrument every library on the request path, including clients, so the trace stays connected.
Problem
Teams upgrade instrumentation libraries automatically with every release, without reading what changed.
Why It’s Harmful
Renamed attributes or changed metric names quietly break dashboards and alerts, and nobody notices until an incident.
Correct Approach
Read release notes, test upgrades in a safe environment, and update saved dashboards together with the library.
17Advantages and Trade-offs
Instrumentation libraries are a huge time saver, with a few costs.
Advantages
- Instant visibility into popular libraries with little or no code change
- Consistent names and attributes that follow semantic conventions
- Automatic context propagation, so traces connect across services
- Expert-written and community-tested telemetry code
- Works with any SDK and any backend through the API
- Can be switched on, off or tuned through configuration
Disadvantages / Trade-offs
- Coverage is limited to libraries that have an add-on
- Cannot see your own business logic without manual spans
- Tied to specific versions of the libraries they watch
- Adds some overhead and may capture more data than you need
- Maturity varies, and some add-ons are still experimental
Approaches compared
| Approach | Effort | Coverage | Best For |
|---|---|---|---|
| Instrumentation libraries only | Very low | Broad, shallow | Getting started quickly |
| Manual instrumentation only | High | Narrow, deep | Small systems or special needs |
| Both together | Moderate | Broad and deep | Most production systems |
| Native library support | Lowest | Deep for that library | Libraries built with observability in mind |
“Instrumentation libraries are the SDK.” They are not. They produce telemetry through the API, while the SDK processes and exports it. You need both an instrumentation library and an SDK for data to reach a monitoring tool.
18Real-World Scenarios
Picture how different teams use instrumentation libraries every day.
A startup gets visibility in an afternoon
A small team has a handful of services and no tracing at all. By starting each service with the OpenTelemetry automatic instrumentation and pointing it at a free open-source viewer, they see connected traces across their web framework, database and message queue before the end of the day, without editing any application code.
A retailer finds a broken trace boundary
Traces end abruptly at one internal service. The team discovers that this service uses an HTTP client with no instrumentation library, so the trace context is never passed on. Adding the matching add-on reconnects the whole chain and exposes a slow call that had been hidden.
A bank avoids leaking data
During a review, the security team notices that database instrumentation is capturing full statements, including customer details. They switch to recording only the query shape and add a redaction rule in the Collector. The change takes an hour and removes a serious risk.
A platform team fixes duplicate spans
Dashboards show twice as many database spans as expected. Grouping by instrumentation scope reveals two scopes producing spans for the same driver: one native and one add-on. Disabling the add-on cuts data volume and clears up the traces.
A company builds its own add-on
A large company has an internal messaging framework with no OpenTelemetry support. A small team writes an instrumentation library that depends only on the API, follows semantic conventions and propagates context. Within weeks, every service using the framework appears in traces consistently.
19Getting Started: A Gentle Path
You do not need to learn everything at once.
List the libraries on your critical path
Write down the web framework, HTTP clients, database drivers and message clients that your most important request uses.
Check for native support and add-ons
Look in each library’s documentation and the OpenTelemetry registry for built-in support or a matching instrumentation library.
Turn on automatic instrumentation for one service
Use the agent or launcher for your language, set a clear service name, and send data to a Collector and a viewer.
Read the first traces
Check that spans appear for each library, that the scope names make sense, and that context flows to other services.
Tune and protect
Ignore health checks, limit captured detail, and add redaction rules in the Collector.
Add a few manual spans and roll out
Instrument key business steps by hand, then repeat the process for the rest of your services.
Your first goal is not complete coverage. It is to see one real trace crossing two services, each instrumented by a ready-made add-on. That moment shows how much work these libraries save you.
20Frequently Asked Questions
It is a ready-made add-on that teaches a popular library or framework to produce OpenTelemetry traces, metrics and logs. It watches the other library from outside and reports what it does, so you do not have to write the measuring code yourself.
The instrumented library is the one being watched, such as a web framework. The instrumentation library is the add-on that does the watching and creates the telemetry. One is the subject, and the other is the observer.
No. The instrumentation library creates telemetry using the API. The SDK is the engine that processes and exports it. You normally need both for data to reach a monitoring tool.
Often not. In many languages, an agent or launcher switches on a whole set of instrumentation libraries without touching your source code. In others, you add a short setup step. Manual spans for your own business logic are optional extras.
Then you usually do not need a separate instrumentation library for it. Using both can create duplicate spans, so keep only one source of instrumentation for each library.
It is the name and version of the code that produced a piece of telemetry, attached to every span, metric and log. It started life as the name of the instrumentation library, and it helps you see which add-on created which data.
So they stay small, never conflict with the application’s chosen SDK, and leave decisions about destinations and sampling to the application owner. If no SDK is installed, the API calls cost almost nothing.
Most often because one side lacks an instrumentation library, so trace context is not injected or extracted, or because a gateway removes the context labels. Check both sides of the broken connection.
They can, depending on their settings, for example by recording headers or database statements. Review what each one captures, limit it to what you need, and add redaction in a Collector as a safety net.
They add a small overhead, which is usually acceptable. In very busy systems, it can add up, so measure under realistic load, use sampling, and disable instrumentation that you do not need.
The OpenTelemetry website has a public registry where you can search by language and by the library you want to observe. Library documentation also tells you about native support or recommended add-ons.
Yes. Depend only on the API, use a clear scope name and version, follow semantic conventions, keep overhead low, never break the library you are watching, propagate context, and avoid recording secrets by default.
21Summary and Key Takeaways
An instrumentation library in OpenTelemetry is a ready-made add-on whose job is to produce telemetry on behalf of another library or framework. It hooks into popular components such as web frameworks, HTTP clients, database drivers and message clients, records spans, metrics and logs using the OpenTelemetry API, and passes trace context across service boundaries so traces stay connected. It depends only on the API, leaving the choice of SDK, sampling and destinations to the application owner, and it labels its output with an instrumentation scope so you can tell which add-on produced which data. Where a library has native OpenTelemetry support, that is usually preferable, and where it does not, an instrumentation library bridges the gap. Combine automatic instrumentation for broad coverage with a few manual spans for your own business logic, tune what is captured, protect sensitive data, pin and test versions, and send everything through a Collector for central control.
Key Takeaways
- It watches another library — an instrumentation library produces OpenTelemetry telemetry for an instrumented library, so you do not write the measuring code yourself.
- It uses only the API — the application owner chooses and configures the SDK, which keeps add-ons light and prevents conflicts.
- Native support comes first — use a library’s own OpenTelemetry support when it exists, and avoid enabling both native and add-on instrumentation for the same library.
- Context propagation connects traces — instrument both client and server sides so trace context is injected and extracted at every boundary.
- The scope is the name tag — every signal carries the name and version of the code that created it, which helps with debugging and filtering.
- Combine automatic and manual — automatic instrumentation gives breadth quickly, and a few manual spans add depth around your business logic.
- Tune, protect and test — limit captured detail, redact sensitive values, ignore noisy endpoints, and test version upgrades before release.