传统 VM 下零代码OpenTelemetry可观测方案

>在微服务架构中，可观测性就像给应用装上“眼睛”和“耳朵”。传统方式需要在每个服务中手动集成监控代码，而 **OpenTelemetry Injector** 提供了一种更优雅的解决方案。

## 项目简介

**OpenTelemetry Injector** 是一个专为 **传统 VM 环境** 设计的零代码观测工具。

通过 Linux 的 `LD_PRELOAD` 机制，无需修改应用代码，即可为 Java、Node.js、.NET 应用自动注入 OpenTelemetry 观测能力。

### 核心优势

* 系统级自动化
* 多语言统一管理
* 生产环境就绪

> ⚠️注意: 不适合容器 / K8s 环境。
> 云原生场景建议使用 OpenTelemetry Operator、init-container、sidecar 等方案。

对于企业数据中心中的传统部署、混合技术栈微服务架构或遗留系统升级，OpenTelemetry Injector 提供了一条高效路径。

---

## 零代码检测必要性

在维护包含数百个微服务的系统，技术栈混合（Java、Node.js、.NET）。现在需要统一增加可观测能力时侵入式代码检测会捉襟见肘。

* 需要修改每个服务的代码
* 不同语言集成方式不同
* 升级时需要重复修改
* 功能不一致
* 增加出错风险
* 提高维护成本

这正是 OpenTelemetry Injector 的价值所在。

---

## 核心价值

OpenTelemetry Injector 允许在 **不修改任何应用代码** 的情况下，为 Java、Node.js、.NET 自动注入 OpenTelemetry 代理。

* Kubernetes 场景可使用 OpenTelemetry Operator
* 也可以通过 sidecar / init-container 方式实现自动注入

## 核心特性

* **零侵入性**：无需修改源码
* **多语言支持**：Java / Node.js / .NET
* **开箱即用**：支持 Debian / RPM
* **生产就绪**
* **灵活配置**

---

## 实现方式对比

| 特性    | OpenTelemetry Injector | OpenTelemetry Operator |
| ----- | ---------------------- | ---------------------- |
| 部署环境  | 任意 Linux 系统            | Kubernetes 集群          |
| 触发机制  | 系统级 `LD_PRELOAD`       | Pod 注解                 |
| 配置方式  | 配置文件 + 环境变量            | CRD + 注解               |
| 适用场景  | 传统部署 / 虚拟机             | 云原生 / 容器               |
| 管理复杂度 | 较低                     | 需要 K8s 知识              |

---

# 快速开始

## 环境准备

* Linux（推荐 Ubuntu 20.04+）
* Java 8+
* Docker（可选）

---

## 编译安装 Injector

```bash
git clone https://github.com/open-telemetry/opentelemetry-injector.git
cd opentelemetry-injector
make deb-package VERSION=0.0.1
```

生成 Debian 包：

```
instrumentation/dist/opentelemetry-injector_0.0.1_amd64.deb
```

安装：

```bash
sudo dpkg -i instrumentation/dist/opentelemetry-injector_0.0.1_amd64.deb
```

---

安装后文件结构

* `/usr/lib/opentelemetry/libotelinject.so`
* `/etc/opentelemetry/otelinject/{java,node,dotnet}.conf`
* `/usr/lib/opentelemetry`
* `/usr/lib/opentelemetry/examples/systemd/00-opentelemetry-injector.conf`

## 包文件安装 Injector

从最新页下载适配系统和架构的`opentelemetry-injector-0.1.0-1.xx.xx`安装包文件, 并进行安装
```
https://github.com/open-telemetry/opentelemetry-injector/releases
```

---
安装成功示例(无外部依赖,适用于任何由rpm或者deb管理的linux发行版)

![](/media/202602/2026-02-26_095143_4861510.6533168005310758.png)

## 激活 Injector

```bash
sudo sh -c 'echo /usr/lib/opentelemetry/libotelinject.so >> /etc/ld.so.preload'
```

全局注入后,如遇cat或ldd等常用命令执行时出现如下错误
```
# 命令可能涉及ELF 可执行文件或采用静态链接
# 会主动放弃注入 → 输出错误日志
# [otel-injector] [ 107374] failed to identify libc: error.CannotFindLibcMemoryRange
```

可忽略错误

```
# export OTEL_INJECTOR_LOG_LEVEL=error
export OTEL_INJECTOR_LOG_LEVEL=none
```

---

# 验证效果(Java)

## 配置环境变量

