Overview of collector-based instrumentation samples

To keep your application code vendor-neutral while collecting and sending telemetry to Google Cloud, you can use the OpenTelemetry collector-based instrumentation samples for Go, Java, Node.js, and Python.

These samples demonstrate how to configure an in-process OpenTelemetry SDK to export metrics, logs, and traces to a local OpenTelemetry collector that routes your telemetry to Google Cloud. The samples send metric and trace data in OpenTelemetry Protocol (OTLP) format to your Google Cloud project by using the Telemetry API, and send log data by using a Google Cloud exporter.

How the samples work

The samples for Go, Java, Node.js, and Python use the OpenTelemetry protocol to collect trace and metric data. The samples configure a logging framework to write structured logs, and configure the OpenTelemetry collector to read from the application's stdout stream. For framework recommendations, see Choose an instrumentation approach.

The applications are built and deployed by using Docker. You don't have to use Docker when you instrument an application with OpenTelemetry.

You can run the samples in the Cloud Shell, on Google Cloud resources, or on a local development environment.

Deep dive

The samples use the OpenTelemetry Collector as a sidecar to receive and enrich the application's telemetry, which an exporter then sends to your Google Cloud project. The sample applications send metric and trace data to your project by using the Telemetry API, which supports the OTLP format.

The samples show how to do the following:

Configure OpenTelemetry to collect metrics and traces by using the OpenTelemetry collector.

The complexity of this step is language dependent. For example, in Go, you update the main function to initialize telemetry collection and configure the HTTP server and client.
Configure a logging framework to write structured logs.

We recommend that your applications write structured logs, which format the log payload as a JSON object. For these logs, you can construct queries that search specific JSON paths and you can index specific fields in the log payload.

Some services, like Google Kubernetes Engine, have built-in agents that scrape structured logs and send those logs to your Google Cloud project. Other services, like Compute Engine, require that you install an agent, which scrapes and sends your logs. To learn about agents you install, see Ops Agent overview.

You don't need to install any agents to use these samples.
Configure Docker files. All samples contain the following YAML files:
- docker-compose.yaml: Configures the services for the application, the OpenTelemetry collector, and a load generator. For example, the service for the OpenTelemetry collector, otelcol, specifies an image, a volume, and environment variables. The endpoint for the OpenTelemetry collector is set by the OTEL_EXPORTER_OTLP_ENDPOINT environment variable, which is specified in the app service.
- otel-collector-config.yaml: Configures the OpenTelemetry collector:
  - The samples use the otlp receiver for metric and trace data, and the filelog receiver for log data.
  - The samples use the otlphttp exporter for metric and trace data, and the Google Cloud exporter for log data.
    
    The otlphttp exporter sends data to your project by using the Telemetry API, which supports OTLP. The Google Cloud exporter converts your log data into a format compatible with the Cloud Logging API and then sends the transformed data to your Google Cloud project.
- docker-compose.creds.yaml: This file optionally mounts a Google Cloud credentials file in the otelcol container. You need this file when you run a sample on a local machine where Application Default Credentials (ADC) are available only as a file.

Required permissions

To get the permissions that you need to have the sample applications write log, metric, and trace data, ask your administrator to grant you the following IAM roles:
- Logs Writer (roles/logging.logWriter) on your project
- Monitoring Metric Writer (roles/monitoring.metricWriter) on your project
- Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter) on your project
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer) on your quota project
These permissions are sufficient if you run the sample in the Cloud Shell, on Google Cloud resources, or on a local development environment. To learn how to configure a quota project, see Set the quota project.

Note: Production applications typically rely on a service account to provide the credentials required to write log, metric, and trace data. In those scenarios, grant the previous roles to the service account.

To get the permissions that you need to view your log, metric, and trace data, ask your administrator to grant you the following IAM roles on your project:
- Logs Viewer (roles/logging.viewer)
- Monitoring Viewer (roles/monitoring.viewer)
- Cloud Trace User (roles/cloudtrace.user)
For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Required APIs

Enable the Cloud Logging, Cloud Monitoring, Cloud Trace, and Telemetry APIs:

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com telemetry.googleapis.com

Alternative instrumentation approaches

You might be interested in other samples that illustrate different configurations:

Migrate from the Trace exporter to the OTLP endpoint describes how to use in-process instrumentation to send trace data directly to your Google Cloud project.

We recommend that you use an OpenTelemetry collector to export your telemetry data when your environment supports use of a collector. If you can't use a collector, then you must use an in-process exporter that directly sends data to your Google Cloud project.
Correlate metrics and traces by using exemplars describes how to configure a Go application to generate exemplars. An exemplar is an example data point attached to a metric data point. You can use exemplars to correlate your trace and metric data.
Use the Ops Agent and OpenTelemetry Protocol (OTLP) describes how you can configure the Ops Agent and an OTLP receiver to collect metrics and traces from an application.

What's next

To learn more about collectors, see Google-Built OpenTelemetry Collector.

Explore the samples that use collector-based exports.