이 문서에서는 Go, Java, Node.js, Python 언어용으로 제공되는 계측 샘플의 구조를 설명합니다.
이 샘플에서는 애플리케이션을 계측하는 방법을 안내합니다.
다른 구성을 보여주는 다른 샘플도 확인해 보세요.
실례를 사용하여 측정항목과 trace 간의 상관관계 보기에서는 실례를 생성하도록 Go 애플리케이션을 구성하는 방법을 설명합니다.
실례는 측정항목 데이터 포인트에 연결된 데이터 포인트 예시입니다.
실례를 사용하여 trace 데이터와 측정항목 데이터의 상관관계를 파악할 수 있습니다.
Go, Java, Node.js, Python용 샘플은 OpenTelemetry 프로토콜을 사용하여 trace 및 측정항목 데이터를 수집합니다.
샘플은 구조화된 로그를 작성하도록 로깅 프레임워크를 구성하고 OpenTelemetry 수집기는 애플리케이션의 stdout 스트림에서 읽도록 구성됩니다. 계측 권장사항은 계측 방법 선택을 참조하세요.
애플리케이션은 Docker를 사용하여 빌드 및 배포됩니다. OpenTelemetry로 애플리케이션을 계측할 때 Docker를 사용할 필요는 없습니다.
Cloud Shell, Google Cloud리소스 또는 로컬 개발 환경에서 샘플을 실행할 수 있습니다.
심층 분석
샘플은 OpenTelemetry Collector를 사이드카로 사용하여 애플리케이션의 원격 분석을 수신하고 보강한 후 Google Cloud 내보내기 도구를 사용하여Google Cloud 프로젝트로 전송합니다. 내보내기 도구는 원격 분석을 Cloud Trace API, Cloud Monitoring API 또는 Cloud Logging API와 호환되는 형식으로 변환합니다. 그런 다음 API 명령어를 실행하여 변환된 데이터를Google Cloud 프로젝트로 전송합니다.
애플리케이션에서 구조화된 로그를 작성하는 것이 좋습니다. 그러면 로그 페이로드가 JSON 객체 형식으로 지정됩니다. 이러한 로그의 경우 특정 JSON 경로를 검색하는 쿼리를 구성하고 로그 페이로드의 특정 필드에 색인을 생성할 수 있습니다.
Google Kubernetes Engine과 같은 일부 서비스에는 구조화된 로그를 스크래핑하고 이러한 로그를 Google Cloud 프로젝트로 전송하는 에이전트가 내장되어 있습니다. Compute Engine과 같은 다른 서비스의 경우 로그를 스크래핑하고 전송하는 에이전트를 설치해야 합니다. 설치하는 에이전트에 대해 알아보려면 운영 에이전트 개요를 참조하세요.
이 샘플을 사용하기 위해 에이전트를 설치할 필요는 없습니다.
Docker 파일을 구성합니다. 모든 샘플에는 다음 YAML 파일이 포함되어 있습니다.
docker-compose.yaml: 애플리케이션의 서비스, OpenTelemetry 수집기, 부하 생성기를 구성합니다.
예를 들어 OpenTelemetry Collector의 서비스인 otelcol은 이미지, 볼륨, 환경 변수를 지정합니다.
OpenTelemetry 수집기의 엔드포인트는 app 서비스에 지정된 OTEL_EXPORTER_OTLP_ENDPOINT 환경 변수에 의해 설정됩니다.
telemetry 서비스는 trace, 측정항목, 로그 데이터의 파이프라인을 정의합니다. 각 파이프라인 항목은 수신기, 프로세서, 내보내기 도구를 지정합니다. 측정항목과 trace에 동일한 수신자(otlp)가 사용됩니다.
exporters 섹션에서는 수집된 데이터를 Google Cloud 프로젝트로 내보내는 방법을 설명합니다. 모든 원격 분석에는 Google Cloud 내보내기 도구가 사용됩니다. 내보내기 도구는 원격 분석을 Cloud Trace API, Cloud Monitoring API 또는 Cloud Logging API와 호환되는 형식으로 변환합니다. 그런 다음 API 명령어를 실행하여 변환된 데이터를Google Cloud 프로젝트로 전송합니다.
docker-compose.creds.yaml: 이 파일은 선택적으로 otelcol 컨테이너에Google Cloud 사용자 인증 정보 파일을 마운트합니다. 이 파일은 애플리케이션 기본 사용자 인증 정보(ADC)를 파일로만 사용할 수 있는 로컬 머신에서 샘플을 실행할 때 필요합니다.
필수 권한
Cloud Shell, Google Cloud리소스 또는 로컬 개발 환경에서 샘플을 실행하는 경우 이 섹션에 나열된 권한으로 충분합니다. 프로덕션 애플리케이션의 경우 일반적으로 서비스 계정이 로그, 측정항목, trace 데이터를 작성하는 사용자 인증 정보를 제공합니다.
샘플 애플리케이션에서 로그, 측정항목, trace 데이터를 작성하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-07-26(UTC)"],[],[],null,["# Instrumentation samples overview\n\nThis document describes the structure of the instrumentation samples provided\nfor the [Go](/trace/docs/setup/go), [Java](/trace/docs/setup/java),\n[Node.js](/trace/docs/setup/nodejs), and [Python](/trace/docs/setup/python) languages.\nThese samples provide guidance about how to instrument an application.\n\nYou might be interested in other samples that illustrate different\nconfigurations:\n\n- [Correlate metrics and traces by using exemplars](/stackdriver/docs/instrumentation/advanced-topics/exemplars)\n describes how to configure a Go application to generate exemplars.\n An *exemplar* is an example data point attached to a metric data point.\n You can use exemplars to correlate your trace and metric data.\n\n- [Use the Ops Agent and OpenTelemetry Protocol (OTLP)](/trace/docs/otlp)\n describes how you can configure the Ops Agent and an OTLP receiver to\n collect metrics and traces from an application.\n\n| **Note:** The samples display only selected portions of a working application. For example, the samples don't display the list of imported packages. However, the complete applications are available on GitHub. From a code snippet, you can open GitHub by using the *more_vert* **More** options.\n\nHow the samples work\n--------------------\n\nThe samples for Go, Java, Node.js, and Python use the\n[OpenTelemetry protocol](https://opentelemetry.io/docs/specs/otlp/) to collect trace and metric data.\nThe samples configure a logging framework to write\n[structured logs](/logging/docs/structured-logging) and the\nOpenTelemetry collector is configured to read from\nthe application's `stdout` stream. For framework recommendations, see\n[Choose an instrumentation approach](/stackdriver/docs/instrumentation/choose-approach).\n\nThe applications are built and deployed by using Docker. You don't have to\nuse Docker when you instrument an application with OpenTelemetry.\n\nYou can run the samples in the Cloud Shell, on Google Cloud\nresources, or on a local development environment.\n\nDeep dive\n---------\n\nThe samples use the [OpenTelemetry Collector](https://opentelemetry.io/docs/collector/installation/) as a sidecar\nto receive and enrich the application's telemetry, which is then sent to your\nGoogle Cloud project by using a [Google Cloud exporter](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/exporter/googlecloudexporter/README.md). The exporter\nconverts the\ntelemetry into a format compatible with the Cloud Trace API, Cloud Monitoring API,\nor Cloud Logging API. Next, they send the transformed data to your\nGoogle Cloud project by issuing an API command.\n\nThe samples show how to do the following:\n\n1. Configure OpenTelemetry to collect metrics and traces by using the\n [OpenTelemetry collector](https://opentelemetry.io/docs/collector/).\n\n If you review the samples, you'll notice that the complexity of this step\n is language dependent. For example, for Go, this step configures the\n `main` function to call a function that configures the collection of\n metrics and traces. For Go, the HTTP server and client are also updated.\n2. Configure a logging framework to write [structured logs](/logging/docs/structured-logging).\n\n We recommend that your applications write structured logs, which results\n in the log payload being formatted as a JSON object. For these logs, you can\n construct queries that search specific JSON paths and you can\n index specific fields in the log payload.\n\n Some services, like Google Kubernetes Engine, have built-in agents that scrape\n structured logs and send those logs to your Google Cloud project. Other\n services, like Compute Engine, require that you install an agent, which\n scrapes and sends your logs. If you want to learn about agents you install,\n see [Ops Agent overview](/stackdriver/docs/solutions/agents/ops-agent).\n\n You don't need to install any agents to use these samples.\n3. Configure Docker files. All samples contain the following yaml files:\n\n - `docker-compose.yaml`: Configures the services for the application,\n the [OpenTelemetry collector](https://opentelemetry.io/docs/collector/), and a load generator.\n For example, the service for the OpenTelemetry collector, `otelcol`,\n specifies an image, a volume, and environment variables.\n The endpoint for the OpenTelemetry collector is set by the\n `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable, which is\n specified in the `app` service.\n\n - `otel-collector-config.yaml`: Configures the receivers, exporters,\n processors, and pipelines.\n\n The `telemetry` service defines pipelines for trace, metric, and log\n data. Each pipeline entry specifies a receiver, a processor, and an\n exporter. The same receiver, `otlp`, is used for metrics and traces.\n\n The `exporters` section describes how collected data is exported to\n a Google Cloud project. For all telemetry, a Google Cloud exporter is\n utilized. The exporter converts the telemetry into a format\n compatible with the Cloud Trace API, Cloud Monitoring API, or\n Cloud Logging API. Next, it sends the transformed data to your\n Google Cloud project by issuing an API command.\n - `docker-compose.creds.yaml`: This file optionally mounts a\n Google Cloud credentials file in the `otelcol` container. This file\n is needed when a sample is run on a local machine where the\n [Application Default Credentials (ADC)](/docs/authentication/application-default-credentials) are available\n only as a file.\n\nRequired permissions\n--------------------\n\nIf you run the samples in the Cloud Shell, on Google Cloud\nresources, or on a local development environment, then the permissions listed\nin this section are sufficient. For production applications, typically a\nservice account provides the credentials to write log, metric, and trace\ndata.\n\n-\n\n To get the permissions that\n you need to for the sample applications to write log, metric, and trace data,\n\n ask your administrator to grant you the\n following IAM roles on your project:\n\n - [Logs Writer](/iam/docs/roles-permissions/logging#logging.logWriter) (`roles/logging.logWriter`)\n - [Monitoring Metric Writer](/iam/docs/roles-permissions/monitoring#monitoring.metricWriter) (`roles/monitoring.metricWriter`)\n - [Cloud Trace Agent](/iam/docs/roles-permissions/cloudtrace#cloudtrace.agent) (`roles/cloudtrace.agent`)\n\n\n\u003c!-- --\u003e\n\n-\n\n To get the permissions that\n you need to view your log, metric, and trace data,\n\n ask your administrator to grant you the\n following IAM roles on your project:\n\n - [Logs Viewer](/iam/docs/roles-permissions/logging#logging.viewer) (`roles/logging.viewer`)\n - [Monitoring Viewer](/iam/docs/roles-permissions/monitoring#monitoring.viewer) (`roles/monitoring.viewer`)\n - [Cloud Trace User](/iam/docs/roles-permissions/cloudtrace#cloudtrace.user) (`roles/cloudtrace.user`)\n\n\n For more information about granting roles, see [Manage access to projects, folders, and organizations](/iam/docs/granting-changing-revoking-access).\n\n\n You might also be able to get\n the required permissions through [custom\n roles](/iam/docs/creating-custom-roles) or other [predefined\n roles](/iam/docs/roles-overview#predefined).\n\nRequired APIs\n-------------\n\nThe following provides information about the APIs required to send\ntelemetry data to a Google Cloud project: \n\n### Google Cloud console\n\n\nEnable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.\n\n\n[Enable the APIs](https://console.cloud.google.com/flows/enableapi?apiid=logging.googleapis.com,monitoring.googleapis.com,cloudtrace.googleapis.com)\n\n\u003cbr /\u003e\n\n### Google Cloud CLI\n\n\nEnable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.\n\n\n[Enable the APIs](https://console.cloud.google.com/flows/enableapi?apiid=logging.googleapis.com,monitoring.googleapis.com,cloudtrace.googleapis.com)\n\n\u003cbr /\u003e\n\nWhat's next\n-----------\n\n- [Go sample](/trace/docs/setup/go).\n- [Java sample](/trace/docs/setup/java).\n- [Node.js sample](/trace/docs/setup/nodejs).\n- [Python sample](/trace/docs/setup/python)."]]
