Back to Details

opentelemetry-auto-instrumentation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Instrumenting Applications Using OpenTelemetry

使用OpenTelemetry为应用程序插桩

Principles

原则

  • Zero-code auto-instrumentation and code-based auto-instrumentation are the go-to options. Both approaches capture HTTP, database, and framework-internal spans automatically without modifying application code and may be used interchangeably depending on the use case, language, and frameworks involved.
  • A combination of framework-native OTel and the auto-instrumentation meta-package/agent is acceptable when they complement each other, but verify they don't produce duplicate spans for the same request.
  • Manual instrumentation should never be used. Do not add 
    tracer.startSpan()
    calls or similar manual instrumentation to the application.
  • When a framework provides its own OTel integration, prefer it over the external agent unless the language section says otherwise.
  • Always use latest versions of auto-instrumentation libraries for the most stable experience.
  • 无代码自动插桩和基于代码的自动插桩是首选方案。这两种方式都无需修改应用代码即可自动捕获HTTP、数据库和框架内部的spans，可根据具体用例、语言及涉及的框架灵活切换使用。
  • 当框架原生OTel集成与自动插桩元包/代理能够互补时，可结合使用，但需验证它们不会为同一请求生成重复的spans。
  • 绝不使用手动插桩。请勿在应用中添加
    tracer.startSpan()
    调用或类似的手动插桩代码。
  • 当框架提供自身的OTel集成时，优先使用该集成，除非对应语言章节另有说明。
  • 始终使用最新版本的自动插桩库，以获得最稳定的使用体验。

Workflow

工作流程

1. Clarify the service name

1. 明确服务名称

Ask the developer what they want to call the service (
service.name
). Suggest names based on the repository, directory, or module name.
询问开发者他们想要为服务命名的名称（
service.name
）。可根据仓库、目录或模块名称给出命名建议。

2. Discover the application

2. 发现应用信息

Run the discovery reference to scan the target directory. If the repository contains multiple runnable services, present the candidate list and ask the developer to choose the target app or directory before continuing.
Discovery produces: runtime, language, framework, package manager, lockfiles, test framework, container and deployment hints, existing OpenTelemetry setup, and any non-OTel vendor instrumentation.
运行发现参考文档来扫描目标目录。如果仓库包含多个可运行服务，先列出候选列表并请开发者选择目标应用或目录，再继续后续操作。
发现过程会生成以下信息：运行时环境、语言、框架、包管理器、锁定文件、测试框架、容器与部署提示、已有的OpenTelemetry配置，以及任何非OTel厂商的插桩方案。

3. Identify target platform

3. 确定目标平台

Ask the developer to pick one of the following target platforms where the application will be deployed:
  • VM / bare metal hosts
  • Kubernetes
请开发者选择应用将要部署的目标平台之一：
  • 虚拟机/裸金属主机
  • Kubernetes

4. Check the Observe APM support matrix

4. 查看Observe APM支持矩阵

Visit the corresponding APM support matrix documentation and check for product feature compatibility (Trace Explorer, Service Catalog, Service Maps, etc.):
访问对应的APM支持矩阵文档，检查产品功能兼容性（Trace Explorer、服务目录、服务地图等）：

5. Check for service name conflicts

5. 检查服务名称冲突

Run the conflict-check reference to query Observe for an existing service with the requested 
service.name
. If a collision is found, recommend renaming the service. Only reuse the name if the developer explicitly overrides the recommendation.
运行冲突检查参考文档，查询Observe中是否存在使用请求的
service.name
的现有服务。如果发现冲突，建议重命名该服务。仅当开发者明确覆盖该建议时，才可复用原有名称。

6. Handle vendor instrumentation

6. 处理厂商插桩方案

If discovery found Datadog, New Relic, Dynatrace, Splunk, AppDynamics, Elastic APM, or other non-OTel agents:
  • Pause before making changes.
  • Explain that double instrumentation can create duplicate spans, conflicting context propagation, duplicate exporters, or misleading telemetry.
  • Recommend replacing or disabling the existing vendor instrumentation before adding OpenTelemetry.
  • Only proceed if the developer explicitly agrees with the migration or disablement plan.
如果发现过程中检测到Datadog、New Relic、Dynatrace、Splunk、AppDynamics、Elastic APM或其他非OTel代理：
  • 在进行更改前暂停操作。
  • 说明双重插桩可能会导致重复的spans、上下文传播冲突、重复的导出器或误导性的遥测数据。
  • 建议在添加OpenTelemetry之前替换或禁用现有的厂商插桩方案。
  • 仅当开发者明确同意迁移或禁用计划时，才可继续操作。

7. Handle existing OTel instrumentation

7. 处理已有的OTel插桩

