chore(instrumentation-undici): add example

Author: david-luna

examples/undici/README.md

@@ -0,0 +1,81 @@
+# Overview
+
+OpenTelemetry Undici Instrumentation allows the user to automatically collect trace data and export them to the backend of choice (we can use Zipkin or Jaeger for this example), to give observability to distributed systems.
+
+This is a simple example that demonstrates tracing HTTP request from client to server. The example
+shows key aspects of tracing such as
+
+- Root Span (on Client)
+- Child Span (on Client)
+- Child Span from a Remote Parent (on Server)
+- SpanContext Propagation (from Client to Server)
+- Span Events
+- Span Attributes
+
+## Installation
+
+```sh
+# from this directory
+npm install
+```
+
+Setup [Zipkin Tracing](https://zipkin.io/pages/quickstart.html)
+or
+Setup [Jaeger Tracing](https://www.jaegertracing.io/docs/latest/getting-started/#all-in-one)
+
+## Run the Application
+
+### Zipkin
+
+- Run the server
+
+   ```sh
+   # from this directory
+   npm run zipkin:server
+   ```
+
+- Run the client
+
+   ```sh
+   # from this directory
+   npm run zipkin:client
+   ```
+
+#### Zipkin UI
+
+`zipkin:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`).
+Go to Zipkin with your browser <http://localhost:9411/zipkin/traces/(your-trace-id)> (e.g <http://localhost:9411/zipkin/traces/4815c3d576d930189725f1f1d1bdfcc6>)
+
+<p align="center"><img src="./images/zipkin-ui.png?raw=true"/></p>
+
+### Jaeger
+
+- Run the server
+
+   ```sh
+   # from this directory
+   npm run jaeger:server
+   ```
+
+- Run the client
+
+   ```sh
+   # from this directory
+   npm run jaeger:client
+   ```
+
+#### Jaeger UI
+
+`jaeger:server` script should output the `traceid` in the terminal (e.g `traceid: 4815c3d576d930189725f1f1d1bdfcc6`).
+Go to Jaeger with your browser <http://localhost:16686/trace/(your-trace-id)> (e.g <http://localhost:16686/trace/4815c3d576d930189725f1f1d1bdfcc6>)
+
+<p align="center"><img src="images/jaeger-ui.png?raw=true"/></p>
+
+## Useful links
+
+- For more information on OpenTelemetry, visit: <https://opentelemetry.io/>
+- For more information on OpenTelemetry for Node.js, visit: <https://github.com/open-telemetry/opentelemetry-js/tree/main/packages/opentelemetry-sdk-trace-node>
+
+## LICENSE
+
+Apache License 2.0

examples/undici/client.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const undici = require('undici');
+const tracer = require('./tracer')('example-undici-client');
+
+/** A function which makes requests and handles response. */
+async function makeRequests(type) {
+  tracer.startActiveSpan('makeRequests with global fetch', async (span) => {
+      const fetchResponse = await fetch('localhost:8080/helloworld');    
+      console.log('response with global fetch: ' + await fetchResponse.text());
+
+      const undiciResponse = await undici.fetch('localhost:8080/helloworld');
+      console.log('response with undici fetch: ' + await undiciResponse.text());
+      span.end();
+  });
+
+  // The process must live for at least the interval past any traces that
+  // must be exported, or some risk being lost if they are recorded after the
+  // last export.
+  console.log('Sleeping 5 seconds before shutdown to ensure all records are flushed.');
+  setTimeout(() => { console.log('Completed.'); }, 5000);
+}
+
+makeRequests();

examples/undici/docker-compose.yml

@@ -0,0 +1,21 @@
+version: '3.7'
+
+services:
+  jaeger:
+    image: jaegertracing/all-in-one
+    ports:
+      - "16686:16686"
+      - "4318:4318"
+    environment:
+      - LOG_LEVEL=debug
+    networks:
+      - undici-example
+  zipkin:
+    image: openzipkin/zipkin
+    container_name: zipkin
+    ports:
+      # Port used for the Zipkin UI and HTTP Api
+      - 9411:9411
+
+networks:
+  undici-example:

examples/undici/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "undici-example",
+  "private": true,
+  "version": "0.46.0",
+  "description": "Example of Undici integration with OpenTelemetry",
+  "main": "index.js",
+  "scripts": {
+    "docker:start": "docker compose -f .docker-compose.yml up -d",
+    "docker:stop": "docker compose -f ./docker-compose.yml down",
+    "zipkin:server": "cross-env EXPORTER=zipkin node ./server.js",
+    "zipkin:client": "cross-env EXPORTER=zipkin node ./client.js",
+    "jaeger:server": "cross-env EXPORTER=jaeger node ./server.js",
+    "jaeger:client": "cross-env EXPORTER=jaeger node ./client.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://[email protected]/open-telemetry/opentelemetry-js.git"
+  },
+  "keywords": [
+    "opentelemetry",
+    "undici",
+    "fetch",
+    "tracing"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "author": "OpenTelemetry Authors",
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/open-telemetry/opentelemetry-js/issues"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.3.0",
+    "@opentelemetry/exporter-zipkin": "1.19.0",
+    "@opentelemetry/instrumentation": "0.46.0",
+    "@opentelemetry/instrumentation-undici": "0.46.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "0.46.0",
+    "@opentelemetry/resources": "1.19.0",
+    "@opentelemetry/sdk-trace-base": "1.19.0",
+    "@opentelemetry/sdk-trace-node": "1.19.0",
+    "@opentelemetry/semantic-conventions": "1.19.0"
+  },
+  "homepage": "https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/undici",
+  "devDependencies": {
+    "cross-env": "^6.0.0"
+  }
+}

