Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Dokumen ini menjelaskan struktur contoh instrumentasi yang disediakan untuk bahasa Go, Java, Node.js, dan Python.
Contoh ini memberikan panduan tentang cara menginstrumentasi aplikasi.
Anda mungkin tertarik dengan contoh lain yang menggambarkan berbagai
konfigurasi:
Mengorelasikan metrik dan rekaman aktivitas menggunakan contoh
menjelaskan cara mengonfigurasi aplikasi Go untuk membuat contoh.
Contoh adalah contoh titik data yang dilampirkan ke titik data metrik.
Anda dapat menggunakan contoh untuk mengorelasikan data metrik dan rekaman aktivitas.
Contoh untuk Go, Java, Node.js, dan Python menggunakan
protokol OpenTelemetry untuk mengumpulkan data trace dan metrik.
Contoh mengonfigurasi framework logging untuk menulis
log terstruktur dan
pengumpul OpenTelemetry dikonfigurasi untuk membaca dari
aliran stdout aplikasi. Untuk rekomendasi framework, lihat
Memilih pendekatan instrumentasi.
Aplikasi dibangun dan di-deploy menggunakan Docker. Anda tidak perlu
menggunakan Docker saat menginstrumentasi aplikasi dengan OpenTelemetry.
Anda dapat menjalankan contoh di Cloud Shell, di Google Cloud
resource, atau di lingkungan pengembangan lokal.
Pembahasan mendalam
Contoh ini menggunakan OpenTelemetry Collector sebagai file bantuan
untuk menerima dan memperkaya telemetri aplikasi, yang kemudian dikirim ke projectGoogle Cloud Anda menggunakan pengeksporGoogle Cloud . Exporter mengonversi telemetri ke dalam format yang kompatibel dengan Cloud Trace API, Cloud Monitoring API, atau Cloud Logging API. Selanjutnya, mereka mengirimkan data yang telah diubah ke project
Google Cloud Anda dengan menjalankan perintah API.
Contoh menunjukkan cara melakukan hal berikut:
Konfigurasi OpenTelemetry untuk mengumpulkan metrik dan trace menggunakan
OpenTelemetry Collector.
Jika meninjau sampel, Anda akan melihat bahwa kompleksitas langkah ini bergantung pada bahasa. Misalnya, untuk Go, langkah ini mengonfigurasi fungsi
main untuk memanggil fungsi yang mengonfigurasi pengumpulan
metrik dan rekaman aktivitas. Untuk Go, server dan klien HTTP juga diperbarui.
Konfigurasi framework logging untuk menulis log terstruktur.
Sebaiknya aplikasi Anda menulis log terstruktur, yang menghasilkan
payload log yang diformat sebagai objek JSON. Untuk log ini, Anda dapat membuat kueri yang menelusuri jalur JSON tertentu dan mengindeks kolom tertentu dalam payload log.
Beberapa layanan, seperti Google Kubernetes Engine, memiliki agen bawaan yang meng-scrape log terstruktur dan mengirimkan log tersebut ke project Anda. Google Cloud Layanan
lainnya, seperti Compute Engine, mengharuskan Anda menginstal agen, yang
meng-scrape dan mengirim log Anda. Jika Anda ingin mempelajari agen yang Anda instal, lihat Ringkasan Agen Operasional.
Anda tidak perlu menginstal agen apa pun untuk menggunakan sampel ini.
Konfigurasi file Docker. Semua sampel berisi file YAML berikut:
docker-compose.yaml: Mengonfigurasi layanan untuk aplikasi,
OpenTelemetry Collector, dan generator beban.
Misalnya, layanan untuk pengumpul OpenTelemetry, otelcol,
menentukan image, volume, dan variabel lingkungan.
Endpoint untuk pengumpul OpenTelemetry ditetapkan oleh variabel lingkungan
OTEL_EXPORTER_OTLP_ENDPOINT, yang
ditentukan dalam layanan app.
otel-collector-config.yaml: Mengonfigurasi penerima, pengekspor,
pemroses, dan pipeline.
Layanan telemetry menentukan pipeline untuk data log, metrik, dan rekaman aktivitas. Setiap entri pipeline menentukan penerima, pemroses, dan
pengekspor. Penerima yang sama, otlp, digunakan untuk metrik dan rekaman aktivitas.
Bagian exporters menjelaskan cara data yang dikumpulkan diekspor ke project Google Cloud . Untuk semua telemetri, Google Cloud exporter digunakan. Exporter mengonversi telemetri ke dalam format yang kompatibel dengan Cloud Trace API, Cloud Monitoring API, atau Cloud Logging API. Selanjutnya, data yang telah diubah akan dikirim ke
Google Cloud project Anda dengan menjalankan perintah API.
docker-compose.creds.yaml: File ini secara opsional memasang
file kredensialGoogle Cloud di penampung otelcol. File ini diperlukan saat sampel dijalankan di komputer lokal tempat
Kredensial Default Aplikasi (ADC) hanya tersedia
sebagai file.
Izin yang diperlukan
Jika Anda menjalankan sampel di Cloud Shell, di Google Cloud
resource, atau di lingkungan pengembangan lokal, izin yang tercantum
di bagian ini sudah cukup. Untuk aplikasi produksi, biasanya
akun layanan menyediakan kredensial untuk menulis data log, metrik, dan trace.
Untuk mendapatkan izin yang Anda perlukan agar aplikasi contoh dapat menulis data log, metrik, dan aktivitas, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:
Untuk mendapatkan izin yang Anda perlukan guna melihat data log, metrik, dan rekaman aktivitas, minta administrator Anda untuk memberi Anda peran IAM berikut di project Anda:
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 2025-08-12 UTC."],[],[],null,["# Instrumentation samples overview\n\nThis document describes the structure of the instrumentation samples provided\nfor the [Go](/stackdriver/docs/instrumentation/setup/go), [Java](/stackdriver/docs/instrumentation/setup/java),\n[Node.js](/stackdriver/docs/instrumentation/setup/nodejs), and [Python](/stackdriver/docs/instrumentation/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](/stackdriver/docs/instrumentation/setup/go).\n- [Java sample](/stackdriver/docs/instrumentation/setup/java).\n- [Node.js sample](/stackdriver/docs/instrumentation/setup/nodejs).\n- [Python sample](/stackdriver/docs/instrumentation/setup/python)."]]