If discovery found existing OpenTelemetry instrumentation, run the existing-otel-audit reference before changing anything. The audit branches into one of three outcomes:
  • healthy: no code changes needed. Tell the developer the setup looks healthy and point them to 
    opentelemetry-validation
    for Observe-side confirmation.
  • improve: fix the gaps in place instead of starting over.
  • uncertain: pause, explain what is unknown, and ask before making disruptive changes.
如果发现过程中检测到已有的OpenTelemetry插桩，在进行任何更改前先运行现有OTel审计参考文档。审计会产生以下三种结果之一：
  • 健康：无需修改代码。告知开发者当前配置看起来健康，并引导他们使用
    opentelemetry-validation
    在Observe端进行确认。
  • 需优化：就地修复现有漏洞，无需重新开始。
  • 不确定：暂停操作，说明未知情况，并在进行破坏性更改前征求开发者意见。

8. Resolve latest library versions

8. 确定最新库版本

Before presenting a plan, run the version resolution commands from the appropriate language-specific reference to capture the latest stable versions of all auto-instrumentation packages. These resolved versions must be used in the plan and in all subsequent install commands. Do not rely on package manager defaults to pick the latest version implicitly.
在提出方案前，运行对应语言参考文档中的版本解析命令，获取所有自动插桩包的最新稳定版本。这些解析后的版本必须用于方案及后续所有安装命令中。请勿依赖包管理器默认自动选择最新版本。

9. Summarize context and present a plan

9. 汇总上下文并提出方案

Summarize the analysis and present a reviewable plan before making changes. The plan should include:
  • A list of libraries along with their versions:
    • Categorized as follows
      • Web/HTTP
      • Web/RPC
      • ORM
      • Database Client
      • Cache Client
      • Messaging Client
    • For each library, populate the following columns based on the Observe support matrix:
      • Trace Explorer
      • Service Catalog
      • Service Maps
      • Service Inspector
      • R.E.D Metrics
      • Deployments
      • Error / Exception Tracking
  • Exact dependencies to add or update
  • File edits and startup changes
  • Environment variables
  • Manual caveats or known limitations
Ask the developer to approve the plan before applying changes.
在进行更改前，先汇总分析结果并提出可审核的方案。方案应包含：
  • 库及其版本列表：
    • 按以下类别划分
      • Web/HTTP
      • Web/RPC
      • ORM
      • 数据库客户端
      • 缓存客户端
      • 消息客户端
    • 根据Observe支持矩阵，为每个库填充以下列：
      • Trace Explorer
      • 服务目录
      • 服务地图
      • 服务检查器
      • R.E.D指标
      • 部署
      • 错误/异常追踪
  • 需添加或更新的具体依赖
  • 文件编辑和启动项更改
  • 环境变量
  • 手动注意事项或已知限制
在应用更改前，请开发者批准该方案。

10. Instrument the application

10. 为应用程序插桩

Apply the approved changes using the appropriate language-specific reference:
ReferenceDescription
javaJava auto-instrumentation setup
dotnet.NET auto-instrumentation setup
pythonPython auto-instrumentation setup
nodejsNode.js auto-instrumentation setup
rubyRuby auto-instrumentation setup
configureConfiguration and operation
使用对应语言的参考文档应用已批准的更改：
参考文档描述内容
javaJava自动插桩配置
dotnet.NET自动插桩配置
pythonPython自动插桩配置
nodejsNode.js自动插桩配置
rubyRuby自动插桩配置
configure配置与运维

11. Configure and hand off

11. 配置与交接

  • Provide operational guidance to configure instrumentation for the target platform using the configure reference. Do not make changes to the developer's infrastructure.Instead, if a change is required, provide them with the command to execute.
  • Ask the user if they have installed the 
    Observe Agent
    for data collection.
    • If already installed, provide operational guidance and exit.
    • If not installed, refer to one of the following skills depending on the user's target environment:
SkillDescription
deploy-k8s-explorer
Onboarding data for Kubernetes using the Observe Agent
deploy-linux-host-explorer
Onboarding data for bare metal or VMs using the Observe Agent
  • Finally, recommend that the user triggers the 
    opentelemetry-validation
    skill to perform necessary checks once the instrumented application and the Observe Agent are operational.
  • 使用配置参考文档，为目标平台提供插桩配置的运维指导。请勿修改开发者的基础设施。如果需要更改，请提供对应的执行命令。
  • 询问用户是否已安装
    Observe Agent
    用于数据收集：
    • 如果已安装，提供运维指导后结束操作。
    • 如果未安装，根据用户的目标环境参考以下技能之一：
技能名称描述内容
deploy-k8s-explorer
使用Observe Agent完成Kubernetes的数据接入
deploy-linux-host-explorer
使用Observe Agent完成裸金属或虚拟机的数据接入
  • 最后，建议用户在插桩后的应用程序和Observe Agent正常运行后，触发
    opentelemetry-validation
    技能执行必要的检查。",