3.1 OneAgent Architecture, Components & Automatic Injection

OneAgent Architecture, Components & Automatic Injection

Exam Focus: Understanding the internal process model of Dynatrace OneAgent, the mechanics of dynamic library hooking via the operating system dynamic linker, and the exact boundary between immediate host discovery and capabilities that require an application restart is essential for the Dynatrace Certified Associate exam.

In traditional Application Performance Monitoring (APM) tools, monitoring a multi-tier enterprise stack required deploying separate, disjointed agents: one agent for host infrastructure metrics, a distinct profiler for the Java Virtual Machine (JVM), a separate plugin for web server metrics, an operating system daemon for log collection, and a network sniffing tap. This multi-agent sprawl introduced significant maintenance overhead, version compatibility matrix nightmares, and unpredictable resource footprints.

Dynatrace eliminates this complexity through OneAgent: a single, unified agent binary installed per host or container node. Once deployed, OneAgent automatically discovers the host environment, analyzes network topology, discovers running process groups, and injects deep monitoring sensors into supported application runtimes without requiring code changes, proprietary SDK modifications, or manual binary recompilation.

---

OneAgent Process Architecture and Subsystem Modules

While OneAgent is packaged and installed as a unified binary, it executes internally as a coordinated collection of modular sub-processes and runtime sensors. This separation ensures operational resilience: if a specific language sensor encounters an unhandled edge case, the host-level operating system monitoring remains fully operational.

The Watchdog Daemon (oneagentwatchdog)

The OneAgent watchdog is the master supervisory daemon running as an operating system service. It acts as the guardian of host system stability. The watchdog performs three critical functions:

1. Lifecycle Management: It spawns, stops, and updates the child monitoring daemons (oneagentos, oneagentnet, plugin engines).
2. Self-Protection and Resource Throttling: It continuously measures the CPU and memory consumption of all OneAgent components. If an agent component exceeds predefined resource thresholds, the watchdog throttles or temporarily suspends monitoring to prevent impacting host workloads.
3. Automatic Crash Recovery: If a sub-process terminates unexpectedly due to a system crash or out-of-memory event, the watchdog logs the failure diagnostic data and automatically restarts the affected module.

---

Linux Automatic Injection Mechanics: Dynamic Linker & ld.so.preload

One of the most foundational capabilities tested on the Dynatrace Certified Associate exam is Automatic Injection—how OneAgent injects deep monitoring sensors into running processes without touching source code.

On Linux systems, OneAgent utilizes the native dynamic linker mechanism (ld-linux.so). During installation, OneAgent registers its bootstrap loader library in the system-wide preloading configuration file:

/etc/ld.so.preload

Inside /etc/ld.so.preload, OneAgent appends the path to its process agent bootstrap library, typically:

/opt/dynatrace/oneagent/agent/lib64/liboneagentproc.so

The Step-by-Step Linux Injection Sequence

1. Kernel Syscall      ==> Executable invoked via execve()
2. Dynamic Linker Load ==> ld-linux.so reads /etc/ld.so.preload before application libraries
3. Bootstrap Hook      ==> liboneagentproc.so loads into the new process address space
4. Technology Check    ==> Inspects ELF header, process arguments, and environment variables
5. Runtime Match       ==> Identifies supported runtime (e.g., /usr/bin/java or /usr/bin/node)
6. Sensor Mapping      ==> Loads language-specific module (e.g., liboneagentjava.so)
7. Bytecode Hook       ==> Injects runtime bytecode instrumentation (BCI) into classloader

When any new process is launched via the execve() system call, the Linux dynamic linker inspects /etc/ld.so.preload before loading the application's own shared objects (libc, etc.). The linker preloads liboneagentproc.so directly into the process memory address space.

At this stage, the OneAgent bootstrap library performs a rapid, lightweight signature inspection of the process:

• It examines the executable binary's ELF headers and symbol tables.
• It checks the command-line arguments and process environment variables.
• If the process is a standard shell utility (such as ls, grep, or cat), the bootstrap library unhooks immediately and unloads with negligible overhead (sub-millisecond).
• If the process matches a supported application runtime (such as Java, Node.js, .NET Core, Python, or Go), the bootstrap loader maps the appropriate technology code module (for example, liboneagentjava.so) into the process address space.

