otel-instrumentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenTelemetry Instrumentation Guide

OpenTelemetry 埋点实施指南

Expert guidance for implementing high-quality, cost-efficient OpenTelemetry telemetry.

关于实施高质量、高性价比OpenTelemetry遥测的专业指南。

Rules

规则

Rule	Description
telemetry	Entrypoint - signal types, correlation, and navigation
resolve-values	Resolving configuration values from the codebase
resources	Resource attributes - service identity and environment
k8s	Kubernetes deployment - downward API, pod spec
spans	Spans - naming, kind, status, and hygiene
logs	Logs - structured logging, severity, trace correlation
metrics	Metrics - instrument types, naming, units, cardinality
nodejs	Node.js instrumentation setup
go	Go instrumentation setup
python	Python instrumentation setup
java	Java instrumentation setup
scala	Scala instrumentation setup
dotnet	.NET instrumentation setup
ruby	Ruby instrumentation setup
php	PHP instrumentation setup
browser	Browser instrumentation setup
nextjs	Next.js full-stack instrumentation (App Router)

规则	描述
telemetry	入口规则 - 信号类型、关联与导航
resolve-values	从代码库中解析配置值
resources	资源属性 - 服务标识与环境
k8s	Kubernetes 部署 - Downward API、Pod 规格
spans	Span - 命名、类型、状态与规范
logs	日志 - 结构化日志、日志级别、链路关联
metrics	指标 - 埋点类型、命名、单位、基数
nodejs	Node.js 埋点设置
go	Go 埋点设置
python	Python 埋点设置
java	Java 埋点设置
scala	Scala 埋点设置
dotnet	.NET 埋点设置
ruby	Ruby 埋点设置
php	PHP 埋点设置
browser	浏览器端埋点设置
nextjs	Next.js 全栈埋点设置（App Router）

Official documentation

官方文档

Key principles

核心原则

Signal density over volume

重信号密度而非数量

Every telemetry item should serve one of three purposes:

Detect - Help identify that something is wrong
Localize - Help pinpoint where the problem is
Explain - Help understand why it happened

If it doesn't serve one of these purposes, don't emit it.

每条遥测数据应满足以下三个用途之一：

检测 - 帮助识别异常情况
定位 - 帮助精准定位问题位置
解释 - 帮助理解问题发生原因

如果不满足其中任一用途，则无需生成该数据。

Sample in the pipeline, not the SDK

在管道中采样，而非SDK中

Use the

AlwaysOn

sampler (the default) in every SDK. Do not configure SDK-side samplers — they make irreversible decisions before the outcome of a request is known. Defer all sampling to the Collector, where policies can be changed centrally without redeploying applications.

SDK (AlwaysOn)  →  Collector (sampling)  →  Backend (retention)
     ↓                    ↓                       ↓
  All spans         Head or tail            Storage policies
  exported          sampling applied

在所有SDK中使用

AlwaysOn

采样器（默认配置）。不要在SDK端配置采样器——它们会在请求结果确定前做出不可逆转的采样决策。将所有采样操作延迟到Collector中执行，这样可以在无需重新部署应用的情况下集中修改采样策略。

SDK (AlwaysOn)  →  Collector (sampling)  →  Backend (retention)
     ↓                    ↓                       ↓
  All spans         Head or tail            Storage policies
  exported          sampling applied

Quick reference

快速参考

Use Case	Rule
Node.js backend	nodejs
Go backend	go
Python backend	python
Java backend	java
Scala backend	scala
.NET backend	dotnet
Ruby backend	ruby
PHP backend	php
Browser frontend	browser
Next.js (App Router)	nextjs
Kubernetes pod spec	k8s
Resolve config values	resolve-values
Resource attributes	resources
Writing metrics	metrics
Cardinality management	metrics
Span naming, kind, status	spans
Writing logs	logs
Signal overview	telemetry

使用场景	对应规则
Node.js 后端	nodejs
Go 后端	go
Python 后端	python
Java 后端	java
Scala 后端	scala
.NET 后端	dotnet
Ruby 后端	ruby
PHP 后端	php
浏览器前端	browser
Next.js（App Router）	nextjs
Kubernetes Pod 规格	k8s
解析配置值	resolve-values
资源属性	resources
指标编写	metrics
基数管理	metrics
Span 命名、类型、状态	spans
日志编写	logs
信号概览	telemetry