Mantenha tudo organizado com as coleções
Salve e categorize o conteúdo com base nas suas preferências.
Este documento descreve a estrutura dos exemplos de instrumentação fornecidos para as linguagens Go, Java, Node.js e Python.
Estes exemplos fornecem orientações sobre como instrumentar uma aplicação.
Pode ter interesse noutros exemplos que ilustram diferentes
configurações:
O artigo Correlacione métricas e rastreios através de exemplares
descreve como configurar uma aplicação Go para gerar exemplares.
Um exemplar é um ponto de dados de exemplo anexado a um ponto de dados de métrica.
Pode usar exemplos para correlacionar os dados de rastreio e métricas.
Os exemplos para Go, Java, Node.js e Python usam o protocolo OpenTelemetry para recolher dados de rastreio e métricas.
Os exemplos configuram uma framework de registo para escrever
registos estruturados e o coletor OpenTelemetry está configurado para ler a partir do fluxo stdout da aplicação. Para recomendações de estruturas, consulte o artigo
Escolha uma abordagem de instrumentação.
As aplicações são criadas e implementadas através do Docker. Não tem de usar o Docker quando instrumenta uma aplicação com o OpenTelemetry.
Pode executar os exemplos no Cloud Shell, em Google Cloud
recursos ou num ambiente de desenvolvimento local.
Análise detalhada
Os exemplos usam o OpenTelemetry Collector como um sidecar
para receber e enriquecer a telemetria da aplicação, que é depois enviada para o seu
Google Cloud projeto através de um Google Cloud exportador. O exportador converte a telemetria num formato compatível com a Cloud Trace API, a Cloud Monitoring API ou a Cloud Logging API. Em seguida, enviam os dados transformados para o seu
Google Cloud projeto através da emissão de um comando da API.
Os exemplos mostram como fazer o seguinte:
Configure o OpenTelemetry para recolher métricas e rastreios através do coletor OpenTelemetry.
Se rever os exemplos, vai reparar que a complexidade deste passo depende do idioma. Por exemplo, para o Go, este passo configura a função main para chamar uma função que configura a recolha de métricas e rastreios. Para o Go, o servidor e o cliente HTTP também são atualizados.
Recomendamos que as suas aplicações escrevam registos estruturados, o que faz com que a carga útil do registo seja formatada como um objeto JSON. Para estes registos, pode
criar consultas que pesquisem caminhos JSON específicos e pode
indexar campos específicos no payload do registo.
Alguns serviços, como o Google Kubernetes Engine, têm agentes incorporados que extraem registos estruturados e enviam esses registos para o seu projeto. Google Cloud Outros serviços, como o Compute Engine, exigem que instale um agente que
extrai e envia os seus registos. Se quiser saber mais sobre os agentes que instala,
consulte a vista geral do agente do Ops.
Não precisa de instalar agentes para usar estes exemplos.
Configure ficheiros Docker. Todos os exemplos contêm os seguintes ficheiros YAML:
docker-compose.yaml: configura os serviços para a aplicação, o coletor do OpenTelemetry e um gerador de carga.
Por exemplo, o serviço para o coletor OpenTelemetry, otelcol, especifica uma imagem, um volume e variáveis de ambiente.
O ponto final do coletor OpenTelemetry é definido pela variável de ambiente OTEL_EXPORTER_OTLP_ENDPOINT, que é especificada no serviço app.
otel-collector-config.yaml: configura os recetores, os exportadores, os processadores e os pipelines.
O serviço telemetry define pipelines para dados de rastreio, métricas e registos. Cada entrada do pipeline especifica um recetor, um processador e um exportador. O mesmo recetor, otlp, é usado para métricas e rastreios.
A secção exporters descreve como os dados recolhidos são exportados para um Google Cloud projeto. Para toda a telemetria, é usado um Google Cloud exportador. O exportador converte a telemetria num formato compatível com a API Cloud Trace, a API Cloud Monitoring ou a API Cloud Logging. Em seguida, envia os dados transformados para o seu
Google Cloud projeto emitindo um comando da API.
docker-compose.creds.yaml: este ficheiro monta opcionalmente um ficheiro de credenciais no contentor otelcol.Google Cloud Este ficheiro é necessário quando um exemplo é executado numa máquina local onde as credenciais predefinidas da aplicação (ADC) estão disponíveis apenas como um ficheiro.
Autorizações necessárias
Se executar os exemplos no Cloud Shell, em Google Cloud
recursos ou num ambiente de desenvolvimento local, as autorizações indicadas
nesta secção são suficientes. Para aplicações de produção, normalmente, uma conta de serviço fornece as credenciais para escrever dados de registo, métricas e rastreio.
Para receber as autorizações de que precisa para que as aplicações de exemplo escrevam dados de registo, métricas e rastreios, peça ao seu administrador que lhe conceda as seguintes funções da IAM no seu projeto:
Para receber as autorizações de que
precisa para ver os seus dados de registo, métricas e rastreio,
peça ao seu administrador que lhe conceda as
seguintes funções da IAM no seu projeto:
[[["Fácil de entender","easyToUnderstand","thumb-up"],["Meu problema foi resolvido","solvedMyProblem","thumb-up"],["Outro","otherUp","thumb-up"]],[["Difícil de entender","hardToUnderstand","thumb-down"],["Informações incorretas ou exemplo de código","incorrectInformationOrSampleCode","thumb-down"],["Não contém as informações/amostras de que eu preciso","missingTheInformationSamplesINeed","thumb-down"],["Problema na tradução","translationIssue","thumb-down"],["Outro","otherDown","thumb-down"]],["Última atualização 2025-08-21 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)."]]
