diff --git a/doc/diagnostics.html b/doc/diagnostics.html index 438cdce45facfa..cea870285f8afc 100644 --- a/doc/diagnostics.html +++ b/doc/diagnostics.html @@ -10,87 +10,69 @@ Do not send CLs removing the interior tags from such phrases. --> -

Introduction

+

介绍

-The Go ecosystem provides a large suite of APIs and tools to -diagnose logic and performance problems in Go programs. This page -summarizes the available tools and helps Go users pick the right one -for their specific problem. +Go 生态系统提供了一系列 API 和工具来诊断 Go 程序中的逻辑问题和性能问题。 +本页面总结了可用的工具, 并帮助 Go 用户选择合适的工具来处理他们的特定问题。

-Diagnostics solutions can be categorized into the following groups: +诊断方案可以被归类为以下几个类型:

-Note: Some diagnostics tools may interfere with each other. For example, precise -memory profiling skews CPU profiles and goroutine blocking profiling affects scheduler -trace. Use tools in isolation to get more precise info. +注意: 某些诊断工具可能会相互干扰。例如,精确的内存 profiling 会扭曲 CPU 画像, +goroutine 阻塞性分析 (goroutine blocking profiling) 会影响调度器跟踪。请单独使用工具以获得更精确的信息。

Profiling

-Profiling is useful for identifying expensive or frequently called sections -of code. The Go runtime provides -profiling data in the format expected by the -pprof visualization tool. -The profiling data can be collected during testing -via go test or endpoints made available from the -net/http/pprof package. Users need to collect the profiling data and use pprof tools to filter -and visualize the top code paths. +Profiling 对识别代价高昂的或者频繁调用的代码块是非常有用的。 Go 运行时提供了满足pprof可视化工具格式需要的profiling 数据。 Profiling 数据能够通过运行go test或者调用包 +net/http/pprof来进行测试时收集。 用户需要收集 profiling 数据,并使用 pprof 工具来过滤和可视化顶级代码路经。

-

Predefined profiles provided by the runtime/pprof package:

+

由包runtime/pprof提供的预定义 profiles : +

-

What other profilers can I use to profile Go programs?

+

还有其他可以用来分析 Go 程序的 profile 吗?

-

+

在Linux系统中,perf 工具可以用来分析 Go 程序。 +Perf可以分析和回溯 cgo/SWIG 代码和内核,以便深入了解本机/内核性能瓶颈。在macOs系统中,Instruments +suite可以用来分析Go程序。 On Linux, perf tools can be used for profiling Go programs. Perf can profile and unwind cgo/SWIG code and kernel, so it can be useful to get insights into @@ -99,9 +81,10 @@

Profiling

suite can be used profile Go programs.

-

Can I profile my production services?

+

我能分析生产环境的服务吗?Can I profile my production services?

-

Yes. It is safe to profile programs in production, but enabling +

是的。在生产环境中分析程序是安全的,但是启用某些分析包(如CPU分析包)会增加成本。你应该会看到性能下降。在生成环境中打开探查器之前,可以通过测量它的开销来评估性能损耗。 +Yes. It is safe to profile programs in production, but enabling some profiles (e.g. the CPU profile) adds cost. You should expect to see performance downgrade. The performance penalty can be estimated by measuring the overhead of the profiler before turning it on in @@ -121,7 +104,7 @@

Profiling

-What are the best ways to visualize the profiling data? +What are the best ways to visualize the profiling data?可视化profiling数据的最优方式是什么?

@@ -135,16 +118,17 @@

Profiling


-Listing of the most expensive calls as text. +使用文本列出代价最高昂的调用。Listing of the most expensive calls as text.


-Visualization of the most expensive calls as a graph. +使用图可视化代价最高昂的调用。Visualization of the most expensive calls as a graph.

-

Weblist view displays the expensive parts of the source line by line in +

网页列表视图在一个HTML页面中逐行展示了源码中代价高昂的部分。在下面的示例中,runtime.concatstrings花费了530ms,每行代码的代价都在出现在列表中。 +Weblist view displays the expensive parts of the source line by line in an HTML page. In the following example, 530ms is spent in the runtime.concatstrings and cost of each line is presented in the listing.

@@ -152,10 +136,11 @@

Profiling


-Visualization of the most expensive calls as weblist. +使用网页列表可视化代价最高昂的调用。Visualization of the most expensive calls as weblist.

+另外一种可视化profiling数据的方式是flame graph。Flame图允许你在特定的祖先路径中移动,因此你可以放大/缩小代码的特定部分。upstream pprof已经支持Flame图。 Another way to visualize profile data is a flame graph. Flame graphs allow you to move in a specific ancestry path, so you can zoom in/out of specific sections of code. @@ -166,18 +151,21 @@

Profiling


-Flame graphs offers visualization to spot the most expensive code-paths. +Flame图提供可视化功能,可用于发现代价最高昂的代码路经。 +Flame graphs offers visualization to spot the most expensive code-paths.

-

Am I restricted to the built-in profiles?

+

我只能使用内置的profiles吗?Am I restricted to the built-in profiles?

