open-telemetry/opentelemetry-ebpf-instrumentation

# OpenTelemetry eBPF Instrumentation 本仓库提供了基于 OpenTelemetry 标准的 eBPF instrumentation。 它提供了一种轻量且高效的方式，使用 eBPF 为用户空间应用程序收集遥测数据。 **O**penTelemetry e-**B**PF **I**nstrumentation 通常简称为 OBI。 ## 项目状态 OBI 目前处于开发阶段。在项目处于 `v0` 阶段时，用户应预料到次要版本之间可能会出现破坏性变更。 如果您正在评估 OBI 以用于生产环境： - 请固定使用特定的 semver 发布标签，而不是依赖 `latest`，因为后者是一个不断变动且不稳定的标签 - 在次要版本之间升级之前，请查阅发布说明 - 预料在 `v0` 的次要版本之间，配置、行为、支持的环境以及发出的遥测数据可能会发生变化 - 在 OBI 宣布这些层面稳定之前，避免假定仪表盘、警报或下游处理器的遥测连续性 有关项目的版本控制与稳定性策略，请参见 [VERSIONING.md](./VERSIONING.md)。 有关 OBI 目前文档记录为受支持的环境和构件平台，请参见 [SUPPORT_MATRIX.md](./SUPPORT_MATRIX.md)。 ## 如何开始开发 前提条件： * Docker * GNU Make 1. 首先，通过 `make docker-generate` 生成所有 eBPF Go bindings。每次在 [`bpf/`](./bpf) 文件夹下添加或修改 C 文件时，您都需要重新运行此 make 任务。 2. 要运行代码检查器和单元测试：`make fmt verify`。 3. 要运行集成测试，请运行以下任一命令： ``` make integration-test make integration-test-k8s make oats-test ``` ，或者运行上述所有任务。每个集成测试目标最多可能需要 50 分钟才能完成，但您可以 使用标准的 `go` 命令行工具，在 [internal/test/integration](./internal/test/integration) 和 [internal/test/integration/k8s](./internal/test/integration/k8s) 文件夹下单独运行每个集成测试套件。 ## 零代码 Instrumentation 以下是使用二进制文件下载或容器镜像快速启动并运行 OBI 的参考说明。有关全面的设置、配置和故障排除指南，请参阅 [OpenTelemetry 零代码 instrumentation 文档](https://opentelemetry.io/docs/zero-code/)，这是权威的可靠信息源。 有关发布构件的验证和安装详细信息，请参见： - [将 OBI 作为独立进程运行](https://opentelemetry.io/docs/zero-code/obi/setup/standalone/) - [将 OBI 作为 Docker 容器运行](https://opentelemetry.io/docs/zero-code/obi/setup/docker/) ## 安装说明 ### 二进制文件下载 OBI 为 Linux（amd64 和 arm64）提供了预编译的二进制文件。请从 [发布页面](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases) 下载最新版本。 每个版本包含： - `obi-v-linux-amd64.tar.gz` - Linux AMD64/x86_64 归档文件 - `obi-v-linux-arm64.tar.gz` - Linux ARM64 归档文件 - `obi-v-linux-amd64.cyclonedx.json` - AMD64 归档文件的 CycloneDX SBOM - `obi-v-linux-arm64.cyclonedx.json` - ARM64 归档文件的 CycloneDX SBOM - `obi-v-source-generated.cyclonedx.json` - 源码生成归档文件的 CycloneDX SBOM - `obi-java-agent-v.cyclonedx.json` - 内置 Java agent 及其 Java 依赖项的 CycloneDX SBOM - `SHA256SUMS` - 用于验证发布归档文件和 SBOM 资产的校验和 #### 下载并验证 ``` # 设置所需的版本（在 https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases 查找最新版本） export VERSION=1.0.0 # 确定您的架构 # 对于 Intel/AMD 64 位：amd64 # 对于 ARM 64 位：arm64 export ARCH=amd64 # Change to arm64 for ARM systems ``` 下载归档文件和校验和清单： ``` # 下载适用于您架构的压缩包 wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/obi-v${VERSION}-linux-${ARCH}.tar.gz # 下载校验和 wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/SHA256SUMS ``` 验证下载的发布资产： ``` # 验证您下载的压缩包 sha256sum -c SHA256SUMS --ignore-missing ``` 成功验证后，会为您下载的每个文件打印一个 `OK` 结果： ``` obi-v${VERSION}-linux-${ARCH}.tar.gz: OK ``` 如果验证失败，`sha256sum` 将报告 `FAILED`。请重新下载 受影响的文件，并在继续操作前确保您验证的是来自同一发布 版本的资产。 解压归档文件： ``` tar -xzf obi-v${VERSION}-linux-${ARCH}.tar.gz # 该压缩包包含： # - obi：主 OBI 二进制文件 # - k8s-cache：Kubernetes 缓存二进制文件 # - LICENSE：项目许可证 # - NOTICE：法律声明 # - NOTICES/：第三方许可证和归属 ``` #### 可选：下载并检查 SBOM CycloneDX SBOM 文件是用于供应链审查和自动化的可选元数据。 安装或运行 OBI 并不强制要求这些文件。 发布 SBOM 以 [CycloneDX JSON 格式](https://cyclonedx.org/) 描述了已发布归档文件的内容及内置 组件。它们可以被依赖项分析和漏洞扫描工具直接使用，而无需 解压或执行二进制文件。 下载您想检查的 SBOM： ``` # 您下载的二进制包的 SBOM wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/obi-v${VERSION}-linux-${ARCH}.cyclonedx.json # 嵌入式 Java agent 及其 Java 依赖项的 SBOM wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/obi-java-agent-v${VERSION}.cyclonedx.json # 可选：也根据 SHA256SUMS 验证下载的 SBOM 文件 sha256sum -c SHA256SUMS --ignore-missing ``` 使用常用工具检查 SBOM 内容： ``` # 列出压缩包 SBOM 中的组件名称和版本 jq '.components[] | {name, version}' obi-v${VERSION}-linux-${ARCH}.cyclonedx.json # 使用 Grype 扫描 SBOM grype sbom:obi-v${VERSION}-linux-${ARCH}.cyclonedx.json # 检查 Java agent 依赖图 jq '.components[] | {name, version}' obi-java-agent-v${VERSION}.cyclonedx.json ``` #### 安装到系统 解压归档文件后，您可以将二进制文件安装到您的 PATH 中的某个位置，以便在任何目录下使用它们。 Java agent 已嵌入在 `obi` 二进制文件中，因此不需要单独安装 Java agent JAR。 在运行时，OBI 会将内置的 Java agent 解压到用户缓存目录（通常是 `$XDG_CACHE_HOME/obi/java` 或 `~/.cache/obi/java`）中，并在多次运行之间复用以校验和命名的缓存文件。 以下示例将文件安装到 `/usr/local/bin`，这是大多数 Linux 发行版中的标准位置。您也可以安装到 PATH 中的任何其他目录： ``` # 将二进制文件移动到您 PATH 中的目录 sudo cp obi /usr/local/bin/ sudo cp k8s-cache /usr/local/bin/ # 验证安装 obi --version ``` ### 容器镜像 OBI 也以容器镜像的形式提供： ``` # 设置所需的版本。 export VERSION=v0.7.0 # （可选）验证容器镜像的签名 cosign verify --certificate-identity-regexp 'https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/' --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' otel/ebpf-instrument:${VERSION} # （可选）从 GHCR 验证同一版本 cosign verify --certificate-identity-regexp 'https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/' --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' ghcr.io/open-telemetry/opentelemetry-ebpf-instrumentation/ebpf-instrument:${VERSION} # 拉取镜像 docker pull otel/ebpf-instrument:${VERSION} # 或者从 GHCR 拉取相同的镜像 docker pull ghcr.io/open-telemetry/opentelemetry-ebpf-instrumentation/ebpf-instrument:${VERSION} # 在容器中运行 OBI # 注意：OBI 需要提升的权限 (--privileged) 来 instrument 进程 # 详见 https://opentelemetry.io/docs/zero-code/obi/setup/docker/ docker run --privileged otel/ebpf-instrument:${VERSION} ``` 成功的 `cosign verify` 输出会声明声明已被验证，并返回已签名的镜像摘要。如果验证失败，请确认您查询的仓库中存在该镜像标签，并且您正在使用上述所示的 GitHub OIDC 签发者和身份正则表达式。 ## 示例 - [OTel Collector Receiver 示例](./examples/otel-collector/README.md) - [NGINX 多路由与代理示例](./examples/nginx/README.md) ## 贡献指南 参见 [CONTRIBUTING](CONTRIBUTING.md) ## 许可证 OpenTelemetry eBPF Instrumentation 根据 Apache 软件许可证 2.0 版的条款获得许可。 有关更多详细信息，请参见 [许可证文件](./LICENSE)。

标签：API集成, DNS解析, Docker, Docker镜像, GET参数, Go语言, OBI, OpenTelemetry, 内核技术, 分布式追踪, 可观测性, 子域名突变, 安全防御评估, 客户端加密, 开源项目, 性能分析, 性能监控, 指标收集, 无侵入监控, 日志审计, 用户代理, 用户空间监控, 程序破解, 请求拦截, 遥测数据, 零代码插桩