What Is an Instrumentation Agent in OpenTelemetry?
An instrumentation agent is a helper that attaches to your running application and automatically produces traces, metrics, and logs, without you rewriting the application code. It is the fastest way to turn a silent program into one that explains itself.
Imagine you buy an old house and want to know how much electricity each room uses. One option is to tear open every wall and rewire every socket yourself. Another option is to hire an electrician who clips a small sensor onto the main cables, and within an hour you can see the usage of every room. You did not rebuild the house, and the house did not need to know about the sensors. An instrumentation agent is that clip-on sensor for software. It sits beside your application, listens to what the application does, and reports it in a standard language that any observability tool can understand.
1The Problem: Getting Telemetry Without Rewriting Everything
Observability sounds wonderful until you realize how much work it takes to add it by hand.
The cost of adding telemetry manually
Observability means being able to understand what your software is doing from the data it sends out. That data is called telemetry, and it comes in three main forms: traces, which follow a request through your system, metrics, which count and measure things, and logs, which record events. To produce telemetry, somebody has to write code that creates spans, increments counters, and writes log records at the right places.
For a small program, this is manageable. For a company with hundreds of services, written in several programming languages, using many libraries for web servers, databases, and message queues, it becomes a huge project. Every team must learn the instrumentation library, decide where to place the calls, and keep that code correct as the application changes. Many organizations stall at this step and stay blind for months.
The hidden problem of old and third-party code
There is another obstacle. Not all the code running in your application is code you wrote. Your program uses frameworks, database drivers, and client libraries written by other people. You cannot easily edit their source code to add telemetry. Some applications are old, and nobody on the current team knows how they work. Others are packaged products that you can configure but not modify.
Think of a school that wants to track attendance. Asking every teacher to maintain a separate notebook takes weeks of training and gives inconsistent results. Installing a card reader at the school gate gives you attendance for every student on the first day, in the same format, without changing how any teacher teaches.
An instrumentation agent exists to give you useful telemetry quickly, from code you did not write and may not be able to change, with little or no code changes of your own.
2A Quick Refresher on the OpenTelemetry Building Blocks
A few terms need to be clear before we look at what an agent does.
Instrumentation
The act, or the code, that observes your application and creates telemetry. For example, code that starts a span when a web request arrives and ends it when the response is sent.
API
The small set of interfaces that instrumentation code calls to create spans and record metrics. It describes what can be done, without deciding where the data goes.
SDK
The working engine behind the API. It collects the data, applies sampling and limits, and sends the result to an exporter.
Exporter
The part that sends telemetry out, usually using the OpenTelemetry Protocol, called OTLP, to a Collector or to a backend.
Resource
A description of the thing producing the telemetry, such as the service name, version, host, and cloud region. It labels every piece of data with its origin.
Two ways to add instrumentation
OpenTelemetry offers two broad approaches. In code-based instrumentation, developers add OpenTelemetry calls directly in the application’s source code. In zero-code, or automatic, instrumentation, a separate component is attached to the application and adds the telemetry from the outside. The instrumentation agent belongs to the second approach.
The API is the plug socket shape, the SDK is the power station behind the wall, and the exporter is the cable carrying power away. An instrumentation agent is an electrician who installs the sockets for you across the whole building.
3So, What Exactly Is an Instrumentation Agent?
A plain definition first, then the details that matter in practice.
The definition
An instrumentation agent is a software component that is attached to an application at startup, or into the running environment of the application, and that automatically adds OpenTelemetry instrumentation to the libraries and frameworks the application uses. It typically bundles together the OpenTelemetry API and SDK, a large collection of ready-made instrumentation for popular libraries, and default configuration for exporting data. The application’s own source code does not have to be modified.
What it gives you out of the box
Spans for incoming requests
When your application receives a web request, the agent starts a span, records details such as the method and route, and ends the span when the response is complete.
Spans for outgoing calls
When your application calls a database, another service, or a message broker, the agent creates child spans that show how long each call took.
Context propagation
The agent passes trace identity along to other services through headers or message properties, so that traces connect across service boundaries.
Metrics and logs where supported
Many agents also produce standard metrics, such as request counts and durations, and can link logs to the active trace.
Exporting
The agent sends the collected data out using a configured exporter, normally to an OpenTelemetry Collector or directly to a backend.
An agent does not understand your business. It sees technical events such as web requests and database calls. It does not know that a particular function means “approve a loan” unless you add that meaning yourself.
4Clearing Up a Confusing Word: Three Meanings of “Agent”
The word “agent” is used in several ways in the observability world, and mixing them up causes real confusion.
Meaning one: the instrumentation agent
This is the topic of this tutorial. It is attached to the application itself and produces telemetry from inside the application process, or very close to it.
Meaning two: the Collector in agent mode
The OpenTelemetry Collector is a separate program that receives, processes, and exports telemetry. When it is deployed next to each application or on each host, it is often said to run in agent mode. That Collector does not create telemetry from your application code. It collects and forwards data that other things produced.
Meaning three: vendor monitoring agents
Many commercial monitoring products ship their own proprietary agents. These attach to applications in similar ways, but they send data in vendor-specific formats. OpenTelemetry agents instead use open standards that can be sent to many different backends.
| Term | Where it runs | What it does | Produces telemetry from your code? |
|---|---|---|---|
| Instrumentation agent | Attached to the application process | Adds spans, metrics, and logs automatically | Yes |
| Collector in agent mode | Separate process on the same host or pod | Receives, processes, and forwards telemetry | No, it handles data from others |
| Collector in gateway mode | Central shared service | Aggregates and routes telemetry from many sources | No |
| Vendor proprietary agent | Attached to the application or host | Collects data in a vendor’s own format | Yes, but in a closed format |
A reporter who goes to the scene and writes the story is like an instrumentation agent. A courier who picks up finished stories and delivers them to the newspaper is like a Collector. Both are called “agents” in casual speech, but they do very different jobs.
Most healthy setups use both: an instrumentation agent inside each application, sending data to a Collector, which then forwards it to one or more backends.
5How Agents Work: The Trick Behind the Magic
Automatic instrumentation sounds like magic, but the trick is different for each language.
The common idea
Every agent has to solve the same puzzle: how can new behavior be added to code that was written without it? The answer is to intercept the code at a moment when it is being loaded or run, and wrap it with extra steps that record telemetry. The original behavior is preserved, but now there is a before-step that starts a span and an after-step that ends it.
Java
The agent is a packaged file attached when the program starts. It uses a hook provided by the Java platform to modify the compiled code of known libraries as they are loaded, inserting telemetry steps around their methods.
.NET
The agent hooks into the runtime’s startup and profiling features to modify code or attach to library events, so that common libraries are observed automatically.
Python
A launcher command starts the program after wrapping supported libraries with instrumented versions. This approach of replacing functions at runtime is often called monkey patching.
Node.js
A module loaded before the application intercepts the loading of supported packages and wraps their functions, so that telemetry appears without changing application code.
Go and other compiled languages
Compiled programs are harder to modify at runtime. Approaches include kernel-level observation using a technology called eBPF, or build-time tooling. Maturity and capabilities vary, so check current documentation.
flowchart LR
APP["Application code and libraries"] --> HOOK["Agent hook at load or run time"]
HOOK --> WRAP["Libraries wrapped with telemetry steps"]
WRAP --> SDK["OpenTelemetry SDK"]
SDK --> EXP["Exporter sends data out"]
Imagine a security guard who stands at the entrance of each shop, notes who walks in and out, and then lets them continue. The shops did nothing special. The guard watches at the doorway, and that is where the interception happens.
An agent can only observe the libraries it has been taught about. If you use an obscure or very new library, the agent may not create spans for it. Always check the list of supported libraries and versions for the agent you use.
6A Closer Look at One Example: The Java Agent
The Java agent is the best-known example and a good way to see the lifecycle of an agent step by step.
How it is attached
The Java agent is distributed as a single packaged file. To use it, you tell the Java runtime to load that file when starting the application, using a standard startup option for agents. No code in the application is changed, and no new dependency is added to the application’s build.
The lifecycle
The runtime starts and loads the agent first
Before the application’s main entry point runs, the Java runtime gives the agent a chance to run its startup logic.
The agent reads configuration
It reads settings such as the service name, exporter destination, and sampling choices from environment variables and system properties.
The agent registers a transformer
It asks the runtime to notify it every time a class is about to be loaded. This is the key hook that makes automatic modification possible.
Known libraries are modified as they load
When a class from a supported library, such as a web server or a database driver, is loaded, the agent rewrites it in memory to add telemetry steps around key methods.
The application runs normally
From the application’s point of view, nothing changed. But each time a wrapped method runs, a span is created, timed, and recorded.
Telemetry is batched and exported
The embedded SDK collects finished spans and metrics, groups them, and sends them to the configured destination in the background.
Because the agent modifies libraries as they load, it has to be present from the very start. Attaching an agent to an already running program is much more limited, so the common practice is to include the agent in the startup command.
Think of a film crew that sets up cameras before the play begins. They cannot place cameras in the middle of the performance without disturbing it. In the same way, the agent prepares its hooks before the application starts running.
Example: Instrumenting an existing order service
A team has an order service built years ago using a common web framework and a relational database. Without touching the source code, they add the agent to the startup command and set the service name and exporter destination. Within minutes, traces show every request, every database query, and every outgoing call, with timings.
7What the Agent Produces: Spans, Attributes, and Resources
The agent does not just create timers. It describes each event in a standard vocabulary so that tools can understand it.
Semantic conventions
OpenTelemetry defines semantic conventions, which are agreed names and meanings for the details attached to telemetry. For example, there are standard names for the HTTP method, the response status code, the database system, and the destination of a message. Agents apply these names automatically, so data from different languages and libraries looks consistent.
Span kinds
Agents label spans by their role. A server span represents work done in response to an incoming request. A client span represents an outgoing call. A producer and a consumer span represent sending and receiving messages. These labels let tools draw service maps and understand who called whom.
Resource information
Every piece of data from an agent carries resource details that describe where it came from. These include the service name, which you should always set explicitly, along with details the agent can detect itself, such as the host name, the process, and the language runtime. In cloud environments, extra detectors can add the cloud provider, region, and container details.
| Thing observed | Typical span role | Typical details recorded |
|---|---|---|
| Incoming web request | Server | Method, route, status code, request size |
| Outgoing web call | Client | Method, destination, status code, duration |
| Database query | Client | Database system, operation name, query text after cleaning |
| Message sent to a broker | Producer | Destination name, messaging system, message size |
| Message received | Consumer | Destination name, processing time, link to producer |
If you forget to name your service, the agent may fall back to a generic or unknown name. Telemetry from many services will then be mixed together, which makes dashboards confusing and traces hard to read.
Semantic conventions are like the labels on a medicine box: a fixed set of fields such as name, dosage, and expiry, in a standard place. Any pharmacist anywhere can read them, regardless of who made the medicine.
8Configuring an Agent Without Touching Code
Since you cannot change the code, configuration is done from the outside, and OpenTelemetry has a standard way to do it.
Environment variables as the common language
OpenTelemetry defines a set of standard environment variables that all compliant agents and SDKs understand. An environment variable is a named setting passed to a program by the system that launches it. This makes it easy to configure agents in containers and cluster platforms, where environment variables are the usual way to pass settings.
OTEL_SERVICE_NAME
The name of your service as it will appear in tools. This is the single most important setting to provide.
OTEL_RESOURCE_ATTRIBUTES
Extra labels for your service, such as the version, the environment name, or the team that owns it, written as a list of key-value pairs.
OTEL_EXPORTER_OTLP_ENDPOINT
The address where telemetry is sent, usually a Collector. Protocol and header settings are also available.
OTEL_TRACES_SAMPLER
Controls how many traces are kept, from keeping everything to keeping a fraction. A companion setting provides the sampling argument, such as the ratio.
OTEL_PROPAGATORS
Selects the format used to pass trace context between services. The default is the W3C standard along with baggage.
Per-instrumentation switches
Many agents allow individual library instrumentations to be turned on or off, which helps reduce noise or avoid conflicts.
Configuration layers
In practice, configuration comes from several places. The agent has built-in defaults. Environment variables override defaults. Some agents also accept system properties, configuration files, or startup options. When settings conflict, the more specific or more explicit source usually wins, so it is wise to read the documentation of your specific agent.
Names, defaults, and availability of settings can differ between languages and versions, and some are still evolving. Treat the list above as a map of the common ones, and confirm details in the documentation of the agent you actually run.
Environment variables are like the settings dial on a washing machine. You do not open the machine to rewire it. You turn the dial to choose temperature, spin speed, and duration, and the machine behaves accordingly.
9Zero-Code, Code-Based, and the Hybrid Approach
Agents are powerful, but they are not the whole story. The best setups often combine both styles.
What each style is good at
| Aspect | Instrumentation agent (zero-code) | Code-based (manual) |
|---|---|---|
| Time to first data | Minutes | Days to weeks |
| Code changes needed | None or very few | Throughout the application |
| Coverage of third-party libraries | Excellent for supported libraries | Poor, you cannot modify them |
| Business meaning | Low, it sees technical events | High, you name what matters |
| Control and precision | Limited to what the agent offers | Complete |
| Runtime overhead | Moderate, depends on coverage | Depends on what you add |
| Maintenance effort | Update the agent version | Maintain the instrumentation code |
The hybrid approach
The most effective approach is usually a blend. Start with the agent to get broad coverage of web requests, database calls, and messaging. Then add a small amount of manual instrumentation for the business moments that the agent cannot know about, such as “calculate discount” or “verify identity.” The manual spans automatically become children of the agent’s spans, because they share the same current context.
This works because the agent and the manual code both use the same OpenTelemetry API and the same SDK. Spans created by hand and spans created automatically live in the same trace and are exported through the same pipeline.
graph TD
A["Agent creates server span for the order request"] --> B["Manual span: calculate discount"]
A --> C["Agent creates client span: database query"]
A --> D["Agent creates client span: call payment service"]
B --> E["Manual span: apply promotion rules"]
Example: Adding business meaning
A bank uses the agent for broad coverage of its loan service. The team then adds three manual spans around risk scoring, document checks, and final approval. Engineers now see not just that the service was slow, but that risk scoring took most of the time.
Begin with zero-code and look at the data for a week. Only add manual instrumentation where you find real gaps. This avoids writing code that duplicates what the agent already gives you.
10Deploying Agents in Containers and Kubernetes
Modern applications mostly run in containers, so how an agent gets into a container matters a great deal.
Baking the agent into the image
The simplest method is to include the agent file in the application’s container image and change the startup command or environment so that the agent loads. This is easy to understand and works anywhere, but it requires rebuilding images whenever you update the agent.
Using an init container or shared volume
In Kubernetes, a common approach is to use an init container, which is a short helper container that runs before the main container. It copies the agent files into a volume shared with the application container. The application then starts with the agent available, without changing the application image.
The OpenTelemetry Operator
The OpenTelemetry Operator for Kubernetes can automate this injection. You describe the instrumentation settings once in a cluster resource, and then add an annotation to a workload to request injection for a given language. The operator modifies the pod to include the agent and the standard environment variables. This means platform teams can roll out instrumentation across many services without asking each team to edit its images.
Platform team defines instrumentation settings
They describe the exporter destination, sampling choices, and language agents in a cluster-level resource.
A workload is annotated
The application team adds a simple annotation to their deployment, naming the language they use.
The operator modifies the pod when it is created
It adds an init container, a shared volume, and environment variables, so the agent loads when the application starts.
The application restarts with the agent attached
Telemetry begins to flow to the configured Collector, with no changes to the application’s source code or image.
flowchart LR
ANN["Annotated workload"] --> OP["OpenTelemetry Operator"]
OP --> INIT["Init container copies agent files"]
INIT --> VOL["Shared volume"]
VOL --> APP["Application container with agent loaded"]
APP -->|"OTLP telemetry"| COL["Collector"]
COL --> BE["Backends"]
Operator features and supported languages change over time, and some languages are better supported than others. Check the operator documentation for your cluster version before building a plan around it.
Think of a hotel that installs smart meters in every room using a standard procedure. Guests do nothing differently. The hotel management simply adds a label to each room’s order sheet, and the electrician fits the meter during the next cleaning round.
11A Request’s Journey Through an Agent-Instrumented Service
Let us follow one request to see how the agent weaves telemetry through ordinary application behavior.
The scenario
A customer opens an order page. The request reaches a shopping service, which reads from a database and calls a pricing service. The shopping service runs with an instrumentation agent. The pricing service also runs with an agent, and both send data to a Collector.
sequenceDiagram
participant U as Customer Browser
participant S as Shopping Service with Agent
participant D as Database
participant P as Pricing Service with Agent
participant C as Collector
U->>S: HTTP request
Note over S: Agent starts server span
S->>D: Query
Note over S: Agent records client span for query
D-->>S: Rows
S->>P: HTTP call with trace headers
Note over S: Agent records client span and injects context
Note over P: Agent extracts context, starts child server span
P-->>S: Price
S-->>U: HTTP response
Note over S: Agent ends server span
S->>C: Export spans in background
P->>C: Export spans in background
What the engineer sees
A single trace with a clear tree
At the top is the incoming request span. Beneath it are the database query and the call to the pricing service, with the pricing service’s own spans nested below.
Timing that points to the slow part
The durations show that the database query took a short time, while the pricing call took most of the total time.
Consistent labels across services
Because both agents use the same conventions, the engineer can filter by service name, route, or status code, even though the services may be written in different languages.
No code was written
All of this came from the agents and their configuration, which means the developers kept working on features rather than on plumbing.
Notice that the connection between services works only because both services propagate context in the same format. Agents in different languages share the same default standard, which is why they usually link up without extra work.
12Performance and Overhead
Adding an observer always costs something. The question is how much, and how to keep it reasonable.
Where the cost comes from
Startup time
The agent has to load, read configuration, and prepare its hooks. Large agents that cover many libraries can lengthen the time an application takes to start.
Memory use
The agent and its SDK occupy memory, and finished spans wait in buffers until exported. More traffic means larger buffers.
CPU time per operation
Creating spans, recording details, and exporting take a little processing time on every observed operation.
Network traffic
Exported telemetry travels over the network. Heavy tracing of high-volume services can produce a lot of data.
Ways to control the overhead
Sampling is the most effective tool. By keeping only a fraction of traces, you reduce the number of spans created, stored, and exported. Turning off instrumentation for libraries you do not need also helps, because every enabled instrumentation adds some cost. Batching, which groups data before sending, lowers the per-item network cost. Finally, sending to a nearby Collector rather than a distant backend reduces delays and lets the Collector do heavy processing instead of your application.
| Technique | What it reduces | Trade-off |
|---|---|---|
| Sampling a fraction of traces | CPU, memory, network, storage | You see fewer examples of rare events |
| Disabling unused instrumentations | Startup time, CPU | Less coverage for those libraries |
| Batching exports | Network calls and CPU | Slight delay before data appears |
| Exporting to a local Collector | Latency and retry load on the app | One more component to run |
| Limiting recorded detail | Memory and data volume | Less detail per span |
Overhead depends on your application, traffic, and configuration. Measure startup time, memory, and latency with and without the agent in a realistic test environment before rolling out widely, instead of relying on general claims.
Wearing a fitness tracker costs a little battery and adds a little weight. For most people the benefit is worth it, but a marathon runner might choose a lighter model. The right choice depends on how much you value the data and how much you can spare.
13Data Governance, Privacy, and Security
An agent sees a great deal, and what it sees might be sensitive. Responsible use means deciding what to keep and what to hide.
What agents can capture
By design, agents record details about requests and calls. Depending on configuration, this can include web addresses with query parameters, header values, database statements, and message contents. Some of that information may contain personal data, access tokens, or business secrets.
Sensible defaults and safeguards
Well-designed agents avoid capturing risky details by default. For example, database statements may be recorded with literal values replaced by placeholders, and request headers are usually not recorded unless you ask for them. Even so, you should review what your agent records and adjust the configuration to match your privacy rules.
Sensitive web addresses
Web addresses may contain identifiers or tokens in the path or query. Configure the agent or the Collector to remove or mask them.
Query text
Database statements can reveal table names and, if not cleaned, real values. Prefer sanitized statements.
Captured headers and bodies
Enable capture only for specific, safe headers. Avoid capturing bodies unless you have a strong need and controls in place.
Agent privileges
An agent runs with the permissions of the application. Treat the agent file itself as trusted software, and obtain it only from official sources.
Use two layers: limit what the agent captures at the source, and use Collector processors to filter or redact attributes before data reaches storage. If one layer is misconfigured, the other can catch the mistake.
A security camera should point at the entrance, not into the changing rooms. You decide where it looks, what it records, and who can watch the footage, before switching it on.
14Strengths and Limits of Instrumentation Agents
Understanding what an agent cannot do is as valuable as knowing what it can.
Advantages
- Fast results, often within minutes of starting
- No source code changes needed in most cases
- Covers third-party libraries you cannot edit
- Consistent naming through standard conventions
- Automatic context propagation between services
- Uses open standards, so you can change backends later
Disadvantages / Trade-offs
- Sees technical events, not business meaning
- Coverage limited to supported libraries and versions
- Adds startup time, memory, and CPU overhead
- Less fine-grained control than hand-written instrumentation
- May conflict with other agents that modify the same code
- Upgrades can change span names or attributes
Situations where an agent may not be the best fit
Extremely latency-sensitive code paths
For code where every microsecond matters, even small overhead is unacceptable. Selective manual instrumentation, or sampling aggressively, may be a better choice.
Unsupported languages or frameworks
If no agent supports your language or framework, you may need to use the SDK directly or contribute instrumentation. Check support before committing to a plan.
Environments with strict startup controls
Some locked-down platforms, such as certain serverless or managed runtimes, restrict attaching agents or changing startup commands. Vendor-provided layers or built-in integrations may be required.
Running two agents that both rewrite the same libraries, for example an OpenTelemetry agent along with a vendor agent, can cause duplicate spans, conflicts, or even crashes. Choose one primary approach, or follow documented guidance for coexistence.
15Troubleshooting, Best Practices, and Anti-patterns
A short field guide for when the data does not look the way you expect.
Troubleshooting guide
| Symptom | Likely cause | What to check |
|---|---|---|
| No telemetry appears at all | Agent not loaded, or exporter destination wrong | Startup command or injection, endpoint address, network access |
| Service appears with an unknown name | Service name not set | Service name setting and resource attributes |
| Traces broken between services | Context not propagated, or different formats | Propagator settings and proxies that strip headers |
| Some libraries produce no spans | Library or version not supported, or instrumentation disabled | Supported list and per-library switches |
| Duplicate spans for one operation | Two agents or overlapping instrumentations | Remove the extra agent or disable overlapping instrumentation |
| Application slower or heavier after enabling | Too much coverage or full sampling | Sampling rate, disabled instrumentations, batch settings |
| Sensitive data visible in traces | Capture settings too broad | Header capture, statement sanitizing, Collector redaction |
Habits that work
Always name the service
Set an explicit service name and useful resource attributes such as version and environment before anything else.
Send to a Collector
Export to a nearby Collector instead of directly to a backend, so you can change routing, filtering, and retries without touching applications.
Pin and test versions
Choose a specific agent version, test it in staging, and upgrade deliberately, since span names and attributes can change between versions.
Sample with intent
Pick a sampling strategy that balances cost and visibility, and revisit it as traffic grows.
Add manual spans for business steps
Complement the agent with a small number of well-named manual spans around important business operations.
Review captured data
Inspect real traces for sensitive details and tune capture and redaction settings before wide rollout.
Traps to avoid
Problem
The agent is rolled out to every service at once, with full sampling and default settings, without testing.
Why It’s Harmful
Unexpected overhead, large data volumes, and surprising captured data can appear simultaneously across the whole fleet, making problems hard to isolate.
Correct Approach
Roll out gradually, starting with a few services, measure the effects, and then expand with tuned settings.
Problem
Several monitoring agents are attached to the same application, each trying to instrument the same libraries.
Why It’s Harmful
They may conflict, duplicate data, increase overhead, or destabilize the application.
Correct Approach
Standardize on one agent per application, or follow explicit compatibility guidance when migrating between tools.
Problem
Teams assume the agent captures everything that matters and never add business-level spans or attributes.
Why It’s Harmful
Traces show technical steps but not business meaning, so engineers still struggle to answer questions such as which customer segment is affected.
Correct Approach
Use the agent as the foundation and add selective manual instrumentation for key business operations and attributes.
Problem
The agent is upgraded automatically to the newest version whenever one appears, with no testing.
Why It’s Harmful
Changes in span names, attributes, or behavior can break dashboards, alerts, and saved queries, or introduce regressions in the application.
Correct Approach
Pin versions, read release notes, test in a staging environment, and upgrade on a planned schedule.
16Frequently Asked Questions
Quick answers to the questions people ask most often.
No. The agent runs with your application and creates telemetry from its activity. The Collector is a separate program that receives, processes, and forwards telemetry. They are usually used together.
In most cases, no. You attach the agent at startup or through injection and provide configuration. You may still choose to add a little manual instrumentation for business-specific information.
Several major languages have automatic instrumentation options, but the approach, maturity, and coverage differ between them. Some compiled languages rely on different techniques. Check the current documentation for your language.
Yes, and this is often the best approach. Both use the same API and SDK, so manual spans become part of the same traces as the automatic ones.
It adds some overhead, mainly at startup and per operation. The amount depends on your application and settings. Use sampling, disable unneeded instrumentation, and measure in a test environment.
You should tell it, using the standard service name setting. If you do not, the agent may use a default or guessed name, which is usually not helpful.
Most agents allow individual instrumentations to be disabled through configuration. This reduces noise and overhead, and avoids conflicts with other tools.
It can, but sending to a Collector first is the more common and flexible pattern. The Collector can then filter, enrich, batch, and route the data to one or more backends.
Many organizations do so, but you should test first. Check performance, review captured data for sensitivity, pin versions, and roll out gradually. Treat the agent as part of your trusted software supply chain.
You can add manual instrumentation around the relevant calls using the OpenTelemetry API, or look for a community instrumentation library. You may also request or contribute support in the project.
17Summary and Key Takeaways
An instrumentation agent is the quickest route from a silent application to a well-observed one. It attaches to your application without changing its source code, wraps supported libraries with telemetry steps, creates spans and metrics using shared conventions, passes trace context between services, and exports everything using open standards. Each language achieves this with a different technique, but the result feels the same: traces appear within minutes. The agent sees technical events, not business meaning, so the strongest setups combine it with a few well-chosen manual spans, a nearby Collector, thoughtful sampling, and careful handling of sensitive data. Used with measurement and care, it removes the biggest barrier to observability: the effort of getting started.
Key Takeaways
- An agent adds telemetry from outside your code — it attaches at startup or through injection and instruments supported libraries automatically.
- It is not the Collector — the agent creates telemetry inside the application, while the Collector receives, processes, and forwards it.
- Each language uses its own trick — Java modifies loaded classes, Python and Node.js wrap modules, .NET uses runtime hooks, and compiled languages may rely on other approaches.
- Configuration comes from the outside — standard environment variables set the service name, exporter, sampling, and propagation without code changes.
- Hybrid beats either extreme — use the agent for broad coverage and add manual spans for business meaning.
- Mind overhead and privacy — measure startup, memory, and latency, use sampling, and review captured data and redaction before wide rollout.
- Roll out deliberately — pin versions, avoid stacking multiple agents, test in staging, and expand gradually.