+除了运行时提供的profiles外,Go用户还可以通过pprof.Profile创建自定义的profiles,并使用已有的工具来检查它们。 Additionally to what is provided by the runtime, Go users can create their custom profiles via pprof.Profile and use the existing tools to examine them.

-

Can I serve the profiler handlers (/debug/pprof/...) on a different path and port?

+

我能够用不同的路经和端口提供profiler handlers(/debug/pprof/...)服务吗? + Can I serve the profiler handlers (/debug/pprof/...) on a different path and port?

Yes. The net/http/pprof package registers its handlers to the default @@ -186,6 +174,7 @@

Profiling

+例如,下面的示例将在:7777端口的/custom_debug_path/profile路基下提供pprof.Profile handler的服务。 For example, the following example will serve the pprof.Profile handler on :7777 at /custom_debug_path/profile:

@@ -208,9 +197,10 @@

Profiling

-

Tracing

+

跟踪Tracing

+跟踪是一种检测代码的方法,用于分析调用链整个生命周期中的延迟。Go提供golang.org/x/net/trace包作为每个Go节点的最小跟踪后端,并提供一个带有简单仪表板的最小检测库。Go还提供了一个执行跟踪程序来跟踪间隔内的运行时事件。 Tracing is a way to instrument code to analyze latency throughout the lifecycle of a chain of calls. Go provides golang.org/x/net/trace @@ -219,16 +209,18 @@

Tracing

an execution tracer to trace the runtime events within an interval.

-

Tracing enables us to:

+

跟踪使我们能够: +Tracing enables us to:

+在单片机系统中,从程序的构建块中收集诊断数据相对容易。所有模块都运行在一个进程中,共享公共资源来报告日志、错误和其他诊断信息。一旦您的系统超出了单个进程,开始变得分布式,那么在响应返回给用户之前,从前端web服务器到所有后端的调用就变得更加困难。这就是分布式跟踪在检测和分析您的生产系统方面发挥重要作用的地方。 In monolithic systems, it's relatively easy to collect diagnostic data from the building blocks of a program. All modules live within one process and share common resources to report logs, errors, and other @@ -240,6 +232,7 @@

Tracing

+分布式跟踪是一种在用户请求的生命周期内分析延迟的方法。当系统是分布式的,并且传统的分析和调试工具无法扩展时,您可能需要使用分布式跟踪工具来分析用户请求和RPC的性能。 Distributed tracing is a way to instrument code to analyze latency throughout the lifecycle of a user request. When a system is distributed and when conventional profiling and debugging tools don’t scale, you might want @@ -247,30 +240,32 @@

Tracing

requests and RPCs.

-

Distributed tracing enables us to:

+

分布式跟踪使我们能够:Distributed tracing enables us to:

-

The Go ecosystem provides various distributed tracing libraries per tracing system +

Go生态系统为每个跟踪系统和后端不可知的Profiling系统提供各种分布式跟踪库。The Go ecosystem provides various distributed tracing libraries per tracing system and backend-agnostic ones.

-

Is there a way to automatically intercept each function call and create traces?

+

有没有办法自动拦截每个函数调用并创建跟踪?Is there a way to automatically intercept each function call and create traces?

+Go没有提供一种自动拦截每个函数调用并创建跟踪范围的方法。您需要手动插入代码以创建、结束和注释范围。 Go doesn’t provide a way to automatically intercept every function call and create trace spans. You need to manually instrument your code to create, end, and annotate spans.

-

How should I propagate trace headers in Go libraries?

+

我应该如何在Go库中传播跟踪头?How should I propagate trace headers in Go libraries?

+可以在context.Context中传播跟踪标识符和标记。业界还没有规范的跟踪键或跟踪头的通用表示形式。每个跟踪提供者负责在其Go库中提供传播公用程序。 You can propagate trace identifiers and tags in the context.Context. There is no canonical trace key or common representation of trace headers @@ -279,11 +274,12 @@

Tracing

-What other low-level events from the standard library or +跟踪中还可以包括标准库或运行时的其他低级别事件?What other low-level events from the standard library or runtime can be included in a trace?

+标准库和运行时正在尝试公开几个附加的API,以便低级内部事件通知它们。例如,httptrace.ClientTrace提供了可用于跟踪传出请求生命周期中低级事件的API。目前正在努力从运行时执行跟踪器中获取低级运行时事件,并允许用户定义和记录他们的用户事件。 The standard library and runtime are trying to expose several additional APIs to notify on low level internal events. For example, httptrace.ClientTrace @@ -292,25 +288,29 @@

Tracing

the runtime execution tracer and allow users to define and record their user events.

-

Debugging

+

调试

+调试是一个识别程序为什么会出错的过程。调试器允许我们了解程序的执行流程和当前状态。有几种类型的调试;本节只关注将调试器附加到程序和核心转储调试。 Debugging is the process of identifying why a program misbehaves. Debuggers allow us to understand a program’s execution flow and current state. There are several styles of debugging; this section will only focus on attaching a debugger to a program and core dump debugging.

-

Go users mostly use the following debuggers:

+

