open-telemetry · windsonsea · Jul 7, 2025 · Jul 10, 2025
@@ -0,0 +1,44 @@
+---
+title: 插桩
+description: OpenTelemetry 如何促进插桩
+aliases: [instrumenting]
+weight: 15
+default_lang_commit: deb98d0648c4833d9e9d77d42e91e2872658b50c
+---
+
+要使系统具备[可观测性][observable]，就必须进行**插桩（Instrumentation）**：
+也就是说，系统组件中的代码必须发出[信号][signals]，如[链路][traces]、[指标][metrics]和[日志][logs]。
+
+使用 OpenTelemetry，你可以通过两种主要方式对代码进行插桩：
+
+1. 通过官方[适用于大多数编程语言的 API 和 SDK](/docs/languages/)的[代码开发方案](code-based/)
+2. [零代码方案](zero-code/)
+
+**基于代码**的方案可以让你从应用本身获取更深入的洞察和丰富的遥测数据。
+它们使你能够使用 OpenTelemetry API 从应用中生成遥测数据，作为零代码方案生成遥测数据的重要补充。
+
+**零代码**方案非常适合入门使用，或在你无法修改需要获取遥测数据的应用时使用。
+它们可以从你所使用的库和/或应用运行的环境中提供丰富的遥测数据。
+换句话说，它们提供的是关于应用**边缘**发生情况的信息。
+
+你可以同时使用这两种方案。
+
+## OpenTelemetry 的其他优势 {#additional-opentelemetry-benefits}
+
+OpenTelemetry 不仅仅提供零代码和基于代码的遥测解决方案。以下内容也是 OpenTelemetry 的一部分：
+
+- 代码库可以将 OpenTelemetry API 作为依赖项进行集成，除非导入 OpenTelemetry SDK，
+  否则对使用该库的应用不会产生任何影响。
+- 对于每种[信号]，你都有多种方法可以创建、处理和导出它们。
+- 借助实现中内建的[上下文传播](../context-propagation/)，你可以关联不同位置生成的信号。
+- [资源](../resources/)和[插桩作用域](../instrumentation-scope/)允许按不同实体对信号进行分组，
+  例如[主机](/docs/specs/semconv/resource/host/)、[操作系统](/docs/specs/semconv/resource/os/)或
+  [K8s 集群](/docs/specs/semconv/resource/k8s/#cluster)。
+- 每个语言特定的 API 和 SDK 实现都遵循 [OpenTelemetry 规范](/docs/specs/otel/)的要求和预期。
+- [语义约定](../semantic-conventions/)提供了一个通用的命名模式，可用于在不同代码库和平台之间实现标准化。
+
+[logs]: ../signals/logs/
+[metrics]: ../signals/metrics/
+[observable]: ../observability-primer/#what-is-observability
+[signals]: ../signals/
+[traces]: ../signals/traces/
@@ -0,0 +1,48 @@
+---
+title: 基于代码的方式
+description: 了解设置基于代码插桩的基本步骤
+weight: 20
+aliases: [manual]
+default_lang_commit: deb98d0648c4833d9e9d77d42e91e2872658b50c
+---
+
+## 导入 OpenTelemetry API 和 SDK {#import-the-opentelemetry-api-and-sdk}
+
+你首先需要在服务代码中导入 OpenTelemetry。如果你正在开发一个库或其他打算被可运行二进制文件使用的组件，
+那么你只需要依赖 API。如果你的构件是一个独立的进程或服务，那么你需要同时依赖 API 和 SDK。
+有关 OpenTelemetry API 和 SDK 的更多信息，请参阅[规范](/docs/specs/otel/)。
+
+## 配置 OpenTelemetry API {#configure-the-opentelemetry-api}
+
+为了创建链路或指标，你需要先创建一个 tracer 和/或 meter 提供程序。通常，我们建议
+SDK 为这些对象提供一个默认的单一提供程序。随后，你将从该提供程序获取一个 tracer 或 meter
+实例，并为其指定名称和版本。你在此处选择的名称应能标识正在进行插桩的对象。
+例如，如果你正在编写一个库，那么你应将其命名为你的库名称（例如 `com.example.myLibrary`），
+因为该名称将为所有生成的 Span 或指标事件设置命名空间。也建议你提供一个版本字符串
+（即 `semver:1.0.0`），对应于你库或服务的当前版本。
+
+## 配置 OpenTelemetry SDK {#configure-the-opentelemetry-sdk}
+
+如果你正在构建一个服务进程，你还需要使用适当的选项来配置 SDK，以便将你的遥测数据导出到某个分析后端。
+我们建议通过配置文件或其他机制以编程方式处理该配置。每种语言还提供可供调整的选项，你可能希望加以利用。
+
+## 创建遥测数据 {#create-telemetry-data}
+
+在你配置好 API 和 SDK 后，你就可以通过从提供程序获取的 tracer 和 meter
+对象来创建链路和指标事件。请为你的依赖项使用插桩库，
+即查看[镜像仓库](/ecosystem/registry/)或你所使用语言的代码仓库，以获取更多信息。
+
+## 导出数据 {#export-data}
+
+一旦你创建了遥测数据，你就需要将它发送出去。OpenTelemetry 支持两种主要的数据导出方式：
+直接从进程导出，或通过 [OpenTelemetry Collector](/docs/collector) 代理导出。
+
+进程内导出要求你导入并依赖一个或多个**导出器**，这些库将 OpenTelemetry 的内存中
+Span 和指标对象转换为适用于遥测分析工具（如 Jaeger 或 Prometheus）的格式。此外，
+OpenTelemetry 支持一种称为 `OTLP` 的传输协议，所有 OpenTelemetry SDK 都支持该协议。
+此协议可用于将数据发送到 OpenTelemetry Collector，这是一种独立的二进制进程，
+可以作为服务实例的代理或边车运行，也可以在单独的主机上运行。
+Collector 可配置为将这些数据转发并导出到你选择的分析工具中。
+
+除了 Jaeger 或 Prometheus 等开源工具外，越来越多的公司也支持从 OpenTelemetry
+接收遥测数据。详情请参阅[供应商](/ecosystem/vendors/)。
@@ -0,0 +1,42 @@
+---
+title: 零代码
+description: 了解如何在无需编写代码的情况下为应用添加可观测性
+weight: 10
+aliases: [automatic]
+default_lang_commit: deb98d0648c4833d9e9d77d42e91e2872658b50c
+---
+
+作为一名[运维人员](/docs/getting-started/ops/)，你可能希望在不编辑源代码的情况下为一个或多个应用添加可观测性。
+OpenTelemetry 允许你快速为某个服务增加一定程度的可观测性，而无需使用 OpenTelemetry API 和
+SDK 进行[基于代码的插桩](/docs/concepts/instrumentation/code-based)。
+
+![零代码](./zero-code.svg)
+
+零代码插桩通常以代理或类似代理的安装方式，将 OpenTelemetry API 和 SDK 的能力添加到你的应用中。
+所涉及的具体机制可能因语言而异，包括字节码操作、猴子补丁或 eBPF，用于将对
+OpenTelemetry API 和 SDK 的调用注入你的应用中。
+
+通常，零代码插桩会为你所使用的库添加插桩。这意味着对请求和响应、数据库调用、消息队列调用等操作进行了插桩。
+而你的应用代码本身通常不会被插桩。若要对你的代码进行插桩，
+你需要使用[基于代码的插桩](/docs/concepts/instrumentation/code-based)。
+
+此外，零代码插桩允许你配置加载的[插桩库](/docs/concepts/instrumentation/libraries)和[导出器](/docs/concepts/components/#exporters)。
+
+你可以通过环境变量和其他特定语言的机制（如系统属性或传递给初始化方法的参数）来配置零代码插桩。
+要开始使用，你只需要配置一个服务名称，以便你可以在所选择的可观测性后端中识别该服务。
+
+还有其他可用的配置选项，包括：
+
+- 特定数据源的配置
+- 导出器配置
+- 传播器配置
+- 资源配置
+
+以下语言提供了自动插桩功能：
+
+- [.NET](/docs/zero-code/dotnet/)
+- [Go](/docs/zero-code/go)
+- [Java](/docs/zero-code/java/)
+- [JavaScript](/docs/zero-code/js/)
+- [PHP](/docs/zero-code/php/)
+- [Python](/docs/zero-code/python/)