examples/undici/server.js

@@ -0,0 +1,45 @@
+'use strict';
+
+const api = require('@opentelemetry/api');
+const tracer = require('./tracer')('example-undici-server');
+const http = require('http');
+
+/** Starts a HTTP server that receives requests on sample server port. */
+function startServer(port) {
+  // Creates a server
+  const server = http.createServer(handleRequest);
+  // Starts the server
+  server.listen(port, (err) => {
+    if (err) {
+      throw err;
+    }
+    console.log(`Node HTTP listening on ${port}`);
+  });
+}
+
+/** A function which handles requests and send response. */
+function handleRequest(request, response) {
+  const currentSpan = api.trace.getActiveSpan();
+  // display traceid in the terminal
+  const traceId = currentSpan.spanContext().traceId;
+  console.log(`traceId: ${traceId}`);
+  const span = tracer.startSpan('handleRequest', {
+    kind: 1, // server
+    attributes: { key: 'value' },
+  });
+  // Annotate our span to capture metadata about the operation
+  span.addEvent('invoking handleRequest');
+
+  const body = [];
+  request.on('error', (err) => console.log(err));
+  request.on('data', (chunk) => body.push(chunk));
+  request.on('end', () => {
+    // deliberately sleeping to mock some action.
+    setTimeout(() => {
+      span.end();
+      response.end('Hello World!');
+    }, 2000);
+  });
+}
+
+startServer(8080);

examples/undici/tracer.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const opentelemetry = require('@opentelemetry/api');
+const { registerInstrumentations } = require('@opentelemetry/instrumentation');
+const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
+const { Resource } = require('@opentelemetry/resources');
+const { SemanticResourceAttributes } = require('@opentelemetry/semantic-conventions');
+const { SimpleSpanProcessor } = require('@opentelemetry/sdk-trace-base');
+const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-proto');
+const { ZipkinExporter } = require('@opentelemetry/exporter-zipkin');
+const { UndiciInstrumentation } = require('@opentelemetry/instrumentation-undici');
+
+const EXPORTER = process.env.EXPORTER || '';
+
+module.exports = (serviceName) => {
+  const provider = new NodeTracerProvider({
+    resource: new Resource({
+      [SemanticResourceAttributes.SERVICE_NAME]: serviceName,
+    }),
+  });
+
+  let exporter;
+  if (EXPORTER.toLowerCase().startsWith('z')) {
+    exporter = new ZipkinExporter();
+  } else {
+    exporter = new OTLPTraceExporter();
+  }
+
+  provider.addSpanProcessor(new SimpleSpanProcessor(exporter));
+
+  // Initialize the OpenTelemetry APIs to use the NodeTracerProvider bindings
+  provider.register();
+
+  registerInstrumentations({
+    // // when boostraping with lerna for testing purposes
+    instrumentations: [
+      new UndiciInstrumentation(),
+    ],
+  });
+
+  return opentelemetry.trace.getTracer('undici-example');
+};

experimental/packages/opentelemetry-instrumentation-undici/README.md

@@ -15,7 +15,7 @@ npm install --save @opentelemetry/instrumentation-undici
 
 ## Usage
 
-OpenTelemetry HTTP Instrumentation allows the user to automatically collect trace data and export them to their backend of choice, to give observability to distributed systems.
+OpenTelemetry Undici/fetch Instrumentation allows the user to automatically collect trace data and export them to their backend of choice, to give observability to distributed systems.
 
 To load a specific instrumentation (Undici in this case), specify it in the Node Tracer's configuration.
 
@@ -42,7 +42,7 @@ registerInstrumentations({
 <!-- TODO: -->
 See [examples/http](https://github.com/open-telemetry/opentelemetry-js/tree/main/examples/fetch) for a short example.
 
-### Fetch instrumentation Options
+### Undici/Fetch instrumentation Options
 
 <!-- TODO: check PR description about config -->