Serverless

Instrument your serverless functions with OpenTelemetry JavaScript

This guide shows how to get started with tracing serverless functions using OpenTelemetry instrumentation libraries.

AWS Lambda

The following show how to use Lambda wrappers with OpenTelemetry to instrument AWS Lambda functions manually and send traces to a configured backend.

If you are interested in a plug and play user experience, see OpenTelemetry Lambda Layers.

Dependencies

First, create an empty package.json:

npm init -y

Then install the required dependencies:

npm install \
  @opentelemetry/api \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http \
  @opentelemetry/instrumentation \
  @opentelemetry/sdk-trace-base \
  @opentelemetry/sdk-trace-node

AWS Lambda wrapper code

This file contains all the OpenTelemetry logic, which enables tracing. Save the following code as lambda-wrapper.js.

/* lambda-wrapper.js */

const api = require('@opentelemetry/api');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const {
  OTLPTraceExporter,
} = require('@opentelemetry/exporter-trace-otlp-http');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const {
  getNodeAutoInstrumentations,
} = require('@opentelemetry/auto-instrumentations-node');

api.diag.setLogger(new api.DiagConsoleLogger(), api.DiagLogLevel.ALL);

const provider = new NodeTracerProvider();
const collectorOptions = {
  url: '<backend_url>',
};

const spanProcessor = new BatchSpanProcessor(
  new OTLPTraceExporter(collectorOptions),
);

provider.addSpanProcessor(spanProcessor);
provider.register();

registerInstrumentations({
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-aws-lambda': {
        disableAwsContextPropagation: true,
      },
    }),
  ],
});

Replace <backend_url> with the URL of your favorite backend to export all traces to it. If you don’t have one setup already, you can check out Jaeger or Zipkin.

Note that disableAwsContextPropagation is set to true. The reason for this is that the Lambda instrumentation tries to use the X-Ray context headers by default, unless active tracing is enabled for this function, this results in a non-sampled context, which creates a NonRecordingSpan.

More details can be found in the instrumentation documentation.

AWS Lambda function handler

Now that you have a Lambda wrapper, create a simple handler that serves as a Lambda function. Save the following code as handler.js.

/* handler.js */

'use strict';

const https = require('https');

function getRequest() {
  const url = 'https://opentelemetry.io/';

  return new Promise((resolve, reject) => {
    const req = https.get(url, (res) => {
      resolve(res.statusCode);
    });

    req.on('error', (err) => {
      reject(new Error(err));
    });
  });
}

exports.handler = async (event) => {
  try {
    const result = await getRequest();
    return {
      statusCode: result,
    };
  } catch (error) {
    return {
      statusCode: 400,
      body: error.message,
    };
  }
};

Deployment

There are multiple ways of deploying your Lambda function:

Here we will be using Serverless Framework, more details can be found in the Setting Up Serverless Framework guide.

Create a file called serverless.yml:

service: lambda-otel-native
frameworkVersion: '3'
provider:
  name: aws
  runtime: nodejs14.x
  region: '<your-region>'
  environment:
    NODE_OPTIONS: --require lambda-wrapper
functions:
  lambda-otel-test:
    handler: handler.hello

For OpenTelemetry to work properly, lambda-wrapper.js must be included before any other file: the NODE_OPTIONS setting ensures this.

Note if you are not using Serverless Framework to deploy your Lambda function, you must manually add this environment variable using the AWS Console UI.

Finally, run the following command to deploy the project to AWS:

serverless deploy

You can now invoke the newly deployed Lambda function by using the AWS Console UI. You should expect to see spans related to the invocation of the Lambda function.

Visiting the backend

You should now be able to view traces produced by OpenTelemetry from your Lambda function in the backend!

GCP function

The following shows how to instrument HTTP triggered function using the Google Cloud Platform (GCP) UI.

Creating function

Login to GCP and create or select a project where your function should be placed. In the side menu go to Serverless and select Cloud Functions. Next, click on Create Function, and select 2nd generation for your environment, provide a function name and select your region.

Setup environment variable for otelwrapper

If closed, open the Runtime, build, connections and security settings menu and scroll down and add the environment variable NODE_OPTIONS with the following value:

--require ./otelwrapper.js

Select runtime

On the next screen (Code), select Node.js version 16 for your runtime.

Create OTel wrapper

Create a new file called otelwrapper.js, that will be used to instrument your service. Please make sure that you provide a SERVICE_NAME and that you set the <address for your backend>.

/* otelwrapper.js */

const { Resource } = require('@opentelemetry/resources');
const {
  SEMRESATTRS_SERVICE_NAME,
} = require('@opentelemetry/semantic-conventions');
const api = require('@opentelemetry/api');
const { BatchSpanProcessor } = require('@opentelemetry/sdk-trace-base');
const {
  OTLPTraceExporter,
} = require('@opentelemetry/exporter-trace-otlp-http');
const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const { registerInstrumentations } = require('@opentelemetry/instrumentation');
const {
  getNodeAutoInstrumentations,
} = require('@opentelemetry/auto-instrumentations-node');

const providerConfig = {
  resource: new Resource({
    [SEMRESATTRS_SERVICE_NAME]: '<your function name>',
  }),
};

api.diag.setLogger(new api.DiagConsoleLogger(), api.DiagLogLevel.ALL);

const provider = new NodeTracerProvider(providerConfig);
const collectorOptions = {
  url: '<address for your backend>',
};

const spanProcessor = new BatchSpanProcessor(
  new OTLPTraceExporter(collectorOptions),
);

provider.addSpanProcessor(spanProcessor);
provider.register();

registerInstrumentations({
  instrumentations: [getNodeAutoInstrumentations()],
});

Add package dependencies

Add the following to your package.json:

{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0",
    "@opentelemetry/api": "^1.3.0",
    "@opentelemetry/auto-instrumentations-node": "^0.35.0",
    "@opentelemetry/exporter-trace-otlp-http": "^0.34.0",
    "@opentelemetry/instrumentation": "^0.34.0",
    "@opentelemetry/sdk-node": "^0.34.0",
    "@opentelemetry/sdk-trace-base": "^1.8.0",
    "@opentelemetry/sdk-trace-node": "^1.8.0",
    "@opentelemetry/resources": "^1.8.0",
    "@opentelemetry/semantic-conventions": "^1.8.0"
  }
}

Add HTTP call to function

The following code makes a call to the OpenTelemetry web site to demonstrate an outbound call.

/* index.js */
const functions = require('@google-cloud/functions-framework');
const https = require('https');

functions.http('helloHttp', (req, res) => {
  let url = 'https://opentelemetry.io/';
  https
    .get(url, (response) => {
      res.send(`Response ${response.body}!`);
    })
    .on('error', (e) => {
      res.send(`Error ${e}!`);
    });
});

Backend

If you run OTel collector in GCP VM you are likely to need to create VPC access connector to be able to send traces.

Deploy

Select Deploy in UI and await deployment to be ready.

Testing

You can test the function using cloud shell from test tab.


Last modified June 21, 2024: Update and fix textlinter (#4728) (22821f42)