Once loaded into the runtime process, the code module uses Dynamic Bytecode Instrumentation (BCI). For Java Virtual Machines, it hooks into the Java Virtual Machine Tool Interface (JVMTI) and modifies class bytecode dynamically at class-loading time. For .NET, it attaches via the CLR Profiling API. This allows Dynatrace to intercept method entries and exits, capture method arguments and exceptions, time database queries, and propagate PurePath trace context across thread boundaries and network hops.

---

Windows Injection Architecture: AppInit_DLLs, Detours & Profiling APIs

On Microsoft Windows operating systems, OneAgent achieves transparent injection through a combination of native Windows subsystem mechanisms:

1. User-Mode API Hooking (Dynatrace Detours Engine): OneAgent utilizes an advanced memory-hooking framework to intercept native Win32/NT system APIs. When new processes launch, OneAgent inspects their PE (Portable Executable) headers and determines whether monitoring hooks should be established.
2. .NET CLR Profiling Interface: For .NET Framework and .NET Core / .NET 5+ applications, OneAgent leverages Microsoft's native CLR Profiling APIs. When an instrumented .NET process boots, environment variables tell the Common Language Runtime to load the Dynatrace profiler COM object into memory:
   • COR_ENABLE_PROFILING=1 and COR_PROFILER={GUID} (for .NET Framework)
   • CORECLR_ENABLE_PROFILING=1 and CORECLR_PROFILER={GUID} (for .NET Core)
3. Internet Information Services (IIS) Module Injection: For Microsoft IIS web servers, OneAgent installs a native C++ HTTP module into the IIS core pipeline via applicationHost.config. This module intercepts every incoming HTTP request, measures request durations, captures HTTP response status codes, correlates incoming requests with backend database transactions, and automatically injects the Real User Monitoring (RUM) JavaScript tag before closing the HTML <head> tag.

---

Container Runtime Discovery and Namespace Traversal

When deployed on a containerized host running Docker, containerd, or CRI-O, OneAgent does not require container images to be rebuilt or altered. The host-level OneAgent monitors containers from the underlying operating system by traversing Linux kernel namespaces:

• PID Namespace Traversal: OneAgent accesses the host PID namespace, allowing it to view every process executing inside every container running on the node.
• Mount Namespace Injection: OneAgent discovers running container runtimes by communicating with local runtime control sockets (e.g., /var/run/containerd/containerd.sock or /var/run/docker.sock). When a container launches, OneAgent maps its instrumentation libraries directly into the container's mount namespace (mnt), making the agent libraries accessible inside the container filesystem.
• Network Namespace Inspection: The network module attaches to the container's virtual ethernet interfaces (veth) and network namespace (net) to measure round-trip times, bandwidth consumption, and TCP connection metrics per container.

---

Immediate Discovery vs. Process Restart Requirements

A critical, heavily tested distinction on the certification exam is understanding what data Dynatrace discovers immediately upon OneAgent installation versus what capabilities strictly require an application process restart.

The Golden Rule of OneAgent Injection

• Host Infrastructure & OS Metrics = No Restart Required: The OS monitoring daemon (oneagentos) and network daemon (oneagentnet) begin inspecting system states, cgroups, network interfaces, and process tables immediately upon service startup.
• Deep Code-Level Monitoring & PurePaths = Application Restart Mandatory: Because dynamic preloading (/etc/ld.so.preload) and bytecode instrumentation occur when a process initializes its runtime and classloaders, already-running application processes must be restarted for OneAgent to inject its sensors into memory.

Handling Agent Updates and Restarts

When OneAgent automatic updates are enabled, the host OS agent and watchdog update immediately in the background without rebooting the host operating system. However, the deep code modules running inside target application memory spaces continue running the previous agent version until those application processes are restarted. Upon the next scheduled maintenance window or rolling restart, the newly updated code modules are injected automatically.