Stay organized with collections Save and categorize content based on your preferences.
This document describes how to modify a Node.js JavaScript app to collect trace and metric data using the open source OpenTelemetry framework, and how to write structured JSON logs to standard out. This document also provides information about a sample Node.js app that you can install and run. The app uses the Fastify web framework and is configured to generate metrics, traces, and logs.
To learn more about instrumentation, see the following documents:
Note: This document displays only selected portions of a working application. For example, the sample doesn't display the list of imported packages. However, the full application is available on GitHub. To view the full sample, click more_vert More, and then select View on GitHub. About manual and zero-code instrumentationFor this language, OpenTelemetry defines zero-code instrumentation as the practice of collecting telemetry from libraries and frameworks without making code changes. However, you do have install modules and set environment variables.
This document doesn't describe zero-code instrumentation. For information about that topic, see JavaScript zero-code instrumentation.
For general information, see OpenTelemetry Instrumentation for Node.
Before you beginInstall the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
gcloud init
Create or select a Google Cloud project.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace PROJECT_ID with your Google Cloud project name.
Verify that billing is enabled for your Google Cloud project.
Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:
gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com
Install the Google Cloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
To initialize the gcloud CLI, run the following command:
gcloud init
Create or select a Google Cloud project.
Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.Create a Google Cloud project:
gcloud projects create PROJECT_ID
Replace PROJECT_ID with a name for the Google Cloud project you are creating.
Select the Google Cloud project that you created:
gcloud config set project PROJECT_ID
Replace PROJECT_ID with your Google Cloud project name.
Verify that billing is enabled for your Google Cloud project.
Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs:
gcloud services enable logging.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com
To instrument your app to collect trace and metric data, and to write structured JSON to standard out, perform the following steps as described in subsequent sections of this document:
The default configuration for the OpenTelemetry Node.js SDK exports traces by using the OTLP protocol. It also configures OpenTelemetry to use the W3C Trace Context format for propagating trace context. This configuration ensures that spans have the correct parent-child relationship within a trace.
The following code sample illustrates a JavaScript module to setup OpenTelemetry.
To view the full sample, click more_vert More, and then select View on GitHub.
The previous code sample configures OpenTelemetry to export metrics using the OTLP protocol, and it uses the @opentelemetry/auto-instrumentations-node package to configure all available Node.js instrumentations.
To ensure that all pending telemetry is flushed and that connections are closed gracefully before the application shuts down, the SIGTERM handler calls shutdown.
For more information and configuration options, see Zero-Code Instrumentation Configuration.
Configure your app to preload the OpenTelemetry configurationTo configure the app to write structured logs and to collect metrics and trace data by using OpenTelemetry, update the invocation of your app to preload the instrumentation module with the Node.js --require flag. Using the --require flag ensures that OpenTelemetry is initialized before your app starts. For more information, see OpenTelemetry Node.js Getting Started.
The following code sample illustrates a Dockerfile passing the --require flag:
To include the trace information as part of the JSON-formatted logs written to standard output, configure your app to output structured logs in JSON format. Fastify uses the Pino log framework and provides a logger in each request handler. The following code sample illustrates a Pino LoggerOptions object that configures the app to output JSON structured logs:
The previous configuration extracts information about the active span from the log message, and then adds that information as attributes to the JSON structured log. These attributes can then be used to correlate a log with a trace:
logging.googleapis.com/trace: Resource name of the trace associated with the log entry.logging.googleapis.com/spanId: The span ID with the trace that is associated with the log entry.logging.googleapis.com/trace_sampled: The value of this field must be true or false.For more information about these fields, see the LogEntry structure.
To use the Pino configuration with Fastify, pass the logger config object when creating the Fastify app:
Write structured logsTo write structured logs that link to a trace, use the Fastify provided Pino logger. For example, the following statement shows how to call the Logger.info() method:
request.log.info({subRequests}, 'handle /multi request');
OpenTelemetry automatically populates the Pino log entries with the span context of the current active span in the OpenTelemetry Context. This span context is then included in the JSON logs as described in Configure structured logging.
Run a sample app configured to collect telemetryThe example app uses vendor-neutral formats, including JSON for logs and OTLP for metrics and traces, and the Fastify framework. To route the telemetry to Google Cloud, this sample uses the OpenTelemetry Collector configured with Google exporters. The app has two endpoints:
The /multi endpoint is handled by the handleMulti function. The load generator in the app issues requests to the /multi endpoint. When this endpoint receives a request, it sends between three and seven requests to the /single endpoint on the local server.
The /single endpoint is handled by the handleSingle function. When this endpoint receives a request, it sleeps for a short delay and then responds with a string.
To run the sample, do the following:
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Clone the repository:
git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-js
Go to the sample directory:
cd opentelemetry-operations-js/samples/instrumentation-quickstart
Build and run the sample:
docker compose up --abort-on-container-exit
If you aren't running on Cloud Shell, then run the application with the GOOGLE_APPLICATION_CREDENTIALS environment variable pointing to a credentials file. Application Default Credentials provides a credentials file at $HOME/.config/gcloud/application_default_credentials.json.
# Set environment variables
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
export USERID="$(id -u)"
# Run
docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
The OpenTelemetry instrumentation in the sample app generates Prometheus metrics that you can view by using the Metrics Explorer:
Prometheus/http_server_duration_milliseconds/histogram records the duration of server requests and stores the results in a histogram.
Prometheus/http_client_duration_milliseconds/histogram records the duration of client requests and stores the results in a histogram.
To view the metrics generated by the sample app, do the following:
In the Google Cloud console, go to the leaderboard Metrics explorer page:
If you use the search bar to find this page, then select the result whose subheading is Monitoring.
http_server in the filter bar, and then use the submenus to select a specific resource type and metric:
When the measurements for a metric are cumulative, Metrics Explorer automatically normalizes the measured data by the alignment period, which which results in the chart displaying a rate. For more information, see Kinds, types, and conversions.
When integer or double values are measured, such as with the two counter metrics, Metrics Explorer automatically sums all time series. To view the data for the /multi and /single HTTP routes, set the first menu of the Aggregation entry to None.
For more information about configuring a chart, see Select metrics when using Metrics Explorer.
It might take several minutes before your trace data is available. For example, when trace data is received by your project, Google Cloud Observability might need to create a database to store that data. The creation of the database can take a few minutes and during that period, no trace data is available to view.
To view your trace data, do the following:
In the Google Cloud console, go to the Trace explorer page:
You can also find this page by using the search bar.
/multi.In the Gantt chart on the Trace details panel, select the span labeled /multi.
A panel opens that displays information about the HTTP request. These details include the method, status code, number of bytes, and the user agent of the caller.
To view the logs associated with this trace, select the Logs & Events tab.
The tab shows individual logs. To view the details of the log entry, expand the log entry. You can also click View Logs and view the log by using the Logs Explorer.
For more information about using the Cloud Trace explorer, see Find and explore traces.
View your logsFrom the Logs Explorer, you can inspect your logs, and you can also view associated traces, when they exist.
In the Google Cloud console, go to the Logs Explorer page:
If you use the search bar to find this page, then select the result whose subheading is Logging.
Locate a log with the description of handle /multi request.
To view the details of the log, expand the log entry.
Click Traces on a log entry with the "handle /multi request" message, and then select View trace details.
A Trace details panel opens and displays the selected trace.
Your log data might be available several minutes before your trace data is available. If you encounter an error when viewing trace data either by searching for a trace by ID or by following the steps in this task, then wait a minute or two and retry the action.
For more information about using the Logs Explorer, see View logs by using the Logs Explorer.
What's nextExcept as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-08-15 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-15 UTC."],[],[]]
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4