Descripción general de las muestras de instrumentación
Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
En este documento, se describe la estructura de las muestras de instrumentación proporcionadas para los lenguajes Go, Java, Node.js y Python.
En estos ejemplos, se brinda orientación sobre cómo instrumentar una aplicación.
Es posible que te interesen otros ejemplos que ilustran diferentes configuraciones:
En Correlaciona las métricas y los seguimientos con ejemplares, se describe cómo configurar una aplicación de Go para generar ejemplares.
Un ejemplar es un dato de ejemplo adjunto a un dato de métrica.
Puedes usar ejemplares para correlacionar tus datos de seguimiento y métricas.
Las muestras para Go, Java, Node.js y Python usan el protocolo OpenTelemetry para recopilar datos de seguimiento y métricas.
En los ejemplos, se configura un framework de registro para escribir registros estructurados y el recopilador de OpenTelemetry se configura para leer desde el flujo stdout de la aplicación. Para obtener recomendaciones sobre frameworks, consulta Elige un enfoque de instrumentación.
Las aplicaciones se compilan y se implementan con Docker. No es necesario que uses Docker cuando instrumentas una aplicación con OpenTelemetry.
Puedes ejecutar las muestras en Cloud Shell, en recursos de Google Cloudo en un entorno de desarrollo local.
Análisis detallado
En los ejemplos, se usa el recopilador de OpenTelemetry como un sidecar para recibir y enriquecer la telemetría de la aplicación, que luego se envía a tu proyecto deGoogle Cloud con un Google Cloud exportador. El exportador convierte la telemetría en un formato compatible con la API de Cloud Trace, la API de Cloud Monitoring o la API de Cloud Logging. Luego, envían los datos transformados a tu proyectoGoogle Cloud con un comando de API.
En los ejemplos, se muestra cómo hacer lo siguiente:
Si revisas las muestras, notarás que la complejidad de este paso depende del idioma. Por ejemplo, en Go, este paso configura la función main para que llame a una función que configura la recopilación de métricas y registros. En el caso de Go, también se actualizan el servidor y el cliente HTTP.
Te recomendamos que tus aplicaciones escriban registros estructurados, lo que hace que la carga útil del registro se formatee como un objeto JSON. En el caso de estos registros, puedes crear consultas que busquen rutas de acceso JSON específicas y puedes indexar campos específicos en la carga útil del registro.
Algunos servicios, como Google Kubernetes Engine, tienen agentes integrados que extraen registros estructurados y los envían a tu proyecto de Google Cloud . Otros servicios, como Compute Engine, requieren que instales un agente que extrae y envía tus registros. Si deseas obtener información sobre los agentes que instalas, consulta Descripción general del agente de operaciones.
No es necesario que instales ningún agente para usar estas muestras.
Configura los archivos de Docker. Todas las muestras contienen los siguientes archivos YAML:
docker-compose.yaml: Configura los servicios para la aplicación, el recopilador de OpenTelemetry y un generador de carga.
Por ejemplo, el servicio para el recopilador de OpenTelemetry, otelcol, especifica una imagen, un volumen y variables de entorno.
El extremo del recopilador de OpenTelemetry se establece con la variable de entorno OTEL_EXPORTER_OTLP_ENDPOINT, que se especifica en el servicio app.
otel-collector-config.yaml: Configura los receptores, los exportadores, los procesadores y las canalizaciones.
El servicio telemetry define canalizaciones para los datos de registro, métricas y seguimiento. Cada entrada de la canalización especifica un receptor, un procesador y un exportador. El mismo receptor, otlp, se usa para las métricas y los registros.
En la sección exporters, se describe cómo se exportan los datos recopilados a un proyecto de Google Cloud . Para toda la telemetría, se utiliza un exportador Google Cloud . El exportador convierte la telemetría en un formato compatible con la API de Cloud Trace, la API de Cloud Monitoring o la API de Cloud Logging. Luego, envía los datos transformados a tu proyectoGoogle Cloud con un comando de la API.
docker-compose.creds.yaml: Este archivo puede, de manera opcional, montar un archivo de credencialesGoogle Cloud en el contenedor otelcol. Este archivo es necesario cuando se ejecuta una muestra en una máquina local en la que las credenciales predeterminadas de la aplicación (ADC) solo están disponibles como un archivo.
Permisos necesarios
Si ejecutas las muestras en Cloud Shell, en recursos Google Cloudo en un entorno de desarrollo local, los permisos que se indican en esta sección son suficientes. En el caso de las aplicaciones de producción, por lo general, una cuenta de servicio proporciona las credenciales para escribir datos de registros, métricas y seguimientos.
Para obtener los permisos que
necesitas para que las aplicaciones de ejemplo escriban datos de registros, métricas y seguimiento,
pídele a tu administrador que te otorgue los
siguientes roles de IAM en tu proyecto:
Para obtener los permisos que
necesitas para ver tus datos de registros, métricas y seguimientos,
pídele a tu administrador que te otorgue los
siguientes roles de IAM en tu proyecto:
[[["Fácil de comprender","easyToUnderstand","thumb-up"],["Resolvió mi problema","solvedMyProblem","thumb-up"],["Otro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Información o código de muestra incorrectos","incorrectInformationOrSampleCode","thumb-down"],["Faltan la información o los ejemplos que necesito","missingTheInformationSamplesINeed","thumb-down"],["Problema de traducción","translationIssue","thumb-down"],["Otro","otherDown","thumb-down"]],["Última actualización: 2025-09-04 (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)."]]