```bash
sudo sh -c 'cat >> /etc/opentelemetry/otelinject/java.conf <<EOF
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc
OTEL_LOGS_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_RESOURCE_ATTRIBUTES=service.version=1.0.0,deployment.environment=development
OTEL_SERVICE_NAME=my-java-service
EOF'
```

---

## 示例 Java 程序

```java
import java.util.Map;

public class Main {
    public static void main(String[] args) {
        Map<String, String> env = System.getenv();
        for (String envName : env.keySet()) {
            System.out.format("%s=%s%n", envName, env.get(envName));
        }
    }
}
```

---

## 编译运行

```bash
javac Main.java
jar cfe Main.jar Main Main.class
java -jar Main.jar | grep -i OTEL
```

如果输出中包含：

* `JAVA_TOOL_OPTIONS`
* `OTEL_EXPORTER_OTLP_ENDPOINT`
* `OTEL_SERVICE_NAME`
* `otel.javaagent - version:`

说明注入成功。

---

# 技术实现原理

## 核心机制：`LD_PRELOAD`

Linux 动态链接器允许通过 `LD_PRELOAD` 预加载共享库。

Injector 利用该机制：

1. 进程启动
2. 动态链接器加载 `libotelinject.so`
3. 执行构造函数
4. 读取配置文件
5. 设置环境变量
6. 语言运行时加载 OpenTelemetry Agent

---

## 核心代码（简化）

```c
void __attribute__((constructor)) enter() {
    char *env_var_file;

if (strcmp("java", program_invocation_short_name) == 0) {
        env_var_file = "/etc/opentelemetry/otelinject/java.conf";
    } else {
        return;
    }

FILE *fp = fopen(env_var_file, "r");
    if (!fp) return;

char buffer[1024];

while (fgets(buffer, sizeof(buffer), fp)) {
        if (buffer[0] == '#') continue;

char *equals = strchr(buffer, '=');
        if (!equals) continue;

*equals = '\0';
        char *key = buffer;
        char *value = equals + 1;

char *newline = strchr(value, '\n');
        if (newline) *newline = '\0';

setenv(key, value, 0);
    }

fclose(fp);
}
```

---

# 配置文件示例

## Java

```
JAVA_TOOL_OPTIONS=-javaagent:/usr/lib/opentelemetry/javaagent.jar
```

## Node.js

```
NODE_OPTIONS=-r /usr/lib/opentelemetry/otel-js/node_modules/@opentelemetry-js/otel/instrument
```

## .NET

```
CORECLR_ENABLE_PROFILING=1
CORECLR_PROFILER={918728DD-259F-4A6A-AC2B-B85E1B658318}
CORECLR_PROFILER_PATH=/usr/lib/opentelemetry/dotnet/linux-x64/OpenTelemetry.AutoInstrumentation.Native.so
DOTNET_ADDITIONAL_DEPS=/usr/lib/opentelemetry/dotnet/AdditionalDeps
DOTNET_SHARED_STORE=/usr/lib/opentelemetry/dotnet/store
DOTNET_STARTUP_HOOKS=/usr/lib/opentelemetry/dotnet/net/OpenTelemetry.AutoInstrumentation.StartupHook.dll
OTEL_DOTNET_AUTO_HOME=/usr/lib/opentelemetry/dotnet
```

---

# 安全设计

Injector 采用多层保护机制：

* 环境变量白名单
* 输入验证
* 程序名精确匹配
* 固定配置路径

---

# 总结

## 核心定位

专为 **传统 VM 环境** 设计
基于 `LD_PRELOAD` 的系统级自动注入

## 核心价值

* 零代码集成
* 系统级自动化
* 多语言统一
* 生产环境可用

## 适用场景

* 企业数据中心
* 传统部署
* 混合技术栈
* 遗留系统升级

> ⚠ 容器 / Kubernetes 场景请使用 OpenTelemetry Operator。

---

# 参考资料

* [https://github.com/open-telemetry/opentelemetry-injector](https://github.com/open-telemetry/opentelemetry-injector)
* [https://opentelemetry.io/docs/kubernetes/operator/](https://opentelemetry.io/docs/kubernetes/operator/)
* [https://opentelemetry.io/docs/zero-code/java/agent/configuration/](https://opentelemetry.io/docs/zero-code/java/agent/configuration/)
* [https://opentelemetry.io/docs/zero-code/js/configuration/](https://opentelemetry.io/docs/zero-code/js/configuration/)
* [https://opentelemetry.io/docs/zero-code/dotnet/configuration/](https://opentelemetry.io/docs/zero-code/dotnet/configuration/)