Go用户主要使用以下调试器:Go users mostly use the following debuggers:

-

How well do debuggers work with Go programs?

+

调试器与Go程序配合得如何?How well do debuggers work with Go programs?

+gc编译器执行诸如函数内联和变量注册之类的优化。这些优化有时会使使用调试器进行调试更加困难。目前正在努力提高为优化过的二进制代码生成的DWARF信息的质量。在这些改进可用之前,我们建议在构建即将调试的代码时禁用优化。以下命令生成一个没有编译器优化的包: The gc compiler performs optimizations such as function inlining and variable registerization. These optimizations sometimes make debugging with debuggers harder. There is an ongoing @@ -337,7 +338,7 @@

Debugging

$ go build -gcflags=all="-N -l"

- +作为改进工作的一部分,Go 1.10引入了一个新的编译器标志-dwarflocationlists。该标志使编译器添加位置列表,以帮助调试器处理优化过的二进制代码。以下命令使用优化构建包,但包含DWARF位置列表: As part of the improvement effort, Go 1.10 introduced a new compiler flag -dwarflocationlists. The flag causes the compiler to add location lists that helps debuggers work with optimized binaries. @@ -350,16 +351,18 @@

Debugging

-

What’s the recommended debugger user interface?

+

推荐的调试器用户界面是什么?What’s the recommended debugger user interface?

+尽管delve和gdb都提供CLIs,但是大多数编辑集成器和IDE都提供了调试特定的用户界面。 Even though both delve and gdb provides CLIs, most editor integrations and IDEs provides debugging-specific user interfaces.

-

Is it possible to do postmortem debugging with Go programs?

+

可以对Go程序进行事后调试吗?Is it possible to do postmortem debugging with Go programs?

+核心转储文件中包含正在运行进程的内存转储及其进程状态。它主要用于程序的事后调试,并在程序仍在运行时了解其状态。这两个案例使核心转储调试成为事后分析和生产服务分析的一个很好的诊断辅助工具。从Go程序中获取核心转储文件并使用delve或gdb进行调试是可行的,请参阅核心转储调试页面以了解分步指南。 A core dump file is a file that contains the memory dump of a running process and its process status. It is primarily used for post-mortem debugging of a program and to understand its state @@ -371,15 +374,17 @@

Debugging

page for a step-by-step guide.

-

Runtime statistics and events

+

运行时统计和事件Runtime statistics and events

+运行时提供内部事件的统计信息和报告,供用户在运行时级别诊断性能和利用率问题。 The runtime provides stats and reporting of internal events for users to diagnose performance and utilization problems at the runtime level.

+用户可以监控这些统计数据,以便更好地了解Go程序的整体健康状况和性能。一些经常被监控的统计和状态: Users can monitor these stats to better understand the overall health and performance of Go programs. Some frequently monitored stats and states: @@ -387,33 +392,40 @@

Runtime statistics and events

-

Execution tracer

+

执行跟踪器Execution tracer

-

Go comes with a runtime execution tracer to capture a wide range +

+Go附带了一个运行时执行跟踪器来捕获广泛的运行时事件。调度、系统调用、垃圾回收、堆大小和其他事件由运行时收集,并可通过go工具跟踪进行可视化。执行跟踪器是一种检测延迟和利用率问题的工具。您可以检查CPU的利用率,以及什么时候网络或系统调用引起了goroutine抢占。 +Go comes with a runtime execution tracer to capture a wide range of runtime events. Scheduling, syscall, garbage collections, heap size, and other events are collected by runtime and available for visualization by the go tool trace. Execution tracer is a tool @@ -421,14 +433,14 @@

Execution tracer

the CPU is utilized, and when networking or syscalls are a cause of preemption for the goroutines.

-

Tracer is useful to:

+

跟踪器可用于:Tracer is useful to:

-

However, it is not great for identifying hot spots such as +

但是,对于识别热点(如分析内存或CPU使用过多的原因)来说,这并不是什么好方法。首先使用profiling工具来定位这些问题。However, it is not great for identifying hot spots such as analyzing the cause of excessive memory or CPU usage. Use profiling tools instead first to address them.

@@ -436,37 +448,49 @@

Execution tracer

-

Above, the go tool trace visualization shows the execution started +

在上图中,go工具跟踪可视化显示开始时运行得很好,然后就序列化了。这表明共享资源可能存在锁争用,从而造成瓶颈。 + + + +Above, the go tool trace visualization shows the execution started fine, and then it became serialized. It suggests that there might be lock contention for a shared resource that creates a bottleneck.

-

See go tool trace +

请参阅go tool trace以收集和分析运行时跟踪。 +See go tool trace to collect and analyze runtime traces.

GODEBUG

-

Runtime also emits events and information if +

+如果GODEBUG环境变量按照要求进行设置,运行时也会提交事件和信息。 +Runtime also emits events and information if GODEBUG environmental variable is set accordingly.

-

The GODEBUG environmental variable can be used to disable use of +

GODEBUG环境变量可用于在标准库和运行时中禁用指令集扩展。 +The GODEBUG environmental variable can be used to disable use of instruction set extensions in the standard library and runtime.