插桩是指生成或收集有关应用运行时行为的数据的特定代码。在应用内部,插桩(例如 OpenTelemetry 提供的插桩)可以收集有关语言运行时、框架或应用逻辑的领域特定信息,然后将该数据发送到 Google Cloud 项目或其他目标位置。这些数据(也称为遥测数据)包括指标、日志和跟踪记录。
系统级指标(如 CPU 使用率、内存用量和磁盘使用率)对于检测应用的问题非常有用,但它们无法提供关于应用级问题的详细分析洞见。插桩可帮助您的应用生成诊断问题根本原因所需的数据,因为生成的遥测数据会显示应用内部发生的情况。例如,日志通常包含有关程序的上下文,例如特定错误消息或堆栈轨迹,以及源代码中的位置。同样,分布式跟踪记录可帮助您了解多个服务在处理请求时如何进行交互。通过指标,您可以在应用行为不正常时收到通知。
对应用进行插桩涉及生成遥测数据并将其发送到可存储和查询数据的位置。例如,您的插桩可能会将遥测数据发送到 Google Cloud 项目。Google Cloud Observability 中的服务可帮助您收集、分析和关联遥测数据。它们还提供了内置默认设置,可帮助您更快地开始使用,例如默认信息中心和提醒政策。 如需详细了解 Google Cloud Observability,请参阅 Google Cloud中的可观测性。
下图说明了应用如何使用插桩生成遥测数据并将其发送到存储系统:
如上图所示,插桩代码存在于应用的进程中,并与应用进行交互以生成遥测数据。然后,插桩框架将遥测数据导出到已配置的存储系统。在该图中,存储系统是您的 Google Cloud 项目。
不受制于供应商的插桩框架简介
即使您打算仅将遥测数据发送到 Google Cloud,我们也建议您使用不受制于供应商的开源插桩框架来对应用进行插桩。这类框架具有以下主要优势:
[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC):2025-09-04。"],[],[],null,["# Instrumentation and observability\n\n*Instrumentation* refers to the specific code that generates or collects data\nabout your application's runtime behavior. Inside of your application,\ninstrumentation, such as that provided by OpenTelemetry,\ncan collect domain specific information about the\nlanguage runtime, framework, or application logic, and then send that data\nto a Google Cloud project or to some other destination.\nThis data, which is also known as *telemetry* , includes\n[metrics](/stackdriver/docs#metrics-def), [logs](/stackdriver/docs#logs-def), and\n[traces](/stackdriver/docs#traces-def).\n\nSystem-level metrics such as CPU usage, memory usage, and disk usage are\nvaluable for detecting problems with your application, but they don't provide\nmuch insight into application-level concerns. Instrumentation can help your\napplication generate the data that you need to\ndiagnose the root cause of a problem, because the resulting telemetry shows\nyou what is happening inside of your application.\nFor example, logs often include context about your\nprogram like a specific error message or stacktrace, and the location in\nyour source code. Similarly, distributed traces help you understand how multiple\nservices interact when processing requests. Metrics let you get notified\nwhen your application isn't behaving correctly.\n\nInstrumenting your application involves generating telemetry and sending it\nto where the data can be stored and queried. For example, your instrumentation\nmight send telemetry to a Google Cloud project.\nServices in Google Cloud Observability help you to collect, analyze, and\ncorrelate telemetry data. They also provide built-in defaults to help you get\nstarted faster such as default dashboards and alert policies. For\nmore information about Google Cloud Observability, see\n[Observability in Google Cloud](/stackdriver/docs).\n\nThe following figure illustrates how an application uses instrumentation to\ngenerate and send telemetry to a storage system:\n\nAs illustrated in previous figure, the instrumentation code exists within your\napplication's process and interacts with the application to generate telemetry\ndata. The instrumentation framework then exports your telemetry to a configured\nstorage system. In the figure, the storage system is your Google Cloud project.\n\nAbout vendor-neutral instrumentation frameworks\n-----------------------------------------------\n\nEven if you plan to send telemetry only to Google Cloud, we recommend that you\nuse a vendor-neutral open source instrumentation framework to instrument your\napplications. These types of frameworks have some key benefits:\n\nNo vendor lock-in\n: Vendor-neutral frameworks aren't tied to any particular vendor and they\n provide their own data model for the generated telemetry. Therefore, you\n can send data to multiple vendors, and you usually can change which vendor\n you use without modifying your code.\n\nStandardized procedures for collecting telemetry\n: Well-designed frameworks, such as OpenTelemetry, provide a standardized approach\n to collecting telemetry from applications. You can use the same framework\n for applications written in supported languages. And because the\n framework is standardized, you can collect and compare the telemetry from\n all of your services.\n\nInteroperable libraries\n: Instrumentation frameworks include a rich ecosystem of libraries that\n gather telemetry signals, and these libraries are interoperable.\n For example, OpenTelemetry provides libraries to collect trace data and to\n collect metric data. You can use either library, or both libraries.\n\nGeneral recommendations\n-----------------------\n\nThis section contains general recommendations about how to instrument your\napplication. For guidance that is specific to Google Cloud,\nsee [Choose an instrumentation approach](/stackdriver/docs/instrumentation/choose-approach).\n\nTo collect metrics, we recommend that you use [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) or\n[Prometheus](https://prometheus.io):\n\n- OpenTelemetry is an open source project that provides a\n unified framework for application instrumentation. It also provides\n instrumentation libraries for popular libraries.\n OpenTelemetry provides a standalone agent,\n the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/), that can receive, transform,\n and export telemetry. The\n [OpenTelemetry Collector configuration file](https://opentelemetry.io/docs/collector/configuration/)\n determines the behavior of the OpenTelemetry Collector.\n To send telemetry to an agent or directly to a storage system, use the\n [OpenTelemetry Protocol (OTLP)](https://opentelemetry.io/docs/specs/otlp/).\n\n- Prometheus is a popular open source\n monitoring system. You can use the\n [Prometheus client libraries](https://prometheus.io/docs/instrumenting/clientlibs/) to\n generate metrics from your application, and there is a third-party\n ecosystem of instrumentation libraries for popular frameworks.\n Prometheus clients expose their metrics as an HTTP endpoint that can be\n scraped by an agent.\n\nTo collect traces, we recommend that you use [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/).\n\nTo collect logs, we recommend that you use a framework which can be\nconfigured to output\n[JSON-structured logs for Cloud Logging](/logging/docs/structured-logging).\nFor writing log data, we recommend the following:\n\n- Go: [`slog`](https://pkg.go.dev/log/slog).\n- Python: [`logging`](https://docs.python.org/3/library/logging.html).\n- JavaScript: [Pino](https://getpino.io/).\n- Java: [SLF4J](https://www.slf4j.org/) with [Log4j2](https://logging.apache.org/log4j/2.x/).\n\nGoogle Cloud solutions\n----------------------\n\nGoogle Cloud Observability provides flexible options for collecting telemetry:\n\n- For code samples that illustrate how to instrument your application to\n send telemetry to Google Cloud, see the following:\n\n - [Sample overview](/stackdriver/docs/instrumentation/setup/sample-overview).\n - [Go instrumentation sample](/stackdriver/docs/instrumentation/setup/go).\n - [Java instrumentation sample](/stackdriver/docs/instrumentation/setup/java).\n - [Node.js instrumentation sample](/stackdriver/docs/instrumentation/setup/nodejs).\n - [Python instrumentation sample](/stackdriver/docs/instrumentation/setup/python).\n- To learn how to collect and view latency data from your applications, see\n [View latency of app requests](/trace/docs/trace-app-latency).\n\n- For information about Google Cloud's fully managed, multi-cloud,\n cross-project solution for Prometheus, see\n [Google Cloud Managed Service for Prometheus](/stackdriver/docs/managed-prometheus).\n\n- For information about how to configure the [Ops Agent](/stackdriver/docs/solutions/agents/ops-agent),\n see the following documents:\n\n - [Collect OTLP metrics and traces](/stackdriver/docs/solutions/agents/ops-agent/otlp).\n - [Collect Prometheus metrics](/monitoring/agent/ops-agent/prometheus).\n\nWhat's next\n-----------\n\nFor more information about Google Cloud Observability, see\n[Observability in Google Cloud](/stackdriver/docs)."]]