Add sample for opentelemetry-js

2nd-gen/instrument-with-opentelemetry/README.md

@@ -0,0 +1,30 @@
+# Instrumenting Cloud Functions for Firebase with Open Telemetry
+This sample demonstrates instrumenting your Cloud Functions for Firebase using [OpenTelemetry](https://opentelemetry.io).
+
+See Firebase Summit 2022 Talk "Observability in Cloud Functions for Firebase" for motivations and context.
+
+Open Telemetry SDK provides both automatic and manual instrumentation, both of which are demonstrated here. See [OpenTelemetry JS documentations](https://opentelemetry.io/docs/instrumentation/js/) for more information about how to use and configure OpenTelemetry for your javascript project.
+
+## Notable Files
+* `./tracing.js`: Initializes OpenTelemetry SDK to automatically instrument HTTP/GRPC/Express modules and export the generated traces to Google Cloud Trace.
+
+* `./.env`: Configures `NODE_OPTIONS` to preload the `tracing.js` module. This is important because OpenTelemtry SDK works by monkey-patching instrumented modules and must run first before other module is loaded.
+
+* `./index.js`: Includes sample code for generating custom spans using the OpenTelemetry API. e.g.:
+```js
+const opentelemetry = require('@opentelemetry/api');
+
+const tracer = opentelemetry.trace.getTracer();
+await tracer.startActiveSpan("calculatePrice", async (span) => {
+ totalUsd = await calculatePrice(productIds);
+ span.end();
+});
+```
+
+## Deploy and test
+1. Deploy your function using firebase deploy --only functions
+2. Seed Firestore with mock data.
+3. Send callable request to the deployed function, e.g.:
+```
+$ curl -X POST -H "content-type: application/json" https:// -d '{ "data": ... }'
+```

2nd-gen/instrument-with-opentelemetry/firebase.json

@@ -0,0 +1,17 @@
+{
+ "functions": {
+ "source": "functions"
+ },
+ "emulators": {
+ "functions": {
+ "port": 5001
+ },
+ "firestore": {
+ "port": 8080
+ },
+ "ui": {
+ "enabled": true
+ },
+ "singleProjectMode": true
+ }
+}

2nd-gen/instrument-with-opentelemetry/functions/index.js

@@ -0,0 +1,63 @@
+const {onCall} = require("firebase-functions/v2/https");
+const logger = require("firebase-functions/logger");
+const {initializeApp} = require('firebase-admin/app');
+const {getFirestore} = require('firebase-admin/firestore');
+const opentelemetry = require('@opentelemetry/api');
+const {Timer} = require("./timer");
+
+initializeApp();
+const db = getFirestore();
+
+function sliceIntoChunks(arr, chunkSize) {
+ const res = [];
+ for (let i = 0; i < arr.length; i += chunkSize) {
+ const chunk = arr.slice(i, i + chunkSize);
+ res.push(chunk);
+ }
+ return res;
+}
+
+async function calculatePrice(productIds) {
+ const timer = new Timer();
+ let totalUsd = 0;
+ const products = await db.getAll(...productIds.map(id => db.doc(`products/${id}`)));
+ for (const product of products) {
+ totalUsd += product.data()?.usd || 0;
+ }
+ logger.info("calculatePrice", {calcPriceMs: timer.measureMs()});
+ return totalUsd;
+}
+
+async function calculateDiscount(productIds) {
+ const timer = new Timer();
+
+ let discountUsd = 0;
+ const processConcurrently = sliceIntoChunks(productIds, 10)
+ .map(async (productIds) => {
+ const discounts = await db.collection("discounts")
+ .where("products", "array-contains", productIds)
+ .get();
+ for (const discount of discounts.docs) {
+ discountUsd += discount.data().usd || 0;
+ }
+ });
+ await Promise.all(processConcurrently);
+ logger.info("calculateDiscount", {calcDiscountMs: timer.measureMs()});
+ return discountUsd;
+}
+
+exports.calculatetotal = onCall(async (req) => {
+ const {productIds} = req.data;
+
+ let totalUsd = 0;
+ const tracer = opentelemetry.trace.getTracer();
+ await tracer.startActiveSpan("calculatePrice", async (span) => {
+ totalUsd = await calculatePrice(productIds);
+ span.end();
+ });
+ await tracer.startActiveSpan("calculateDiscount", async (span) => {
+ totalUsd -= await calculateDiscount(productIds);
+ span.end();
+ });
+ return {totalUsd};
+});

2nd-gen/instrument-with-opentelemetry/functions/package.json

@@ -0,0 +1,29 @@
+{
+ "name": "functions",
+ "description": "Cloud Functions for Firebase",
+ "scripts": {
+ "lint": "eslint .",
+ "serve": "firebase emulators:start --only functions",
+ "shell": "firebase functions:shell",
+ "start": "npm run shell",
+ "deploy": "firebase deploy --only functions",
+ "logs": "firebase functions:log"
+ },
+ "engines": {
+ "node": "16"
+ },
+ "dependencies": {
+ "@google-cloud/opentelemetry-cloud-trace-exporter": "^1.1.0",
+ "@google-cloud/opentelemetry-cloud-trace-propagator": "^0.14.0",
+ "@opentelemetry/api": "^1.2.0",
+ "@opentelemetry/instrumentation": "^0.33.0",
+ "@opentelemetry/instrumentation-grpc": "^0.33.0",
+ "@opentelemetry/instrumentation-http": "^0.33.0",
+ "@opentelemetry/resource-detector-gcp": "^0.27.2",
+ "@opentelemetry/sdk-node": "^0.33.0",
+ "firebase-admin": "^10.2.0",
+ "firebase-functions": "^4.0.0",
+ "opentelemetry-instrumentation-express": "^0.29.0"
+ },
+ "private": true
+}

2nd-gen/instrument-with-opentelemetry/functions/timer.js

@@ -0,0 +1,10 @@
+exports.Timer = class {
+ constructor() {
+ this.start = process.hrtime.bigint();
+ }
+
+ measureMs() {
+ const duration = process.hrtime.bigint() - this.start;
+ return (duration / 1_000_000n).toString();
+ }
+};

2nd-gen/instrument-with-opentelemetry/functions/tracing.js

@@ -0,0 +1,40 @@
+const opentelemetry = require("@opentelemetry/sdk-node");
+const {TraceExporter} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
+const {HttpInstrumentation} = require("@opentelemetry/instrumentation-http");
+const {GrpcInstrumentation} = require("@opentelemetry/instrumentation-grpc");
+const {ExpressInstrumentation} = require('opentelemetry-instrumentation-express');
+const {gcpDetector} = require("@opentelemetry/resource-detector-gcp");
+const {
+ CloudPropagator,
+} = require("@google-cloud/opentelemetry-cloud-trace-propagator");
+
+
+// Only enable OpenTelemetry if the function is actually deployed.
+// Emulators don't reflect real-world latency"
+if (!process.env.FUNCTIONS_EMULATOR) {
+ const sdk = new opentelemetry.NodeSDK({
+ // Setup automatic instrumentation for
+ // http, grpc, and express modules.
+ instrumentations: [
+ new HttpInstrumentation(),
+ new GrpcInstrumentation(),
+ new ExpressInstrumentation(),
+ ],
+ // Make sure opentelemetry know about Cloud Trace http headers
+ // i.e. 'X-Cloud-Trace-Context'
+ textMapPropagator: new CloudPropagator(),
+ // Automatically detect and include span metadata when running
+ // in GCP, e.g. region of the function.
+ resourceDetectors: [gcpDetector],
+ // Export generated traces to Cloud Trace.
+ traceExporter: new TraceExporter(),
+ });
+
+ sdk.start();
+
+ // Ensure that generated traces are exported when the container is
+ // shutdown.
+ process.on("SIGTERM", async () => {
+ await sdk.shutdown();
+ });
+}